BGAPI2 Interface Functions

Functions related to the GenICam Interface (USB or GigE transport layer)
A System (GenTL producer) can connect devices through the transport layer via interfaces. An interface can be a physical interface such as an ethernet network adapter or a logical interface such as an USB port. The Interface module provides functions to open/close interfaces, get informations like the ID and name of an interface and retrieve the devices accessable through each interface. More...

Typedefs

typedef struct BGAPI2_Interface BGAPI2_Interface
 Struct for pointers of type Interface. More...
 
typedef void(BGAPI2CALL * BGAPI2_PnPEventHandler) (void *callBackOwner, BGAPI2_PnPEvent *pnpEvent)
 Declaration for callback functions for BGAPI2_PnPEventHandler. More...
 

Functions

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_Open (BGAPI2_Interface *iface)
 Opens an interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_IsOpen (BGAPI2_Interface *iface, bo_bool *is_open)
 Checks the open state of a interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_UpdateDeviceList (BGAPI2_Interface *iface, bo_bool *changed, bo_uint64 timeout)
 Updates the list of devices on the interface and creates an object for each found device. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetDevice (BGAPI2_Interface *iface, bo_uint index, BGAPI2_Device **device)
 Get a pointer to the device with supplied index. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNumDevices (BGAPI2_Interface *iface, bo_uint *count_devices)
 Returns count of devices on interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetParent (BGAPI2_Interface *iface, BGAPI2_System **parent)
 Returns the parent object (GenTL producer) which the interface belongs to. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_Close (BGAPI2_Interface *iface)
 Closes an interfaces. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNode (BGAPI2_Interface *iface, const char *name, BGAPI2_Node **node)
 Get a named node of the interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNodeTree (BGAPI2_Interface *iface, BGAPI2_NodeMap **node_tree)
 Get the node tree of the interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNodeList (BGAPI2_Interface *iface, BGAPI2_NodeMap **node_list)
 Get the node list of the interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_SetPnPEventMode (BGAPI2_Interface *iface, BGAPI2_EventMode event_mode)
 Set the event mode (polling, callback, off) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetPnPEventMode (BGAPI2_Interface *iface, BGAPI2_EventMode *event_mode)
 Returns the current event mode setting. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_CreatePnPEvent (BGAPI2_PnPEvent **pnp_event)
 Creates a structure to store pnp events retrieved via BGAPI2_Interface_GetPnPEvent More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_ReleasePnPEvent (BGAPI2_PnPEvent *pnp_event)
 Destroys a pnp event structure. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetPnPEvent (BGAPI2_Interface *iface, BGAPI2_PnPEvent *pnp_event, bo_uint64 timeout)
 Polls for event information until timeout is reached. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_CancelGetPnPEvent (BGAPI2_Interface *iface)
 Cancels an actively running BGAPI2_Interface_GetPnPEvent More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_RegisterPnPEventHandler (BGAPI2_Interface *iface, void *callback_owner, BGAPI2_PnPEventHandler pnp_event_handler)
 Register one callback function to handle all pnp events of the interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetID (BGAPI2_Interface *iface, char *ID, bo_uint64 *string_length)
 Returns the identifier of the interface. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetDisplayName (BGAPI2_Interface *iface, char *display_name, bo_uint64 *string_length)
 Returns the "user friendly" display name of interface, can be called on an interface which is not open. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetTLType (BGAPI2_Interface *iface, char *tl_type, bo_uint64 *string_length)
 Returns the transport layer name of interface, can be called on an interface which is not open. More...
 

Detailed Description

Functions related to the GenICam Interface (USB or GigE transport layer)
A System (GenTL producer) can connect devices through the transport layer via interfaces. An interface can be a physical interface such as an ethernet network adapter or a logical interface such as an USB port. The Interface module provides functions to open/close interfaces, get informations like the ID and name of an interface and retrieve the devices accessable through each interface.

Typedef Documentation

◆ BGAPI2_Interface

Struct for pointers of type Interface.

◆ BGAPI2_PnPEventHandler

typedef void(BGAPI2CALL * BGAPI2_PnPEventHandler) (void *callBackOwner, BGAPI2_PnPEvent *pnpEvent)

Declaration for callback functions for BGAPI2_PnPEventHandler.

Function Documentation

◆ BGAPI2_Interface_Open()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_Open ( BGAPI2_Interface iface)

Opens an interface.

Parameters
[in]ifacePointer to the interface obtained from BGAPI2_System_GetInterface()
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_RESOURCE_IN_USEInterface is already opened
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetInterface

◆ BGAPI2_Interface_IsOpen()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_IsOpen ( BGAPI2_Interface iface,
bo_bool *  is_open 
)

Checks the open state of a interface.

Parameters
[in]ifacePointer to the interface
[out]is_openResult variable for open state of interface
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_Interface_Open
BGAPI2_System_GetInterface

◆ BGAPI2_Interface_UpdateDeviceList()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_UpdateDeviceList ( BGAPI2_Interface iface,
bo_bool *  changed,
bo_uint64  timeout 
)

Updates the list of devices on the interface and creates an object for each found device.

Parameters
[in]ifacePointer to the interface
[out]changedTrue if devices have changed since last call, otherwise false
[in]timeoutMaximum time in milliseconds to search for devices
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read device infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_GetDevice()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetDevice ( BGAPI2_Interface iface,
bo_uint  index,
BGAPI2_Device **  device 
)

Get a pointer to the device with supplied index.

Parameters
[in]ifacePointer to the interface
[in]indexIndex in the device list
[out]deviceDevice pointer
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read device infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_Interface_UpdateDeviceList
BGAPI2_Device_Open

◆ BGAPI2_Interface_GetNumDevices()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNumDevices ( BGAPI2_Interface iface,
bo_uint *  count_devices 
)

Returns count of devices on interface.

Parameters
[in]ifaceInstance of interface
[out]count_devicesVariable for count of devices on interface
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read device infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_GetParent()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetParent ( BGAPI2_Interface iface,
BGAPI2_System **  parent 
)

Returns the parent object (GenTL producer) which the interface belongs to.

Parameters
[in]ifacePointer to the interface
[out]parentParent object
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_Close()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_Close ( BGAPI2_Interface iface)

Closes an interfaces.

Parameters
[in]ifacePointer to the interface
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_GetNode()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNode ( BGAPI2_Interface iface,
const char *  name,
BGAPI2_Node **  node 
)

Get a named node of the interface.

Parameters
[in]ifacePointer to the interface
[in]nameNode name
[out]nodePointer to store node value
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_GetNodeTree()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNodeTree ( BGAPI2_Interface iface,
BGAPI2_NodeMap **  node_tree 
)

Get the node tree of the interface.

Parameters
[in]ifacePointer to the interface
[out]node_treePointer to store node tree
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_NOT_AVAILABLEError for missing root node
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_GetNodeList()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetNodeList ( BGAPI2_Interface iface,
BGAPI2_NodeMap **  node_list 
)

Get the node list of the interface.

Parameters
[in]ifacePointer to the interface
[out]node_listPointer to store node list
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_NOT_AVAILABLEError for missing root node
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_SetPnPEventMode()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_SetPnPEventMode ( BGAPI2_Interface iface,
BGAPI2_EventMode  event_mode 
)

Set the event mode (polling, callback, off)

Parameters
[in]ifacePointer to the interface
[in]event_modeEvent mode for the PnP events of interface
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_EventMode

◆ BGAPI2_Interface_GetPnPEventMode()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetPnPEventMode ( BGAPI2_Interface iface,
BGAPI2_EventMode event_mode 
)

Returns the current event mode setting.

Parameters
[in]ifacePointer to the interface
[out]event_modePointer for event mode
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_EventMode

◆ BGAPI2_CreatePnPEvent()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_CreatePnPEvent ( BGAPI2_PnPEvent **  pnp_event)

Creates a structure to store pnp events retrieved via BGAPI2_Interface_GetPnPEvent

Parameters
[in,out]pnp_eventPointer to a struct which can store events
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_Interface_GetPnPEvent

◆ BGAPI2_ReleasePnPEvent()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_ReleasePnPEvent ( BGAPI2_PnPEvent pnp_event)

Destroys a pnp event structure.

Parameters
[in]pnp_eventPointer to a event struct
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_CreatePnPEvent

◆ BGAPI2_Interface_GetPnPEvent()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetPnPEvent ( BGAPI2_Interface iface,
BGAPI2_PnPEvent pnp_event,
bo_uint64  timeout 
)

Polls for event information until timeout is reached.

This function is only used if BGAPI2_EventMode is set to EVENTMODE_POLLING

Parameters
[in]ifacePointer to interface
[in,out]pnp_eventPointer for event structure created with BGAPI2_CreatePnPEvent
[in]timeoutMaximum time to wait for events, if set to -1 wait indefinitely
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERROR
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_EventMode
BGAPI2_CreatePnPEvent
BGAPI2_Interface_CancelGetPnPEvent

◆ BGAPI2_Interface_CancelGetPnPEvent()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_CancelGetPnPEvent ( BGAPI2_Interface iface)

Cancels an actively running BGAPI2_Interface_GetPnPEvent

Parameters
[in]ifacePointer to the interface
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_LOWLEVEL_ERRORInternal error (on kill event)
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_RegisterPnPEventHandler()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_RegisterPnPEventHandler ( BGAPI2_Interface iface,
void *  callback_owner,
BGAPI2_PnPEventHandler  pnp_event_handler 
)

Register one callback function to handle all pnp events of the interface.

This function is only used if BGAPI2_EventMode is set to EVENTMODE_EVENT_HANDLER. It starts internal an thread to retrieve and queue events

Parameters
[in]ifacePointer to interface
[in]callback_ownerData, context pointer for use in callback function
[in]pnp_event_handlerPointer to callback function from type BGAPI2_PnPEventHandler
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORCould not start event thread
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_EventMode
Todo:
check... what is the callback owner???

◆ BGAPI2_Interface_GetID()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetID ( BGAPI2_Interface iface,
char *  ID,
bo_uint64 *  string_length 
)

Returns the identifier of the interface.

The BGAPI2 C-Interface utilizes a two step process for the retrieval of strings.

1. Get the size of the string: For the first call to BGAPI2_Interface_GetID, you need to supply the function with an null-pointer for the parameter ID. In this case the function will return you the size of the ID. You can now use this size to set up the pointer with the right size.

2. Get the actual ID string: Now you can supply the function with the right sized pointer you created for the ID. In that case, the function will return the ID into your provided memory pointer.

Alternatively, to save the extra call to get the size, you can supply the function with a larger memory pointer than required (e.g. 1024 byte).

Parameters
[in]ifacePointer to interface
[in,out]IDNullptr to get string length or pointer to store result
[in,out]string_lengthResult size, length of version string (including string end zero)
Return values
BGAPI2_RESULT_SUCCESSNo error.
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDProducer not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read producer interface infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_Interface_GetDisplayName()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetDisplayName ( BGAPI2_Interface iface,
char *  display_name,
bo_uint64 *  string_length 
)

Returns the "user friendly" display name of interface, can be called on an interface which is not open.

Parameters
[in]ifaceInstance of interface
[in,out]display_nameNullptr to get string length or pointer to store result
[in,out]string_lengthResult size, length of version string (including string end zero)
Return values
BGAPI2_RESULT_SUCCESSNo error.
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDProducer not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read interface infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_Interface_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_Interface_GetTLType()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_GetTLType ( BGAPI2_Interface iface,
char *  tl_type,
bo_uint64 *  string_length 
)

Returns the transport layer name of interface, can be called on an interface which is not open.

Parameters
[in]ifaceInstance of interface
[in,out]tl_typeNullptr to get string length or pointer to store result
[in,out]string_lengthResult size, length of version string (including string end zero)
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read interface infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_Interface_GetID for detail how to retrieve strings with unknown size