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
typedef struct BGAPI2_Interface 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] iface Pointer to the interface obtained from BGAPI2_System_GetInterface()
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Interface not initialized BGAPI2_RESULT_RESOURCE_IN_USE Interface is already opened BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [out] is_open Result variable for open state of interface
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error for invalid parameters
◆ 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] iface Pointer to the interface [out] changed True if devices have changed since last call, otherwise false [in] timeout Maximum time in milliseconds to search for devices
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Interface not initialized BGAPI2_RESULT_LOWLEVEL_ERROR Can't read device infos BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [in] index Index in the device list [out] device Device pointer
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Interface not initialized BGAPI2_RESULT_LOWLEVEL_ERROR Can't read device infos BGAPI2_RESULT_INVALID_PARAMETER Error for invalid parameters
◆ 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] iface Instance of interface [out] count_devices Variable for count of devices on interface
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Interface not initialized BGAPI2_RESULT_LOWLEVEL_ERROR Can't read device infos BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [out] parent Parent object
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error for invalid parameters
◆ BGAPI2_Interface_Close()
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_Close | ( | BGAPI2_Interface * | iface | ) |
Closes an interfaces.
- Parameters
-
[in] iface Pointer to the interface
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [in] name Node name [out] node Pointer to store node value
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [out] node_tree Pointer to store node tree
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_NOT_AVAILABLE Error for missing root node BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [out] node_list Pointer to store node list
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_NOT_AVAILABLE Error for missing root node BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [in] event_mode Event mode for the PnP events of interface
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to the interface [out] event_mode Pointer for event mode
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error 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_event Pointer to a struct which can store events
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error 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_event Pointer to a event struct
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to interface [in,out] pnp_event Pointer for event structure created with BGAPI2_CreatePnPEvent
[in] timeout Maximum time to wait for events, if set to -1 wait indefinitely
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR BGAPI2_RESULT_INVALID_PARAMETER Error for invalid parameters
◆ BGAPI2_Interface_CancelGetPnPEvent()
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_Interface_CancelGetPnPEvent | ( | BGAPI2_Interface * | iface | ) |
Cancels an actively running BGAPI2_Interface_GetPnPEvent
- Parameters
-
[in] iface Pointer to the interface
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_LOWLEVEL_ERROR Internal error (on kill event) BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to interface [in] callback_owner Data, context pointer for use in callback function [in] pnp_event_handler Pointer to callback function from type BGAPI2_PnPEventHandler
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR Could not start event thread BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Pointer to interface [in,out] ID Nullptr to get string length or pointer to store result [in,out] string_length Result size, length of version string (including string end zero)
- Return values
-
BGAPI2_RESULT_SUCCESS No error. BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Producer not initialized BGAPI2_RESULT_LOWLEVEL_ERROR Can't read producer interface infos BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Instance of interface [in,out] display_name Nullptr to get string length or pointer to store result [in,out] string_length Result size, length of version string (including string end zero)
- Return values
-
BGAPI2_RESULT_SUCCESS No error. BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Producer not initialized BGAPI2_RESULT_LOWLEVEL_ERROR Can't read interface infos BGAPI2_RESULT_INVALID_PARAMETER Error 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] iface Instance of interface [in,out] tl_type Nullptr to get string length or pointer to store result [in,out] string_length Result size, length of version string (including string end zero)
- Return values
-
BGAPI2_RESULT_SUCCESS No error BGAPI2_RESULT_ERROR Internal error (init failed) BGAPI2_RESULT_NOT_INITIALIZED Interface not initialized BGAPI2_RESULT_LOWLEVEL_ERROR Can't read interface infos BGAPI2_RESULT_INVALID_PARAMETER Error for invalid parameters
- See also
- BGAPI2_Interface_GetID for detail how to retrieve strings with unknown size