Logo
Programmer's Guide Baumer GAPI SDK Reference v2.10.0
Public Member Functions | Friends | List of all members
BGAPI2::Device Class Reference

The class Device is used to retrieve information (e.g. model, manufacturer, access modes) of the device (camera) and also to control the device. This class belongs to the BGAPI2 main classes. More...

#include <bgapi2_genicam.hpp>

Inheritance diagram for BGAPI2::Device:
BGAPI2::INode BGAPI2::Events::DeviceEventControl BGAPI2::Events::EventControl

Public Member Functions

void Open ()
 This function opens the device object and makes their functions available. Exceptions are the info-functions, which are already available before opening the device. More...
 
void OpenExclusive ()
 This function opens the device object exclusive and makes their functions available. Exceptions are the info-functions, which are already available before opening the device. More...
 
void OpenReadOnly ()
 This function opens the device object only for reading and make their functions available. Exceptions are the info-functions, which are already available before opening the device. More...
 
void Close ()
 This function closes the device object and releases the used resources. More...
 
bo_bool IsOpen ()
 This function delivers true, if the device is opened. More...
 
void StartStacking (bo_bool bReplaceMode)
 This function starts the stacked mode for write commands (control commands). See remarks. More...
 
void WriteStack ()
 This function writes the collected values to the device and stops the stacked mode. More...
 
void CancelStack ()
 This function drops the collected values and stops the stacked mode. More...
 
DataStreamListGetDataStreams ()
 This function delivers the data stream list of the device. More...
 
String GetID ()
 This function delivers the unique string identifier of the Device, which is used in the DeviceList. More...
 
String GetVendor ()
 This function delivers the name of the device vendor. More...
 
String GetModel ()
 This function delivers the name of the device. More...
 
String GetSerialNumber ()
 This function delivers the serial number of the device. More...
 
String GetTLType ()
 This function delivers the transport layer type of the Device. More...
 
String GetDisplayName ()
 This function delivers a meaningful name of the Device for display only. More...
 
String GetAccessStatus ()
 This function delivers the access mode to the device. If this function is used before opening the device, it provides the possible access mode. The following possibilities can occur before opening the device. More...
 
bo_uint64 GetPayloadSize ()
 If the device supports a streaming channel for data transfer, this function delivers the size of the expecting data block in bytes based on the current device settings and including all control data (e.g. chunk header). More...
 
NodeGetRemoteNode (String name)
 The remote functions of the Device class are used to get access to the features of the physical (remote) device. More...
 
NodeMapGetRemoteNodeTree ()
 The remote functions of the Device class are used to get access to the features of the physical (remote) device. More...
 
NodeMapGetRemoteNodeList ()
 The remote functions of the Device class are used to get access to the features of the physical (remote) device. More...
 
String GetRemoteConfigurationFile ()
 The remote functions of the Device class are used to get access to the features of the physical (remote) device. More...
 
void SetRemoteConfigurationFile (String sConfigFile)
 The remote functions of the Device class are used to get access to the features of the physical (remote) device. More...
 
bo_bool IsUpdateModeAvailable ()
 The update functions of the Device class are used to get access to firmware of the physical (remote) device. More...
 
bo_bool IsUpdateModeActive ()
 The update functions of the Device class are used to get access to firmware of the physical (remote) device. More...
 
void SetUpdateMode (bool bActive, String pcCustomKey)
 The update functions of the Device class are used to get access to firmware of the physical (remote) device. More...
 
NodeGetUpdateNode (String name)
 The update functions of the Device class are used to get access to the update features of the physical (remote) device. More...
 
NodeMapGetUpdateNodeTree ()
 The update functions of the Device class are used to get access to the update features of the physical (remote) device. More...
 
NodeMapGetUpdateNodeList ()
 The update functions of the Device class are used to get access to the update features of the physical (remote) device. More...
 
String GetUpdateConfigurationFile ()
 The update functions of the Device class are used to get access to the update features of the physical (remote) device. More...
 
InterfaceGetParent ()
 This function delivers the superordinate Interface object. More...
 
void * GetReserved ()
 Undocumented function.
 
- Public Member Functions inherited from BGAPI2::INode
NodeGetNode (String name)
 This function delivers a certain object of the Node list and provides the access to a node objcet without the detour across a NodeMap object. This function is functional identical to NodeMap::GetNode. More...
 
NodeMapGetNodeTree ()
 This function provides the features of a object derived from INode interface as tree structure in form of a NodeMap pointer. For a detailed description of the tree structure representation refer to the class description of NodeMap. More...
 
NodeMapGetNodeList ()
 This function provides the features of a object derived from INode interface as unstructured list in form of a NodeMap pointer. For a detailed description of the unstructured list representation refer to the class description of NodeMap. More...
 
- Public Member Functions inherited from BGAPI2::Events::DeviceEventControl
void RegisterDeviceEvent (EventMode eventMode)
 This function registers a DeviceEvent at an Device object to detect asynchronous events from the physical connected device. More...
 
void UnregisterDeviceEvent ()
 This function unregisters a DeviceEvent at an Device object. More...
 
bo_bool GetDeviceEvent (DeviceEvent *pDeviceEvent, bo_uint64 iTimeout)
 This function fetches a DeviceEvent from the Device object. More...
 
void CancelGetDeviceEvent ()
 This function cancels the current waiting operation on the GetDeviceEvent function. More...
 
void RegisterDeviceEventHandler (void *callBackOwner, DeviceEventHandler pFunc)
 Register a callback function which is called any time a new device event was received. More...
 
- Public Member Functions inherited from BGAPI2::Events::EventControl
EventMode GetEventMode ()
 This function delivers the current event mode setting. The event mode is controlled by the event register functions. See also enumeration Events::EventMode. More...
 
void * GetBase ()
 Undocumented function. More...
 

Friends

class DeviceList
 
class DataStreamList
 
class DataStream
 

Detailed Description

The class Device is used to retrieve information (e.g. model, manufacturer, access modes) of the device (camera) and also to control the device. This class belongs to the BGAPI2 main classes.

Definition at line 2678 of file bgapi2_genicam.hpp.

Member Function Documentation

◆ CancelStack()

BGAPI2::Device::CancelStack ( )

This function drops the collected values and stops the stacked mode.

Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NoDataExceptionThe stacked mode is not started or no control commands were written after calling the function Device::StartStacking.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ Close()

BGAPI2::Device::Close ( )

This function closes the device object and releases the used resources.

Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetAccessStatus()

BGAPI2::Device::GetAccessStatus ( )

This function delivers the access mode to the device. If this function is used before opening the device, it provides the possible access mode. The following possibilities can occur before opening the device.

If the function delivers with "RW" before opening, the device can be opened with one of the functions Device::Open or Device::OpenExclusive. If the function delivers with "RO" before opening, the device can be opend only with function Device::OpenReadOnly. If the function delivers with "NA" before opening, the device can not be opened. If the function delivers with "Unknown" before opening, the access mode could not be determined. The call to an open function may throw an exception. Is the device already opened, this function delivers the current access mode. The following variants can occur after opening the device. If the device was opened with the function Device::Open or Device::OpenExclusive, the function delivers "RW". If the device was opened with the function Device::OpenReadOnly, the function delivers "RO".

Returns
String "RW" - read and write access
String "RO" - only read access
String "NA" - No access, e.g. the device is not reachable (GEV).
String "Unknown" - The access mode could not be determined.
Exceptions
Exceptions::NotAvailableExceptionThe GenTL producer delivers an unexpected access mode.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetDataStreams()

BGAPI2::Device::GetDataStreams ( )

This function delivers the data stream list of the device.

Returns
DataStreamList* The pointer to the data stream list of the device.
Exceptions
Exceptions::NotInitializedExceptionThe interface object is not open.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.

◆ GetDisplayName()

BGAPI2::Device::GetDisplayName ( )

This function delivers a meaningful name of the Device for display only.

For Baumer devices this function delivers the value of the feature 'DeviceUserID'. If this feature is not available or empty the model name of the device is delivered instead.

Returns
String The meaningful name of the Device.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetID()

BGAPI2::Device::GetID ( )

This function delivers the unique string identifier of the Device, which is used in the DeviceList.

Returns
String The unique string identifier.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.

◆ GetModel()

BGAPI2::Device::GetModel ( )

This function delivers the name of the device.

Returns
String The name of the device.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetParent()

BGAPI2::Device::GetParent ( )

This function delivers the superordinate Interface object.

Returns
Interface* A pointer to the superordinate Interface object.

◆ GetPayloadSize()

BGAPI2::Device::GetPayloadSize ( )

If the device supports a streaming channel for data transfer, this function delivers the size of the expecting data block in bytes based on the current device settings and including all control data (e.g. chunk header).

This function is mainly used to determine the size of image buffers to allocate. See also the functions DataStream::GetPayloadSize and DataStream::GetDefinesPayloadSize.

Returns
bo_uint64 The size of the expected data block in bytes.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThis function is not supported.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetRemoteConfigurationFile()

BGAPI2::Device::GetRemoteConfigurationFile ( )

The remote functions of the Device class are used to get access to the features of the physical (remote) device.

This function delivers the GenICam XML File of the remote device.

Returns
String The GenICam XML file of the remote device.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.

◆ GetRemoteNode()

BGAPI2::Device::GetRemoteNode ( String  name)

The remote functions of the Device class are used to get access to the features of the physical (remote) device.

This function allows the access to a requested feature of the remote device. If the requested feature is not available, an exception is thrown.

Parameters
nameThe requested feature of the remote device. For standardized features the predefined items in bgapi2_featurenames.h should be used.
Returns
Node* The requested feature of the remote device in form of a Node object.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::InvalidParameterExceptionThe requested feature is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetRemoteNodeList()

BGAPI2::Device::GetRemoteNodeList ( )

The remote functions of the Device class are used to get access to the features of the physical (remote) device.

This function provides the features of the remote device as unstructured list in form of a NodeMap pointer. For a detailed description of the unstructured list representation refer to the class description of NodeMap.

Returns
NodeMap* The list of all features of the remote device in form of a NodeMap object.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.

◆ GetRemoteNodeTree()

BGAPI2::Device::GetRemoteNodeTree ( )

The remote functions of the Device class are used to get access to the features of the physical (remote) device.

This function provides the features of the remote device as tree structure in form of a NodeMap pointer. For a detailed description of the tree structure representation refer to the class description of NodeMap. The access to the features (elements) of the subordinated levels of hierarchy the functions Node::GetNodeTree and Node::GetNodeList should be used respectively.

Returns
NodeMap* The tree structure of all features of the remote device in form of a NodeMap object.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.

◆ GetSerialNumber()

BGAPI2::Device::GetSerialNumber ( )

This function delivers the serial number of the device.

Returns
String The serial number of the device.
Exceptions
Exceptions::NotImplementedExceptionThis function is currently not implemented.

◆ GetTLType()

BGAPI2::Device::GetTLType ( )

This function delivers the transport layer type of the Device.

Returns
String The name of the device.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ GetUpdateConfigurationFile()

BGAPI2::Device::GetUpdateConfigurationFile ( )

The update functions of the Device class are used to get access to the update features of the physical (remote) device.

This function delivers the GenICam XML File of the update features.

Returns
String The GenICam XML file of the update features.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
The update configuration file is only available if the update mode is active.

◆ GetUpdateNode()

BGAPI2::Device::GetUpdateNode ( String  name)

The update functions of the Device class are used to get access to the update features of the physical (remote) device.

This function allows the access to a requested update feature of the remote device. If the requested update feature is not available, an exception is thrown.

Parameters
nameThe requested update feature of the remote device.
Returns
Node* The requested update feature of the remote device in form of a Node object.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::InvalidParameterExceptionThe requested feature is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.
Remarks
The update nodes are only available if the update mode is active.

◆ GetUpdateNodeList()

BGAPI2::Device::GetUpdateNodeList ( )

The update functions of the Device class are used to get access to the update features of the physical (remote) device.

This function provides the update features of the remote device as unstructured list in form of a NodeMap pointer. For a detailed description of the unstructured list representation refer to the class description of NodeMap.

Returns
NodeMap* The list of all update features of the remote device in form of a NodeMap object.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
The update node list is only available if the update mode is active.

◆ GetUpdateNodeTree()

BGAPI2::Device::GetUpdateNodeTree ( )

The update functions of the Device class are used to get access to the update features of the physical (remote) device.

This function provides the update features of the remote device as tree structure in form of a NodeMap pointer. For a detailed description of the tree structure representation refer to the class description of NodeMap. The access to the update features (elements) of the subordinated levels of hierarchy the functions Node::GetNodeTree and Node::GetNodeList should be used respectively.

Returns
NodeMap* The tree structure of all update features of the remote device in form of a NodeMap object.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NotAvailableExceptionThe GenICam XML file of the remote device is not available.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
The update node tree is only available if the update mode is active.

◆ GetVendor()

BGAPI2::Device::GetVendor ( )

This function delivers the name of the device vendor.

Returns
String The name of the device vendor.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

◆ IsOpen()

BGAPI2::Device::IsOpen ( )

This function delivers true, if the device is opened.

Returns
bo_bool delivers true, if the device is open.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.

◆ IsUpdateModeActive()

BGAPI2::Device::IsUpdateModeActive ( )

The update functions of the Device class are used to get access to firmware of the physical (remote) device.

This function delivers true if the update mode is active.

Returns
bo_bool delivers true, if the UpdateMode is active.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
The update mode allows an firmware update of the device. The remote device features will not be available in the update mode.
In order to enable the update mode all data streams of the device have to be closed.
The update mode requires the BO_UpdateAPI2 library.

◆ IsUpdateModeAvailable()

BGAPI2::Device::IsUpdateModeAvailable ( )

The update functions of the Device class are used to get access to firmware of the physical (remote) device.

This function delivers true if the update mode is available.

Returns
bo_bool delivers true, if the UpdateMode is available.
Exceptions
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
The update mode allows an firmware update of the device. The remote device features will not be available in the update mode.
In order to enable the update mode all data streams of the device have to be closed.
The update mode requires the BO_UpdateAPI2 library.

◆ Open()

BGAPI2::Device::Open ( )

This function opens the device object and makes their functions available. Exceptions are the info-functions, which are already available before opening the device.

Exceptions
Exceptions::ResourceInUseExceptionThis exception will be thrown if the device object is already opened.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.
Remarks
GigEVision (GEV) devices supports several access methods for opening. The several methods are read access, read and write access and exclusive read and write access. If a device is opened for reading another application can get read and write access. If a device is opened for reading and writing one or more other applications only can get read access. If a device is opened for exclusive reading and writing the access from other applications is not possible.
Devices of other transport layer types (e.g. USB3Vision) supports only the exclusive read and write access, that means the open function opens the device for reading and writing. The access from other applications is not possible.

◆ OpenExclusive()

BGAPI2::Device::OpenExclusive ( )

This function opens the device object exclusive and makes their functions available. Exceptions are the info-functions, which are already available before opening the device.

Exceptions
Exceptions::ResourceInUseExceptionThis exception will be thrown if the device object is already opened.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.
Remarks
GigEVision (GEV) devices supports several access methods for opening. The several methods are read access, read and write access and exclusive read and write access. If a device is opened for reading another application can get read and write access. If a device is opened for reading and writing one or more other applications only can get read access. If a device is opened for exclusive reading and writing the access from other applications is not possible.
Devices of other transport layer types (e.g. USB3Vision) supports only the exclusive read and write access, that means the open function opens the device for reading and writing. The access from other applications is not possible.

◆ OpenReadOnly()

BGAPI2::Device::OpenReadOnly ( )

This function opens the device object only for reading and make their functions available. Exceptions are the info-functions, which are already available before opening the device.

Exceptions
Exceptions::ResourceInUseExceptionThis exception will be thrown if the device object is already opened in exclusive mode.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.
Remarks
GigEVision (GEV) devices supports several access methods for opening. The several methods are read access, read and write access and exclusive read and write access. If a device is opened for reading another application can get read and write access. If a device is opened for reading and writing one or more other applications only can get read access. If a device is opened for exclusive reading and writing the access from other applications is not possible.
Devices of other transport layer types (e.g. USB3Vision) supports only the exclusive read and write access, that means the open function opens the device for reading and writing. The access from other applications is not possible.

◆ SetRemoteConfigurationFile()

BGAPI2::Device::SetRemoteConfigurationFile ( String  sConfigFile)

The remote functions of the Device class are used to get access to the features of the physical (remote) device.

This function sets a custom GenICam XML File of the remote device.

Parameters
sConfigFileis a coustom config file of the remote device. Set to "" to use the default file of the device.
Exceptions
Exceptions::ResourceInUseExceptionThe device object is open.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
In order to set the configuration file the device has to be closed.

◆ SetUpdateMode()

BGAPI2::Device::SetUpdateMode ( bool  bActive,
String  pcCustomKey 
)

The update functions of the Device class are used to get access to firmware of the physical (remote) device.

This function enables or disables the update mode. See remarks.

Parameters
bActiveEnable or disable the update mode. This mode will control whether the nodemap contains update or bgapi features.
pcCustomKeyis reserved for future use and should be set to "".
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::ResourceInUseExceptionThis exception will be thrown if the update mode is already in the target state.
Remarks
The update mode allows an firmware update of the device. The remote device features will not be available in the update mode.
In order to enable the update mode all data streams of the device have to be closed.
The update mode requires the BO_UpdateAPI2 library.
If you perform an update, previously requested node objects of the remote device will become invalid.

◆ StartStacking()

BGAPI2::Device::StartStacking ( bo_bool  bReplaceMode)

This function starts the stacked mode for write commands (control commands). See remarks.

Parameters
bReplaceModeEnable or disable the replace mode. This mode will control whether all accesses to a register will be transferred to the device or only the last one.
Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Remarks
The stacked mode is a high-performance method for transmitting write commands (control commands) to the device. The control commands were packed into one packet and transmitted as a concatenated command. The stacked mode is started by calling the function Device::StartStacking. All following control commands were collected and will not be transmitted until the calling of Device::WriteStack. If the replace mode is activated, only the last write acess will be transmitzted. After calling Device::WriteStack the stacked mode is stopped.

◆ WriteStack()

BGAPI2::Device::WriteStack ( )

This function writes the collected values to the device and stops the stacked mode.

Exceptions
Exceptions::NotInitializedExceptionThe device object is not open.
Exceptions::NoDataExceptionThe stacked mode is not started or no control commands were written after calling the function Device::StartStacking.
Exceptions::ObjectInvalidExceptionThe calling object is not valid.
Exceptions::LowLevelExceptionGenTL Producer error. Use IException::GetErrorDescription or check trace output for more detailed error information.

The documentation for this class was generated from the following file:
bgapi: BGAPI::Camera Class Reference

Jan, 14 2020
Baumer Optronic GmbH, Badstrasse 30, 01454 D-Radeberg, Tel:+49-3528-4386-0, Fax:+49-3528-4386-86, Email:support.cameras@baumer.com