dl::IGateway Class Reference

Gateway object for controlling device discovery, and lifetime management. More...

#include <dlapi.h>

Public Member Functions
virtual	~IGateway ()=0
	Virtual destructor to ensure the class is an abstract.
virtual TConnectionDetails	getCameraConnectionDetails (unsigned int serial) const =0
	Returns the connection details for a camera with the provided serial number.
virtual ICameraPtr	getCamera (TConnectionDetails details) const =0
	Fetches a pointer to a camera with the provided connection details (if one is available).
virtual void	queryUSBCameras ()=0
	Query the computer for any DLAPI compliant cameras connected via USB.
virtual size_t	getUSBCameraCount () const =0
	Returns the number of cameras found via the last call to IGateway::queryUSBCameras().
virtual ICameraPtr	getUSBCamera (unsigned int id) const =0
	Returns a pointer to the camera with the supplied index, from zero to IGateway::getUSBCameraCount().
virtual void	queryNetCameras ()=0
	Broadcast and enumerate any DLAPI compliant cameras connected to your network.
virtual void	queryNetCamera (const char *ip, size_t port)=0
	Attempt to connect to a camera with the supplied IP Address and port.
virtual size_t	getNetCameraCount () const =0
	Returns the number of cameras found after a call to IGateway::queryNetCameras().
virtual ICameraPtr	getNetCamera (unsigned int id) const =0
	Get a pointer to a camera found on the network via IGateway::queryNetCameras() with the given index, from zero to IGateway::getNetCameraCount().
virtual ICameraPtr	getNetCamera (const char *ip, unsigned int port) const =0
	Get a pointer to a queried camera with a given IP and port, if it exists.
virtual size_t	getCommProtocolVersion () const =0
	Returns the maximum FPGA revision supported by this version of DLAPI.
virtual void	initFitsDebugSettings ()=0
virtual void	initNetworkConfig (const char *filePath)=0
	Initializes the network configuration of UPD-capable cameras using a supplied YAML file.

Detailed Description

Gateway object for controlling device discovery, and lifetime management.

The IGateway interface provides users with a single point of access for discovering DLAPI devices, and managing their resources from the start to finish of an of an imaging lifecycle.

An example application would wrap all API calls in the dl::getGateway() and dl::deleteGateway() function as follows:

#include <dlapi.h>
 
int main()
{
  dl::IGatewayPtr pGateway = dl::getGateway();
  pGateway->queryUSBCameras();
  if (pGateway->getUSBCameraCount() <= 0) return 1;
  
  // If we find a camera in the USB device list, initialize it and retrieve its ICamera interface.
  dl::ICameraPtr pCamera = pGateway->getUSBCamera(0);
 
  // do stuff ...
  
  dl::deleteGateway(pGateway);
  return 0;
}

Constructor & Destructor Documentation

~IGateway()

virtual dl::IGateway::~IGateway ( )

pure virtual

Virtual destructor to ensure the class is an abstract.

Used to ensure IGateway is pure-virtual.

Member Function Documentation

getCamera()

virtual ICameraPtr dl::IGateway::getCamera ( TConnectionDetails details ) const

pure virtual

Fetches a pointer to a camera with the provided connection details (if one is available).

Parameters

details

obtain a camera using the connection details supplied.

Returns

ICameraPtr a pointer to a camera with matching connection details.

See also

ICameraPtr, TConnectionDetails

This convenience function takes a TConnectionDetails structure, and attempts to access a camera from the appropriate USB, or UDP device list. If no camera can be found matching those connection details, nullptr is returned.

getCameraConnectionDetails()

virtual TConnectionDetails dl::IGateway::getCameraConnectionDetails ( unsigned int serial ) const

pure virtual

Returns the connection details for a camera with the provided serial number.

Parameters

serial

a buffer containing the serial number to look up connection details of.

Returns

TConnectionDetails the structure containing internal API indexing information for connecting to the camera.

See also

TConnectionDetails, EEndpointType

This function takes a serial number input, and searches the list of found devices for one with a matching serial. If a camera with a matching serial is found, the function returns a TConnectionDetails structure with the appropriate EEndpointType, and device index. The user can use this information to access the appropriate USB, or UDP camera access points.

If no camera is found, TConnectionDetails::endpointType will be set to InvalidEndpoint.

getCommProtocolVersion()

virtual size_t dl::IGateway::getCommProtocolVersion ( ) const

pure virtual

Returns the maximum FPGA revision supported by this version of DLAPI.

Returns

size_t the maximum camera FPGA revision the driver is capable of running without error

getNetCamera() [1/2]

virtual ICameraPtr dl::IGateway::getNetCamera ( const char * ip, unsigned int port ) const

pure virtual

Get a pointer to a queried camera with a given IP and port, if it exists.

Parameters

ip	a null-terminated string containing the IP address of the camera to obtain.
port	the network port to query.

Returns

ICameraPtr pointer to camera with index id.

Returns the Networked camera at the given ip address. if no camera is found at the given IP address, the function returns nullptr.

getNetCamera() [2/2]

virtual ICameraPtr dl::IGateway::getNetCamera ( unsigned int id ) const

pure virtual

Get a pointer to a camera found on the network via IGateway::queryNetCameras() with the given index, from zero to IGateway::getNetCameraCount().

Parameters

id	zero-based index of the UDP camera to retrieve

Returns

ICameraPtr pointer to camera with index id.

Returns the Networked camera associated with the provided zero-based index. Attempting to access indices below zero, or at the value returned by IGateway::getNetCameraCount() will return nullptr.

getNetCameraCount()

virtual size_t dl::IGateway::getNetCameraCount ( ) const

pure virtual

Returns the number of cameras found after a call to IGateway::queryNetCameras().

Returns

size_t the number of discovered UDP cameras.

See also

IGateway::queryUSBCameras(), IGateway::getUSBCamera(), IGateway::getUSBCameraCount(), IGateway::getNetCamera(), IGateway::getNetCameraCount(),

Returns the number of cameras found using the IGateway::queryNetCameras() function. Retrieve pointers to found cameras via IGateway::getNetCamera().

getUSBCamera()

virtual ICameraPtr dl::IGateway::getUSBCamera ( unsigned int id ) const

pure virtual

Returns a pointer to the camera with the supplied index, from zero to IGateway::getUSBCameraCount().

Parameters

id	zero-based index of the usb camera to retrieve

Returns

ICameraPtr pointer to camera with index id.

See also

IGateway::queryUSBCameras(), IGateway::getUSBCameraCount(), IGateway::queryNetCamera(), IGateway::getNetCamera(), IGateway::getNetCameraCount(),

Returns the usb camera associated with the provided zero-based index. Attempting to access indices below zero, or at the value returned by IGateway::getUSBCameraCount() will return nullptr.

getUSBCameraCount()

virtual size_t dl::IGateway::getUSBCameraCount ( ) const

pure virtual

Returns the number of cameras found via the last call to IGateway::queryUSBCameras().

Returns

size_t the number of discovered USB cameras.

See also

IGateway::queryUSBCameras(), IGateway::getUSBCamera(), IGateway::queryNetCamera(), IGateway::getNetCamera(), IGateway::getNetCameraCount(),

Returns the number of cameras found using the IGateway::queryUSBCameras() function. Retrieve pointers to found cameras via IGateway::getUSBCamera().

initFitsDebugSettings()

virtual void dl::IGateway::initFitsDebugSettings ( )

pure virtual

initNetworkConfig()

virtual void dl::IGateway::initNetworkConfig ( const char * filePath )

pure virtual

Initializes the network configuration of UPD-capable cameras using a supplied YAML file.

Parameters

filePath

the full path to the YAML file containing the network configuration.

This function parses the supplied YAML file for serial-number dependent network configurations for UDP capable cameras. It sends out a broadcast on the specified network interface card to all cameras and the appropriate camera will reconfigure itself to respond with the supplied network settings.

You will be expected to supply a device list with the following information:

• serial: The camera's unique serial number (e.g. AC455M-25010101)
• mac: The camera's physical address (e.g. F1-E2-D3-C4-B5-A6)
• ip: The camera's new IP address (e.g. 192.168.42.2)
• gateway: (optional) The host computer's IP address on the camera's subnet (e.g. 192.168.42.1)
• subnet_mask: (optional) The network's subnet mask (e.g. 255.255.255.0)

You can also supply a global gateway and subnet_mask if the cameras are all on the same subnet. If you do this, the global gateway and subnet_mask will be overridden by any camera-specific settings.

NOTE: You will need to ensure your host PC has the appropriate network settings to communicate with the cameras. This means ensuring the network intefaces connected to the camera are assigned the IP addresses specified in this config file.

example script:

gateway: 192.168.42.1
subnet_mask: 255.255.255.0
devices:
  - serial: AC455M-25010101
    ip: 192.168.42.2
    mac: F1-E2-D3-C4-B5-A6
  - serial: AC455M-25010102
    ip: 192.168.42.3
    mac: 1F-2E-3D-4C-5B-6A

queryNetCamera()

virtual void dl::IGateway::queryNetCamera ( const char * ip, size_t port )

pure virtual

Attempt to connect to a camera with the supplied IP Address and port.

This function sends a GetInfo request to the device located at ip:port. This function blocks until the operation is complete. When the operation is complete it will have enumerated all DLAPI protocol compliant devices connected to the computer via a network. It will have called:

• ICamera::queryInfo().
• ICamera::queryNetworkSettings().
• ISensor::queryInfo() - for each sensor.
• ISensor::queryCalibration() - for each sensor.
• ISensor::querySubframe() - for each sensor.

This process takes up to 2 seconds to complete while the cameras respond via UDP over IP. Note that virtual network interfaces, and bridged adapters can eat up the UDP broadcasts destined for DLAPI devices. If your device is not discovered, check to make sure you have no network adapters that might be intercepting those broadcasts.

queryNetCameras()

virtual void dl::IGateway::queryNetCameras ( )

pure virtual

Broadcast and enumerate any DLAPI compliant cameras connected to your network.

This function searches through all available UDP devices on the active network. This function blocks until the operation is complete. When the operation is complete it will have enumerated all DLAPI protocol compliant devices connected to the computer via a network. It will have called:

• ICamera::queryInfo().
• ICamera::queryNetworkSettings().
• ISensor::queryInfo() - for each sensor.
• ISensor::queryCalibration() - for each sensor.
• ISensor::querySubframe() - for each sensor.

This process takes up to 2 seconds to complete while the cameras respond via UDP. Note that virtual network interfaces, and bridged adapters can eat up the UDP broadcasts destined for DLAPI devices. If your device is not discovered, check to make sure you have no network adapters that might be intercepting those broadcasts.

queryUSBCameras()

virtual void dl::IGateway::queryUSBCameras ( )

pure virtual

Query the computer for any DLAPI compliant cameras connected via USB.

This function searches through all available USB devices connected to the computer which are not in use by another API instance. This function blocks until the operation is complete. When the operation is complete it will have enumerated all DLAPI protocol compliant devices connected to the computer via USB. It will have called:

• ICamera::queryInfo().
• ICamera::queryNetworkSettings().
• ISensor::queryInfo() - for each sensor.
• ISensor::queryCalibration() - for each sensor.
• ISensor::querySubframe() - for each sensor.

---

The documentation for this class was generated from the following file:

• C:/Users/arobi/Perforce/nightly/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h