Back to Aurora Vision Library website

You are here: Start » Function Reference » GenTL » GenTL_OpenDevice


Header: Genicam.h
Namespace: avl
Module: Genicam

Opens a handle to a device provided by GenTL library.


GenTLHandle avl::GenTL_OpenDevice
	const atl::String& inLibraryPath,
	const atl::String& inInterfaceId,
	const atl::String& inDeviceId


Name Type Default Description
Input value
inLibraryPath const String& Path identifying provider library.
Input value
inInterfaceId const String& String identifying communication interface through which device is accessed.
Input value
inDeviceId const String& Unique identifier of device in provider communication interface.


This function accesses a GenTL provider library modules' chain and device described by passed textual identifiers. When specified device is already opened upon function call, and a primary unique identifier of device is used, a new handle to the same device instance is returned.

inLibraryPath parameter identifies a provider library to use as a device driver. Although library is identified by its file path, this function will not load the specified file. Library must be properly registered in system and enumerated upon GenTL subsystem first use. inInterfaceId parameter specifies an internal provider library textual id of communication interface to use for connecting with device. Communication interface can correspond to a hardware interface or to a virtual category for the device class. Interfaces' organization depends on used GenTL provider library. inDeviceId parameter identifies the requested device in its communication interface. inDeviceId can be a unique device id defined by interface module or other alternative device textual address (when used GenTL provider library accepts one). When using alternative device address a single device cannot be opened multiple times using GenTL_OpenDevice function.

You can use GenTL_FindDevices function to quickly obtain library, interface and device identifying parameters. Alternatively you can use GenTL_EnumLibraries and GenTL_EnumLibraryInterfaces functions to discover available GenTL modules structure and pick required library and interface identifiers. When textual ids are not dynamically changed by provider at runtime it is also acceptable to statically define some identifiers of known library-interface-device chain.

For every call to GenTL_OpenDevice a GenTL_CloseHandle function must be called on returned handle.

Return Value

Handle to an opened device. This handle can be used with other GenTL functions to control device state and image streaming, as well as with GenApi functions to access device GenApi parameters set.


This function will throw an exception in the following situations:

  • One of device addressing parameters is missing or has invalid format.
  • Requested device cannot be found.
  • Device connection operation failed.
  • Device initial setup failed.
  • GenICam device description xml file could not be loaded.
  • Other general GenTL or GenICam error occurred.