BGAPI2 System Functions

Functions related to the GenICam System or Producer
The System is the abstraction for an GenTL Producer. The System module provides functions to find, load/unload and open/close GenTL producers. There are also functions to retrieve informations like ID, vendor or name from a producer and to retrieve the the accessable Interfaces. More...

Typedefs

typedef struct BGAPI2_System BGAPI2_System
 Struct for pointers of type System. More...
 

Functions

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_UpdateSystemList ()
 Search for GenTL producers in the current directory and in GENICAM_GENTLxx_PATH. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_UpdateSystemListFromPath (const char *producer_path)
 Search for GenTL producers only in the path specified. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_LoadSystemFromPath (const char *file_path, BGAPI2_System **system)
 Creates a system (GenTL producer) object, specified by filepath before opening it. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_GetNumSystems (bo_uint *count)
 Returns the number of systems (GenTL Producers) found by BGAPI2_UpdateSystemList() More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_GetSystem (bo_uint index, BGAPI2_System **system)
 Get a pointer to the System (GenTL Producer) specified by the index. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_Open (BGAPI2_System *system)
 Opens a system (GenTL producer) to work with it. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_IsOpen (BGAPI2_System *system, bo_bool *is_open)
 Check if the system (GenTL producer) is opened. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_UpdateInterfaceList (BGAPI2_System *system, bo_bool *changed, bo_uint64 timeout)
 Updates the list of of accessable interfaces and creates an object for each. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetInterface (BGAPI2_System *system, bo_uint index, BGAPI2_Interface **iface)
 Get a pointer to the interface with the specified index. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNumInterfaces (BGAPI2_System *system, bo_uint *count_interfaces)
 Returns the number of accessable interfaces. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_Close (BGAPI2_System *system)
 Closes a system (producer), you need to call BGAPI2_ReleaseSystem to unload the library. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_ReleaseSystem (BGAPI2_System *system)
 Release a system (GenTL producer) specified. You need to call BGAPI2_System_Close first! More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNode (BGAPI2_System *system, const char *name, BGAPI2_Node **node)
 Get the named node (feature) of given map of system. More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNodeTree (BGAPI2_System *system, BGAPI2_NodeMap **node_tree)
 Get a tree of all system nodes (features) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNodeList (BGAPI2_System *system, BGAPI2_NodeMap **node_list)
 Get a list of all system nodes (features) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetID (BGAPI2_System *system, char *ID, bo_uint64 *string_length)
 Returns the identifier of the system (GenTL producer). More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetVendor (BGAPI2_System *system, char *vendor, bo_uint64 *string_length)
 Returns the vendor of the system (GenTL producer) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetModel (BGAPI2_System *system, char *model, bo_uint64 *string_length)
 Returns the name (model) of the system (GenTL producer) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetVersion (BGAPI2_System *system, char *version, bo_uint64 *string_length)
 Returns the version of the system (GenTL producer) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetTLType (BGAPI2_System *system, char *tl_type, bo_uint64 *string_length)
 Returns the name of the transport layer of the system (GenTL producer) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetFileName (BGAPI2_System *system, char *name, bo_uint64 *string_length)
 Returns the file name of the system (GenTL producer) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetPathName (BGAPI2_System *system, char *path_name, bo_uint64 *string_length)
 Returns the complete path name of the system (GenTL producer) More...
 
BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetDisplayName (BGAPI2_System *system, char *display_name, bo_uint64 *string_length)
 Returns the "user friendly" display name of the system (GenTL producer) More...
 

Detailed Description

Functions related to the GenICam System or Producer
The System is the abstraction for an GenTL Producer. The System module provides functions to find, load/unload and open/close GenTL producers. There are also functions to retrieve informations like ID, vendor or name from a producer and to retrieve the the accessable Interfaces.

Typedef Documentation

◆ BGAPI2_System

typedef struct BGAPI2_System BGAPI2_System

Struct for pointers of type System.

Function Documentation

◆ BGAPI2_UpdateSystemList()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_UpdateSystemList ( )

Search for GenTL producers in the current directory and in GENICAM_GENTLxx_PATH.

This function creates an System object for each found producer. GenTL producer are files with the .cti extension and are synonymous with the system. After the list of systems is updated, you can use BGAPI2_GetNumSystems() function to get the number of producers found and the BGAPI2_GetSystem() function to open a specific system to work with it

Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_LOWLEVEL_ERRORAn error
See also
BGAPI2_ReleaseSystem
BGAPI2_GetSystem
BGAPI2_System_Open

◆ BGAPI2_UpdateSystemListFromPath()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_UpdateSystemListFromPath ( const char *  producer_path)

Search for GenTL producers only in the path specified.

This function creates an System object for each found producer. GenTL producer are files with the .cti extension and are synonymous with the system. After the list of systems is updated, you can use BGAPI2_GetNumSystems() function to get the number of producers found and the BGAPI2_GetSystem() function to open a specific system to work with it

Parameters
[in]producer_pathPath where producers should be searched
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error
BGAPI2_RESULT_LOWLEVEL_ERRORAn error
See also
BGAPI2_System_Close
BGAPI2_ReleaseSystem
BGAPI2_GetSystem
BGAPI2_System_Open

◆ BGAPI2_LoadSystemFromPath()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_LoadSystemFromPath ( const char *  file_path,
BGAPI2_System **  system 
)

Creates a system (GenTL producer) object, specified by filepath before opening it.

This function creates an System object for each found producer. You need to create and open a producer before you can get any information about it. Once a producer is created it will not be counted by subsequent BGAPI2_GetNumSystems() calls!

Parameters
[in]file_pathPath and Filename of the producer to create
[out]systemReference to a pointer to the system (producer)
Return values
BGAPI2_RESULT_SUCCESSNo error
See also
BGAPI2_System_Open
BGAPI2_System_Close
BGAPI2_ReleaseSystem

◆ BGAPI2_GetNumSystems()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_GetNumSystems ( bo_uint *  count)

Returns the number of systems (GenTL Producers) found by BGAPI2_UpdateSystemList()

Parameters
[out]countCount of found GenTL Producer
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_GetSystem()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_GetSystem ( bo_uint  index,
BGAPI2_System **  system 
)

Get a pointer to the System (GenTL Producer) specified by the index.

You need to open a System before you can get any information about it. Once a System is opened it will not be counted by subsequent BGAPI2_GetNumSystems calls!

Parameters
[in]indexIndex of the system (producer) to use
[out]systemReference to a pointer to the system (producer)
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
BGAPI2_RESULT_RESOURCE_IN_USEProducer already loaded
BGAPI2_RESULT_LOWLEVEL_ERRORError in producer (functions not found)
See also
BGAPI2_System_Open
BGAPI2_System_Close
BGAPI2_ReleaseSystem

◆ BGAPI2_System_Open()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_Open ( BGAPI2_System system)

Opens a system (GenTL producer) to work with it.

Parameters
[in]systemPointer to the system (producer) obtained from BGAPI2_GetSystem
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_RESOURCE_IN_USEAlready opened
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_GetSystem
BGAPI2_System_Close

◆ BGAPI2_System_IsOpen()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_IsOpen ( BGAPI2_System system,
bo_bool *  is_open 
)

Check if the system (GenTL producer) is opened.

Parameters
[in]systemPointer to the system (producer)
[out]is_openPointer to the result variable
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_Open
BGAPI2_System_Close

◆ BGAPI2_System_UpdateInterfaceList()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_UpdateInterfaceList ( BGAPI2_System system,
bo_bool *  changed,
bo_uint64  timeout 
)

Updates the list of of accessable interfaces and creates an object for each.

Parameters
[in]systemPointer to the system (producer)
[out]changedFlag if interfaces are changed since last call
[in]timeoutMaximum time in milliseconds to search for interfaces
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_System_GetInterface()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetInterface ( BGAPI2_System system,
bo_uint  index,
BGAPI2_Interface **  iface 
)

Get a pointer to the interface with the specified index.

You need to call BGAPI2_System_UpdateInterfaceList() first! A System (GenTL producer) connects devices through a transport layer via an interface. The Interface can be a physical interface such as an ethernet network adapter or a logical interface such as an USB port.

Parameters
[in]systemPointer to the system (producer)
[in]indexIndex in the interface list
[out]ifaceDevice instance
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_UpdateInterfaceList

◆ BGAPI2_System_GetNumInterfaces()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNumInterfaces ( BGAPI2_System system,
bo_uint *  count_interfaces 
)

Returns the number of accessable interfaces.

Parameters
[in]systemPointer to the system (producer)
[out]count_interfacesNumber of interfaces
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_NOT_INITIALIZEDInterface not initialized
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetInterface

◆ BGAPI2_System_Close()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_Close ( BGAPI2_System system)

Closes a system (producer), you need to call BGAPI2_ReleaseSystem to unload the library.

Parameters
[in]systemPointer to the system (producer)
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_ERRORInternal error (init failed)
BGAPI2_RESULT_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_Open
BGAPI2_ReleaseSystem

◆ BGAPI2_ReleaseSystem()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_ReleaseSystem ( BGAPI2_System system)

Release a system (GenTL producer) specified. You need to call BGAPI2_System_Close first!

Parameters
[in]systemPointer to the system (producer)
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
BGAPI2_RESULT_NOT_INITIALIZEDError producer was not loaded
BGAPI2_RESULT_ERRORInternal Error (nullptr as system)
BGAPI2_RESULT_LOWLEVEL_ERRORError on close of producer
See also
BGAPI2_System_Open
BGAPI2_System_Close

◆ BGAPI2_System_GetNode()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNode ( BGAPI2_System system,
const char *  name,
BGAPI2_Node **  node 
)

Get the named node (feature) of given map of system.

Parameters
[in]systemPointer to the system (producer)
[in]nameName of the node to return
[out]nodeVariable for returned node value
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_System_GetNodeTree()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNodeTree ( BGAPI2_System system,
BGAPI2_NodeMap **  node_tree 
)

Get a tree of all system nodes (features)

Parameters
[in]systemPointer to the system (producer)
[out]node_treeVariable for the returned node tree
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_NOT_AVAILABLEError for missing root node
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_System_GetNodeList()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetNodeList ( BGAPI2_System system,
BGAPI2_NodeMap **  node_list 
)

Get a list of all system nodes (features)

Parameters
[in]systemPointer to the system (producer)
[out]node_listVariable for the returned node map
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_NOT_AVAILABLEError for missing root node
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_System_GetID()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetID ( BGAPI2_System system,
char *  ID,
bo_uint64 *  string_length 
)

Returns the identifier of the system (GenTL producer).

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_System_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]systemPointer to the system (producer)
[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_INVALID_PARAMETERError for invalid parameters

◆ BGAPI2_System_GetVendor()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetVendor ( BGAPI2_System system,
char *  vendor,
bo_uint64 *  string_length 
)

Returns the vendor of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[in,out]vendorNullptr 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_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_System_GetModel()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetModel ( BGAPI2_System system,
char *  model,
bo_uint64 *  string_length 
)

Returns the name (model) of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[in,out]modelNullptr 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_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_System_GetVersion()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetVersion ( BGAPI2_System system,
char *  version,
bo_uint64 *  string_length 
)

Returns the version of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[in,out]versionNullptr 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_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_System_GetTLType()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetTLType ( BGAPI2_System system,
char *  tl_type,
bo_uint64 *  string_length 
)

Returns the name of the transport layer of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[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_LOWLEVEL_ERRORCan't read producer infos
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_System_GetFileName()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetFileName ( BGAPI2_System system,
char *  name,
bo_uint64 *  string_length 
)

Returns the file name of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[out]nameNullptr to get string length or pointer to store result
[out]string_lengthResult size, length of name
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_System_GetPathName()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetPathName ( BGAPI2_System system,
char *  path_name,
bo_uint64 *  string_length 
)

Returns the complete path name of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[out]path_nameNullptr to get string length or pointer to store result
[out]string_lengthResult size, length of path name
Return values
BGAPI2_RESULT_SUCCESSNo error
BGAPI2_RESULT_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size

◆ BGAPI2_System_GetDisplayName()

BGAPI2_C_DECL BGAPI2_RESULT BGAPI2CALL BGAPI2_System_GetDisplayName ( BGAPI2_System system,
char *  display_name,
bo_uint64 *  string_length 
)

Returns the "user friendly" display name of the system (GenTL producer)

Parameters
[in]systemPointer to the system (producer)
[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_INVALID_PARAMETERError for invalid parameters
See also
BGAPI2_System_GetID for detail how to retrieve strings with unknown size