Basler Logo

Basler Frame Grabber SDK: siso_genicam.h File Reference

siso_genicam.h File Reference

Function declarations for control of GenICam based cameras connected to a Basler frame grabber. More...

#include "fgrab_struct.h"
#include "siso_genicam_error.h"
#include <sys/types.h>

Go to the source code of this file.

Data Structures

struct  SgcCameraInfo
 structure for camera information More...
struct  SgcConnectionProfile
 data structure representing the state of a loaded connection profile More...
struct  SgcEventInfo
 data structure for events received from the board callback functions More...

Defines

#define SGC_EVENT_CAMERA_CONNECTION_LOST   100
 Event types handled by Sgc_RegisterEventCallback.
#define SGC_EVENT_LINK_CONNECTION_STATE_CHANGED   200

Typedefs

typedef struct SgcBoardHandle SgcBoardHandle
typedef struct SgcCameraHandle SgcCameraHandle
typedef struct SgcCameraInfo SgcCameraInfo
 structure for camera information
typedef struct SgcConnectionProfile SgcConnectionProfile
 data structure representing the state of a loaded connection profile
typedef int(* SgcEventCallback_t )(SgcBoardHandle *boardHandle, SgcCameraHandle *cameraHandle, const SgcEventInfo *const eventInfo, const void *userData)
 prototype of event callback procedure
typedef struct SgcEventInfo SgcEventInfo
 data structure for events received from the board callback functions

Functions

int DEPRECATED (Sgc_DirectRegisterWriteMemWithTimeOut(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, const unsigned char *data, const uint32_t buflen, uint32_t timeoutInMilliseconds))
 write a block of data to the camera
int DEPRECATED (Sgc_DirectRegisterReadMemWithTimeOut(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, unsigned char *data, uint32_t *buflen, uint32_t timeoutInMilliseconds))
 write a block of data to the camera
int DEPRECATED (Sgc_DirectRegisterWriteMem(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, const unsigned char *data, const uint32_t buflen))
 write a block of data to the camera
int DEPRECATED (Sgc_DirectRegisterReadMem(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, unsigned char *data, uint32_t *buflen))
 write a block of data to the camera
int DEPRECATED (Sgc_DirectRegisterWrite(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, const uint32_t data, const unsigned int switchByteOrder))
 write an integer value to the camera
int DEPRECATED (Sgc_DirectRegisterRead(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, uint32_t *data))
 reads an integer value from the camera
int DEPRECATED (Sgc_CxpDisconnect(SgcCameraHandle *cameraHandle))
 disconnects a camera handle to a CXP - GenICam camera
int DEPRECATED (Sgc_CxpConnect(SgcBoardHandle *boardHandle, SgcCameraHandle *cameraHandle))
 connects a camera handle to a CXP-GenICam camera
int Sgc_callInternalFunction (int id, const void *const in, void *const out)
int Sgc_connectCamera (SgcCameraHandle *cameraHandle)
 Connect to camera by downloading the cameras internal GenICam XML file A call of this function is necessary in order to control the camera by using GenICam features e.g. "Width", Height" etc. and starting / stopping the camera acquisition as well. The functions loads the GenICam form camera and creates a GnICam node map internally for use by calls to Sgc_SetXXXValue, Sgc_getXXXValues. Alternatively the function Sgc_connectCameraWithExternalXml might be called, if no GenICam is available at the camera.
int Sgc_connectCameraWithExternalXml (SgcCameraHandle *cameraHandle, const char *filename)
 Connect to Camera by using a certain GenICam XML File from the hard disk.
int Sgc_DirectRegisterRead64 (SgcBoardHandle *boardHandle, const unsigned int port, const uint64_t address, uint32_t *data)
 reads an integer value to the camera
int Sgc_DirectRegisterReadMem64 (SgcBoardHandle *boardHandle, const unsigned int port, const uint64_t address, unsigned char *data, uint32_t *buflen)
 write a block of data to the camera
int Sgc_DirectRegisterReadMemWithTimeOut64 (SgcBoardHandle *boardHandle, const unsigned int port, const uint64_t address, unsigned char *data, uint32_t *buflen, uint32_t timeoutInMilliseconds)
 write a block of data to the camera
int Sgc_DirectRegisterWrite64 (SgcBoardHandle *boardHandle, const unsigned int port, const uint64_t address, const uint32_t data, const unsigned int switchByteOrder)
 write a block of data to the camera
int Sgc_DirectRegisterWriteMem64 (SgcBoardHandle *boardHandle, const unsigned int port, const uint64_t address, const unsigned char *data, const uint32_t buflen)
 write a block of data to the camera
int Sgc_DirectRegisterWriteMemWithTimeOut64 (SgcBoardHandle *boardHandle, const unsigned int port, const uint64_t address, const unsigned char *data, const uint32_t buflen, uint32_t timeoutInMilliseconds)
 write a block of data to the camera
int Sgc_disconnectCamera (SgcCameraHandle *cameraHandle)
 Disconnect from camera.
int Sgc_executeCommand (SgcCameraHandle *cameraHandle, const char *name)
 Execute a certain GenICam command at the camera.
void Sgc_freeBoard (SgcBoardHandle *boardHandle)
 Release resources allocated by Sgc_initBoard.
int Sgc_getBoardPropertyWithType (SgcBoardHandle *boardHandle, const char *propertyName, const void *value, const int propertyType, const void *additionalValue)
 get a global board property
int Sgc_getBooleanValue (SgcCameraHandle *cameraHandle, const char *name, unsigned int *valuePtr)
 Read GenICam boolean value at camera.
int Sgc_getCamera (SgcBoardHandle *boardHandle, const unsigned int port, SgcCameraHandle **cameraHandle)
 get a camera object associated to a certain frame grabber port
int Sgc_getCameraByIndex (SgcBoardHandle *boardHandle, const unsigned int index, SgcCameraHandle **cameraHandle)
 get a handle of the currently detected cameras
int Sgc_getCameraCount (SgcBoardHandle *boardHandle)
 get number of the currently detected cameras
SgcCameraInfoSgc_getCameraInfo (SgcCameraHandle *cameraHandle)
 get manufacturer information from connected camera.
int Sgc_getCameraPropertyWithType (SgcCameraHandle *cameraHandle, const char *propertyName, void *value, unsigned int *propertyType, void *additionalValue)
 get camera specific properties
int Sgc_getEnumerationValue (SgcCameraHandle *cameraHandle, const char *name, int64_t *value)
 Read GenICam integer representation of enumeration value from camera.
int Sgc_getEnumerationValueAsString (SgcCameraHandle *cameraHandle, const char *name, const char **valuePtr)
 Read GenICam string representation of enumeration value from camera.
const char * Sgc_getErrorDescription (const int errorCode)
 returns a descriptive text for the error code
int Sgc_getFloatValue (SgcCameraHandle *cameraHandle, const char *name, double *valuePtr)
 Read GenICam floating point value at camera.
int Sgc_getGenICamXML (SgcCameraHandle *cameraHandle, char *buffer, size_t *bufferSize)
 returns the currently loaded GenICam-XML
int Sgc_getIntegerValue (SgcCameraHandle *cameraHandle, const char *name, int64_t *valuePtr)
 Read GenICam Integer value from camera.
int Sgc_getStringValue (SgcCameraHandle *cameraHandle, const char *name, const char **valuePtr)
 Read GenICam string value from camera.
int Sgc_initBoard (Fg_Struct *fg, int initFlag, SgcBoardHandle **boardHandle)
 Create an Interface object for accessing cameras connected to a frame grabber.
int Sgc_initBoardEx (Fg_Struct *fg, unsigned int initFlag, SgcBoardHandle **boardHandle, unsigned int portMask, unsigned int slaveMode)
 Create an Interface object for accessing cameras connected to a frame grabber.
unsigned int Sgc_isCameraAvailable (SgcBoardHandle *boardHandle, const unsigned int port)
 Check for camera.
int Sgc_isCommandDone (SgcCameraHandle *cameraHandle, const char *name, unsigned int *value)
 Check, if a GenICam command is performed completely.
int Sgc_LinkConnect (SgcBoardHandle *boardHandle, SgcCameraHandle *cameraHandle)
 connects a camera handle a GenICam capable camera
int Sgc_LinkDisconnect (SgcCameraHandle *cameraHandle)
 disconnects a camera handle from a GenICam capable camera
int Sgc_LoadBoardConfiguration (SgcBoardHandle *boardHandle, const char *configFileName)
 load connection parameters from a file
int Sgc_LoadCameraParameters (SgcCameraHandle *cameraHandle, const char *paramFileName, uint32_t flags)
 load the current camera parameters from a file
int Sgc_LoadConnectionProfile (Fg_Struct *fg, const char *boardConfigurationFilePath, SgcConnectionProfile **connectionProfilePtr)
 load a connection profile
int Sgc_memoryReadFromCamera (SgcCameraHandle *cameraHandle, void *buffer, uint64_t address, size_t length)
 read a number of bytes from a camera register without a timeout
int Sgc_memoryReadFromCameraWithTimeout (SgcCameraHandle *cameraHandle, void *buffer, uint64_t address, size_t length, uint32_t timeoutInMilliseconds)
 read a number of bytes from a camera register
int Sgc_memoryWriteToCamera (SgcCameraHandle *cameraHandle, const void *buffer, uint64_t address, size_t length)
 write a number of bytes to a camera register without a timeout
int Sgc_memoryWriteToCameraWithTimeout (SgcCameraHandle *cameraHandle, const void *buffer, uint64_t address, size_t length, uint32_t timeoutInMilliseconds)
 write a number of bytes to a camera register
int Sgc_powerSwitch (SgcBoardHandle *boardHandle, const unsigned int portMask)
 switch on Power over CoaxPress/CameraLink/...
int Sgc_powerSwitchExt (SgcBoardHandle *boardHandle, const unsigned int portMask, const unsigned int command)
 switch on Power over CoaxPress
int Sgc_RegisterEventCallback (SgcBoardHandle *boardHandle, SgcEventCallback_t eventHandler, void *userData)
 Register an callback procedure for event notifications.
int Sgc_registerReadFromCamera (SgcCameraHandle *cameraHandle, uint32_t *data, uint64_t address)
 read a 32 bit integer value from a camera register
int Sgc_registerWriteToCamera (SgcCameraHandle *cameraHandle, uint32_t data, uint64_t address)
 write a 32 bit integer value to a camera register
int Sgc_SaveBoardConfiguration (SgcBoardHandle *boardHandle, const char *configFileName)
 save connection parameters of the board to a file
int Sgc_SaveCameraParameters (SgcCameraHandle *cameraHandle, const char *paramFileName, uint32_t flags)
 save the current camera parameters to a file
int Sgc_scanPorts (SgcBoardHandle *boardHandle, const unsigned int portMask, const int discoveryTimeout, const int speed)
 Scans the defined ports of the frame grabber for present cameras.
int Sgc_scanPortsEx (SgcBoardHandle *boardHandle, const unsigned int portMask, const int discoveryTimeout, const int speed, const unsigned int flags)
 Scans the defined ports of the frame grabber for present cameras.
int Sgc_setBoardPropertyWithType (SgcBoardHandle *boardHandle, const char *propertyName, const void *propertyValue, const int propertyType, void *additionalValue)
 set global board properties
int Sgc_setBooleanValue (SgcCameraHandle *cameraHandle, const char *name, unsigned int value)
 Set GenICam boolean value at camera.
int Sgc_setCameraPropertyWithType (SgcCameraHandle *cameraHandle, const char *propertyName, const void *value, int propertyType, void *additionalValue)
 set camera or camera connection specific properties
int Sgc_setEnumerationValue (SgcCameraHandle *cameraHandle, const char *name, const char *value)
 Set GenICam enumeration value at camera.
int Sgc_setFloatValue (SgcCameraHandle *cameraHandle, const char *name, double value)
 Set GenICam floating point value at camera.
int Sgc_setGenICamXML (SgcCameraHandle *cameraHandle, const char *buffer, const size_t bufferSize)
 sets the currently GenICam-XML from a buffer
int Sgc_setIntegerValue (SgcCameraHandle *cameraHandle, const char *name, int64_t value)
 Set GenICam Integer value at camera.
int Sgc_setStringValue (SgcCameraHandle *cameraHandle, const char *name, const char *value)
 Set GenICam string value at camera.
int Sgc_startAcquisition (SgcCameraHandle *cameraHandle, unsigned int startCamera)
 activates the the data flow towards the applet and activates the image acquisition at the camera This function is used in combination with the Fg_StartAcquire() function of the standard frame grabber SDK. Acquisition needs to be started from both sides always: from the applet side (Fg_startAcquire()) and from the camera side (Sgc_startAcquisition()). The order or the commands should be: 1. start grabbing at the applet side (fg_StartAcquire()) and 2. at the camera side. This ensures a correct image transmission. If the sequence is changed, it cannot be guaranteed, that the transferred images are correctly aligned at the beginning of a frame.
int Sgc_stopAcquisition (SgcCameraHandle *cameraHandle, unsigned int stopCamera)
 stops the the data flow towards the applet and stops the image acquisition at the camera (optionally)
int Sgc_stringReadFromCamera (SgcCameraHandle *cameraHandle, char *data, uint64_t address, unsigned int length)
 read a string value from a camera register This function can be used for a direct access to a camera without by bypassing the GenICam XML implementation and register name translations. It might be used, if the register address of the connected camera is known exactly.
int Sgc_UnloadConnectionProfile (SgcConnectionProfile *connectionProfile)
 unload a connection profile

Detailed Description

Function declarations for control of GenICam based cameras connected to a Basler frame grabber.

siso_genicam.h

Copyright (c) 2002-2014 Basler AG, All Rights Reserved.

Author:
Basler AG

Define Documentation

#define SGC_EVENT_CAMERA_CONNECTION_LOST   100

Event types handled by Sgc_RegisterEventCallback.

event type "Camera Connection Lost": the connection to the connected camera has been lost

#define SGC_EVENT_LINK_CONNECTION_STATE_CHANGED   200

event type "link connection state changed


Typedef Documentation

handle structure for boards

handle structure for cameras

typedef struct SgcCameraInfo SgcCameraInfo

structure for camera information

data structure representing the state of a loaded connection profile

Remarks:
SgcConnectionProfile, that gets filled by the the function Sgc_LoadConnectionProfile of siso_genicam. It stores the board handle and camera related data (camera count, camera handles, camera infos, camera connection states).
typedef int(* SgcEventCallback_t)(SgcBoardHandle *boardHandle, SgcCameraHandle *cameraHandle, const SgcEventInfo *const eventInfo, const void *userData)

prototype of event callback procedure

reserved for later usage

Parameters:
boardHandle board handle, at which the event occurred
cameraHandle camera handle, at which the event occurred
eventInfo event details/data
userData additional payload passed from user at registration of event handler
typedef struct SgcEventInfo SgcEventInfo

data structure for events received from the board callback functions

Remarks:
SgcEventInfo is a structure, that gets filled by the callback interface of siso_genicam. Which event is notified can be determined by evaluating the member eventID (event type identifier). the event types correspond to the SGC_EVENT_CXXX constants (defines). Specific events types correspond to specific additional information. These information is represented as different components of the union. When evaluating the additional information, the member eventID needs to be determined first.

Function Documentation

int DEPRECATED ( Sgc_DirectRegisterWriteMemWithTimeOut(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, const unsigned char *data, const uint32_t buflen, uint32_t timeoutInMilliseconds)   ) 

write a block of data to the camera

Deprecated:
this function is replaced by Sgc_DirectRegisterWriteMemWithTimeOut64
See also:
Sgc_DirectRegisterWriteMemWithTimeOut64
int DEPRECATED ( Sgc_DirectRegisterReadMemWithTimeOut(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, unsigned char *data, uint32_t *buflen, uint32_t timeoutInMilliseconds)   ) 

write a block of data to the camera

Deprecated:
this function is replaced by Sgc_DirectRegisterReadMemWithTimeOut64()
See also:
Sgc_DirectRegisterReadMemWithTimeOut64
int DEPRECATED ( Sgc_DirectRegisterWriteMem(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, const unsigned char *data, const uint32_t buflen)   ) 

write a block of data to the camera

Deprecated:
this function is replaced by Sgc_DirectRegisterWriteMem64()
See also:
Sgc_DirectRegisterWriteMem64
int DEPRECATED ( Sgc_DirectRegisterReadMem(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, unsigned char *data, uint32_t *buflen)   ) 

write a block of data to the camera

Deprecated:
Use Sgc_DirectRegisterReadMem64
See also:
Sgc_DirectRegisterReadMem64
int DEPRECATED ( Sgc_DirectRegisterWrite(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, const uint32_t data, const unsigned int switchByteOrder)   ) 

write an integer value to the camera

Deprecated:
this function is replaced by Sgc_DirectRegisterWrite64()
See also:
Sgc_DirectRegisterWrite64
int DEPRECATED ( Sgc_DirectRegisterRead(SgcBoardHandle *boardHandle, const unsigned int port, const uint32_t address, uint32_t *data)   ) 

reads an integer value from the camera

Deprecated:
this function is replaced by Sgc_DirectRegisterRead64()
See also:
Sgc_DirectRegisterRead64
int DEPRECATED ( Sgc_CxpDisconnect(SgcCameraHandle *cameraHandle)   ) 

disconnects a camera handle to a CXP - GenICam camera

Deprecated:
this function is replaced by Sgc_LinkDisconnect()
See also:
Sgc_LinkDisconnect
int DEPRECATED ( Sgc_CxpConnect(SgcBoardHandle *boardHandle, SgcCameraHandle *cameraHandle)   ) 

connects a camera handle to a CXP-GenICam camera

Deprecated:
this function is replaced by Sgc_LinkConnect()
See also:
Sgc_LinkConnect
int Sgc_callInternalFunction ( int  id,
const void *const   in,
void *const   out 
)

for internal use only

int Sgc_connectCamera ( SgcCameraHandle cameraHandle  ) 

Connect to camera by downloading the cameras internal GenICam XML file A call of this function is necessary in order to control the camera by using GenICam features e.g. "Width", Height" etc. and starting / stopping the camera acquisition as well. The functions loads the GenICam form camera and creates a GnICam node map internally for use by calls to Sgc_SetXXXValue, Sgc_getXXXValues. Alternatively the function Sgc_connectCameraWithExternalXml might be called, if no GenICam is available at the camera.

Return values:
0 success, ERR_SGC_NOT_CONNECTED : no physical connection established ERR_SGC_UNEXPECTED: URL is not valid, no GenICam present, error inside XML data ERR_SGC_INVALID_CAMHANDLE: camera handle is not valid
See also:
Sgc_connectCameraWithExternalXml
int Sgc_connectCameraWithExternalXml ( SgcCameraHandle cameraHandle,
const char *  filename 
)

Connect to Camera by using a certain GenICam XML File from the hard disk.

Parameters:
cameraHandle Camera handle retrieved by calling
filename filename of the GenICam XML file for the camera
Return values:
0,: success ERR_SGC_FILENOTFOUND file cannot be opened for reading ERR_SGC_INVALIDFILENAME invalid filename, e.g. empty string
See also:
Sgc_connectCamera
int Sgc_DirectRegisterRead64 ( SgcBoardHandle boardHandle,
const unsigned int  port,
const uint64_t  address,
uint32_t *  data 
)

reads an integer value to the camera

This function can be used in order to read an integer value from a camera register directly

Parameters:
boardHandle a handle to the according board
port port identifier
address camera register address
data data to be written
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
int Sgc_DirectRegisterReadMem64 ( SgcBoardHandle boardHandle,
const unsigned int  port,
const uint64_t  address,
unsigned char *  data,
uint32_t *  buflen 
)

write a block of data to the camera

This function can be used in order to write an block of data to a camera register directly All data according to the parameter buflen is written to the camera

Parameters:
boardHandle a handle to the according board
port port identifier
address camera register address
data data read from the camera
buflen length of the output buffer in bytes, after reading containing the number of bytes read
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
int Sgc_DirectRegisterReadMemWithTimeOut64 ( SgcBoardHandle boardHandle,
const unsigned int  port,
const uint64_t  address,
unsigned char *  data,
uint32_t *  buflen,
uint32_t  timeoutInMilliseconds 
)

write a block of data to the camera

This function can be used in order to write an block of data to a camera register directly All data according to the parameter buflen is written to the camera

Parameters:
boardHandle a handle to the according board
port port identifier
address camera register address
data data read from the camera
buflen length of the output buffer in bytes, after reading containing the number of bytes read
timeoutInMilliseconds timeout in ms. 0 indicates infinite
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
int Sgc_DirectRegisterWrite64 ( SgcBoardHandle boardHandle,
const unsigned int  port,
const uint64_t  address,
const uint32_t  data,
const unsigned int  switchByteOrder 
)

write a block of data to the camera

This function can be used in order to write an block of data to a camera register directly All data according to the parameter buflen is written to the camera

Parameters:
boardHandle a handle to the according board
port port identifier
address camera register address
data data read from the camera
switchByteOrder switches the byte order of data before writing (endianess)
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
int Sgc_DirectRegisterWriteMem64 ( SgcBoardHandle boardHandle,
const unsigned int  port,
const uint64_t  address,
const unsigned char *  data,
const uint32_t  buflen 
)

write a block of data to the camera

This function can be used in order to write an block of data to a camera register directly All data according to the parameter buflen is written to the camera

Parameters:
boardHandle a handle to the according board
port port identifier
address camera register address
data data to be written
buflen length of the input buffer
Return values:
0,: success, ERR_SGC_INVALID_ARG: invalid out parameter
int Sgc_DirectRegisterWriteMemWithTimeOut64 ( SgcBoardHandle boardHandle,
const unsigned int  port,
const uint64_t  address,
const unsigned char *  data,
const uint32_t  buflen,
uint32_t  timeoutInMilliseconds 
)

write a block of data to the camera

This function can be used in order to write an block of data to a camera register directly All data according to the parameter buflen is written to the camera. A timeout can be set in order to take care of the cameras's processing time.

Parameters:
boardHandle a handle to the according board
port port identifier
address camera register address
data data to be written
buflen length of the input buffer
timeoutInMilliseconds timeout in ms. 0 indicates infinite
Return values:
0,: success, ERR_SGC_INVALID_ARG: invalid out parameter
int Sgc_disconnectCamera ( SgcCameraHandle cameraHandle  ) 

Disconnect from camera.

Parameters:
cameraHandle Camera handle retrieved by calling
int Sgc_executeCommand ( SgcCameraHandle cameraHandle,
const char *  name 
)

Execute a certain GenICam command at the camera.

Parameters:
cameraHandle camera handle instance
name name of the command
Return values:
0 in case of success, error code (defined in XXX_error.h) ERR_SGC_INVALID_COMMAND command name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
void Sgc_freeBoard ( SgcBoardHandle boardHandle  ) 

Release resources allocated by Sgc_initBoard.

Parameters:
boardHandle Interface object to be released. Retrieved by Sgc_initBoard
See also:
Sgc_initBoard
int Sgc_getBoardPropertyWithType ( SgcBoardHandle boardHandle,
const char *  propertyName,
const void *  value,
const int  propertyType,
const void *  additionalValue 
)

get a global board property

This generic function allows to get any board property, which is currently active. The property itself is identified by a null terminated string value according to the defined values. The data type of this variable depends on the property itself and might be any standard C data type like integer, double, char[], etc. To allow a check inside the function, the used data type has to be passed at the parameter property type. Constants for definition of the data type passed at the propertyValue parameter can be seen at the SGC_PROPERTY_TYPE_XXX definitions. Some properties need additional addressing. In such cases the data has to be passed at the value parameter. In most cases, this pointer might be set to NULL.

Parameters:
boardHandle a handle to the according board
propertyName property identifier, see PROP_XXX
value pointer to a buffer for returning the data
additionalValue pointer to data for addressing specific properties
propertyType data type of the variable passed at the propertyValuePtr parameter
value additional value for addressing a property, might be NULL
Return values:
0 in case of success, error code (defined in ERR_SGC_XXX)
See also:
Sgc_getErrorDescription, Sgc_setBoardPropertyWithType
int Sgc_getBooleanValue ( SgcCameraHandle cameraHandle,
const char *  name,
unsigned int *  valuePtr 
)

Read GenICam boolean value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
valuePtr buffer for value to be read ( 1 : true, 0: false)
Return values:
0,: in case of success, <> 0: error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_getCamera ( SgcBoardHandle boardHandle,
const unsigned int  port,
SgcCameraHandle **  cameraHandle 
)

get a camera object associated to a certain frame grabber port

Parameters:
boardHandle handle to frame grabber generated by Sgc_initBoard()
port port index (frame grabber port index)
cameraHandle return value of allocated interface resources, needs to be initialized by NULL pointer
Return values:
0 success, <> 0 see ERR_SGC_XXX constants
See also:
Sgc_initBoard
int Sgc_getCameraByIndex ( SgcBoardHandle boardHandle,
const unsigned int  index,
SgcCameraHandle **  cameraHandle 
)

get a handle of the currently detected cameras

This function can be used for iterations or loops to obtain the currently present camera objects. The range of the index is between 0 and Sgc_getNrOfCameras()-1. It returns both: discovered/connected camera handles or unconnected camera handles, which are created by Sgc_GetCamera(port) and might wait for connection.

The camera handle will be returned in the cameraHandle parameter.

Parameters:
boardHandle a handle to the according board
cameraHandle return value as cameraHandel that can be used for further camera access NULL in case of an error
index index between 0 and Sgc_getNrOfCameras()-1
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
See also:
Sgc_getErrorDescription
int Sgc_getCameraCount ( SgcBoardHandle boardHandle  ) 

get number of the currently detected cameras

This function can be used for iterations or loops to obtain the currently present camera objects. It returns both: number of discovered/connected camera handles or unconnected camera handles, which are created by Sgc_GetCamera(port) and might wait for connection.

Parameters:
boardHandle a handle to the according board
Return values:
>= 0: number of cameras ( # of camera handles) <> 0 error code (defined in ERR_SGC_XXX)
See also:
Sgc_getErrorDescription
SgcCameraInfo* Sgc_getCameraInfo ( SgcCameraHandle cameraHandle  ) 

get manufacturer information from connected camera.

This function returns camera specific information from a camera connected to the frame grabber. In general this information is read from technology specific bootstrap registers. The data is returned in form of the SgcCameraInfo structure.

Remarks:
The returned pointer to this structure valid as long as the camera handle passed as an argument to this function
Parameters:
cameraHandle handle to frame grabber generated by Sgc_initBoard()
Return values:
camera information obtained from bootstrap registers
int Sgc_getCameraPropertyWithType ( SgcCameraHandle cameraHandle,
const char *  propertyName,
void *  value,
unsigned int *  propertyType,
void *  additionalValue 
)

get camera specific properties

This generic function allows to get various camera properties like current link speed, current stream packet size, state of connection etc. The available properties are defined at the CAM_PROP_XXX constants. Due to the variety of these parameters, the generic functions uses a void pointer to give access to any of these. The type of data (pointer to integer, pointer to double etc.) have to be passed at the property type parameter in order to allow a minimum check for data security. The available types are listed at the SGC_PROPERTY_TYPE_XXX constants. Some parameter need additional information to address the value correctly. In such cases, the pointer named value has to be used.

Parameters:
cameraHandle camera handle instance
propertyName string containing the name of property to be accessed, see CAM_PROP_XXX constants
value pointer to data structure, where the result value should be used. Needs to be large enough to carry the data completely. For valid values see CAM_PROP_XXX constants
propertyType type of data given at parameter propertyValuePtr (in / out parameter) see SGC_PROPERTY_TYPE_XXX constants
additionalValue additional parameter to address the the property (multi-purpose)
Return values:
0,: success ERR_SGC_INVALID_ARG : a needed data structure was not initialized ERR_SGC_INVALID_PROPERTY: tried to access an invalid property
int Sgc_getEnumerationValue ( SgcCameraHandle cameraHandle,
const char *  name,
int64_t *  value 
)

Read GenICam integer representation of enumeration value from camera.

Parameters:
cameraHandle camera handle instance
name feature name
value buffer for value to be read (value returned as number)
Return values:
0 in case of success, error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_getEnumerationValueAsString ( SgcCameraHandle cameraHandle,
const char *  name,
const char **  valuePtr 
)

Read GenICam string representation of enumeration value from camera.

Parameters:
cameraHandle camera handle instance
name feature name
valuePtr return value
Return values:
0 in case of success, error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
const char* Sgc_getErrorDescription ( const int  errorCode  ) 

returns a descriptive text for the error code

This function returns a descriptive text for an error code returned from a previous call to a Sgc_XXX function.

Parameters:
errorCode error code to be decoded.
Return values:
pointer to a null terminated string containing the according error code
int Sgc_getFloatValue ( SgcCameraHandle cameraHandle,
const char *  name,
double *  valuePtr 
)

Read GenICam floating point value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
valuePtr buffer for value to be read
Return values:
0,: in case of success, <> 0: error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_getGenICamXML ( SgcCameraHandle cameraHandle,
char *  buffer,
size_t *  bufferSize 
)

returns the currently loaded GenICam-XML

Parameters:
cameraHandle camera handle instance
buffer the buffer, where to copy the data, if NULL, the required buffer size is returned
bufferSize the fill level or required buffer size of the buffer
Return values:
0 in case of success, error code (defined in XXX_error.h)
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_getIntegerValue ( SgcCameraHandle cameraHandle,
const char *  name,
int64_t *  valuePtr 
)

Read GenICam Integer value from camera.

Parameters:
cameraHandle camera handle instance
name feature name
valuePtr buffer for value to be read
Return values:
0 in case of success, error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
Remarks:
even if the functions prototype uses a 64 bit value as data, the library supports 32 bit integers only according to CoaxPress specification
See also:
Sgc_connectCamera, Sgc_getErrorDescription,
int Sgc_getStringValue ( SgcCameraHandle cameraHandle,
const char *  name,
const char **  valuePtr 
)

Read GenICam string value from camera.

Parameters:
cameraHandle camera handle instance
name feature name
valuePtr return value
Return values:
0 in case of success, error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_initBoard ( Fg_Struct fg,
int  initFlag,
SgcBoardHandle **  boardHandle 
)

Create an Interface object for accessing cameras connected to a frame grabber.

This function has to be called first, before any access to cameras can be done. By using the retrieved handle, a camera detection, connections to certain cameras or an iteration over present cameras can be performed.

The allocated resources have to be released by using the Sgc_freeBoard function.

Parameters:
fg frame grabber handle retrieved by FGLIB::fg_init(<APPLETNAME>)
initFlag reserved for later usage
boardHandle return value of allocated interface resources, needs to be initialized by NULL pointer
Return values:
0 success, <> 0 see ERR_SGC_XXX constants
See also:
Sgc_freeBoard
int Sgc_initBoardEx ( Fg_Struct fg,
unsigned int  initFlag,
SgcBoardHandle **  boardHandle,
unsigned int  portMask,
unsigned int  slaveMode 
)

Create an Interface object for accessing cameras connected to a frame grabber.

This function has to be called first, before any access to cameras can be done. By using the retrieved handle, a camera detection, connections to certain cameras or an iteration over present cameras can be performed.

The allocated resources have to be released by using the Sgc_freeBoard function.

Parameters:
fg frame grabber handle retrieved by FGLIB::fg_init(<APPLETNAME>)
initFlag reserved for later usage
boardHandle return value of allocated interface resources, needs to be initialized by NULL pointer
portMask bit mask, to enable specific frame grabber ports, that shall be used. Default value is 0xFFFF (all ports)
slaveMode currently not used
Return values:
0 success, <> 0 see ERR_SGC_XXX constants
See also:
Sgc_freeBoard
unsigned int Sgc_isCameraAvailable ( SgcBoardHandle boardHandle,
const unsigned int  port 
)

Check for camera.

Parameters:
boardHandle Interface object to be released. Retrieved by Sgc_initBoard
port port to check
Return values:
true,: a camera is present at the given port, otherwise false
int Sgc_isCommandDone ( SgcCameraHandle cameraHandle,
const char *  name,
unsigned int *  value 
)

Check, if a GenICam command is performed completely.

Parameters:
cameraHandle camera handle instance
name name of the command
value returned data read from the camera by using GenICam
Return values:
0 command is currently in process, 1:command is currently in not process ERR_SGC_INVALID_COMMAND command name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_LinkConnect ( SgcBoardHandle boardHandle,
SgcCameraHandle cameraHandle 
)

connects a camera handle a GenICam capable camera

This function can be used when presetting the link connection parameters manually. It configures the frame grabber port(s) associated to the camera handle at the predefined link speeds, and handles the protocol commands needed for creating a connection. It might be used as an alternative to the camera detection by using the discovery procedures (sgc_ScanPorts()).

Parameters:
boardHandle a handle to the according board
cameraHandle camera handle containing the necessary information for creating the connection
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
See also:
Sgc_ScanPorts, Sgc_SetCameraProperty, Sgc_LoadBoardConfiguration, Sgc_LinkDisconnect
int Sgc_LinkDisconnect ( SgcCameraHandle cameraHandle  ) 

disconnects a camera handle from a GenICam capable camera

Parameters:
cameraHandle camera handle containing the necessary information for creating the connection
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
See also:
Sgc_LinkConnect
int Sgc_LoadBoardConfiguration ( SgcBoardHandle boardHandle,
const char *  configFileName 
)

load connection parameters from a file

This function can be used to load the current connection parameters for all links/cameras from the hard disk in order to create camera connections. It can be used as an alternative approach for setting up a connection instead of the camera discovery. The predefined connection parameters will be used and the connection can be established afterwards by using exactly these parameters. In case of an error condition the calls to established will fail, which can can be evaluated by the software.

Parameters:
boardHandle a handle to the according board
configFileName filename
Return values:
0,: success, ERR_SGC_INVALID_ARG: invalid out parameter ERR_SGC_INVALIDFILENAME: file not found ERR_SGC_INVALID_DATA: the data inside the file is invalid
See also:
Sgc_CxpConnect, Sgc_ScanPorts, Sgc_SetCameraProperty
int Sgc_LoadCameraParameters ( SgcCameraHandle cameraHandle,
const char *  paramFileName,
uint32_t  flags 
)

load the current camera parameters from a file

This function can be used to load values of camera registers from a file. Parameters are loaded and carried over to the camera according to the camera's GenICam register description.

Parameters:
cameraHandle a handle to the according camera
paramFileName filename
flags specific flags see :
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
See also:
Sgc_SaveCameraParameters, Sgc_connectCamera,
int Sgc_LoadConnectionProfile ( Fg_Struct fg,
const char *  boardConfigurationFilePath,
SgcConnectionProfile **  connectionProfilePtr 
)

load a connection profile

This function initializes the board, loads the board configuration file and establishes connections to the cameras. The result of these operations is represented by the returned connection profile structure.

The allocated resources have to be released by using the Sgc_UnloadConnectionProfile function.

Parameters:
fg frame grabber handle retrieved by FGLIB::fg_init(<APPLETNAME>)
boardConfigurationFilePath path to th board configuration file
connectionProfilePtr pointer address for the allocated connection profile structure
Return values:
0 success, <> 0 see ERR_SGC_XXX constants
See also:
Sgc_UnloadConnectionProfile
int Sgc_memoryReadFromCamera ( SgcCameraHandle cameraHandle,
void *  buffer,
uint64_t  address,
size_t  length 
)

read a number of bytes from a camera register without a timeout

See also:
Sgc_memoryReadFromCameraWithTimeout
int Sgc_memoryReadFromCameraWithTimeout ( SgcCameraHandle cameraHandle,
void *  buffer,
uint64_t  address,
size_t  length,
uint32_t  timeoutInMilliseconds 
)

read a number of bytes from a camera register

The data will be copied to the buffer given at the buffer parameter. This buffer needs to be large enough to store the whole string. The number of bytes to be read have to be passed at the length parameter. The string is not necessarily 0 terminated.

This function can be used for a direct access to a camera by bypassing the GenICam XML implementation and register name translations. It might be used, if the register address of the connected camera is known exactly.

Remarks:
The length of data transfer is checked against GenICam definition of the camera.
Parameters:
cameraHandle camera handle instance
address address of the camera register (example 0x00002070 "Device version")
buffer pointer to a buffer for the return value
length number of bytes to be read
timeoutInMilliseconds timeout for camera response and data transfer. if set to 0 the timeout is disabled
Return values:
0,: success, ERR_SGC_BUFFER_TOO_SMALL: Buffer too small
int Sgc_memoryWriteToCamera ( SgcCameraHandle cameraHandle,
const void *  buffer,
uint64_t  address,
size_t  length 
)

write a number of bytes to a camera register without a timeout

See also:
Sgc_memoryWriteToCameraWithTimeout
int Sgc_memoryWriteToCameraWithTimeout ( SgcCameraHandle cameraHandle,
const void *  buffer,
uint64_t  address,
size_t  length,
uint32_t  timeoutInMilliseconds 
)

write a number of bytes to a camera register

The content of the buffer data will be written to the specified camera register. This function can be used for a direct access to a camera register by bypassing the GenICam XML implementation and register name translations. It might be used, if the register address of the connected camera is known exactly.

Remarks:
The length of data transfer is checked against GenICam definition of the camera
Parameters:
cameraHandle camera handle instance
address address of the camera register (example 0x00002070 "Device version")
buffer pointer to a buffer for the return value
length number of bytes to be read
timeoutInMilliseconds timeout for camera response and data transfer. if set to 0 the timeout is disbled
Return values:
0,: success, ERR_SGC_BUFFER_TOO_SMALL: Buffer too small
int Sgc_powerSwitch ( SgcBoardHandle boardHandle,
const unsigned int  portMask 
)

switch on Power over CoaxPress/CameraLink/...

This function switches the power supply of the given frame grabber ports off and on again in order to perform a reset of the camera. This function is only effectful, if the connected camera does not use an external power supply.

Important note: after switching the power on at a certain port, the cameras will boot up. The booting of a camera takes some time, until an access to the camera is possible. This dead time varies between different camera / camera types. Please refer to the camera manufacturer's specification in order to get the information how long the client has to wait after power on.

Parameters:
boardHandle Interface object to be released. Retrieved by Sgc_initBoard
portMask bit mask containing the frame grabber ports to access
int Sgc_powerSwitchExt ( SgcBoardHandle boardHandle,
const unsigned int  portMask,
const unsigned int  command 
)

switch on Power over CoaxPress

This function allows to change the state of power supply at a certain frame grabber port.

Important note: after switching the power on at a certain port, the cameras will boot up. The booting of a camera takes some time, until an access to the camera is possible. This dead time varies between different camera / camera types. Please refer to the camera manufacturer's specification in order to get the information how long the client has to wait after power on.

Parameters:
boardHandle Interface object to be released. Retrieved by Sgc_initBoard
portMask bit mask containing the frame grabber ports to access
command command, how to switch power. values: 0 power off, 1: power on, 2: tear down power for a certain duration
int Sgc_RegisterEventCallback ( SgcBoardHandle boardHandle,
SgcEventCallback_t  eventHandler,
void *  userData 
)

Register an callback procedure for event notifications.

Parameters:
boardHandle a handle for accessing the board
eventHandler structure containing the callback function
userData additional data, that gets passed at each callback
Return values:
0:in case of success, <> 0: error code (defined in XXX_error.h)
See also:
Sgc_getErrorDescription,
int Sgc_registerReadFromCamera ( SgcCameraHandle cameraHandle,
uint32_t *  data,
uint64_t  address 
)

read a 32 bit integer value from a camera register

This function can be used for a direct access to a camera without by bypassing the GenICam XML implementation and register name translations. It might be used, if the register address of the connected camera is known exactly. The byte order gets converted into little endian.

Parameters:
cameraHandle camera handle instance
address address of the camera register (example 0x00002070 "Device version")
data pointer to a buffer for the return value
Return values:
0,: success ERR_SGC_INVALID_ARG : the pointer to return value is not set ERR_SGC_INVALID_CAMHANDLE : the camera handle is not valid
int Sgc_registerWriteToCamera ( SgcCameraHandle cameraHandle,
uint32_t  data,
uint64_t  address 
)

write a 32 bit integer value to a camera register

This function can be used for a direct access to a camera without by bypassing the GenICam XML implementation and register name translations. It might be used, if the register address of the connected camera is known exactly. Data is assumed to be little in little endian byte order

Parameters:
cameraHandle camera handle instance
address address of the camera register (example 0x00002070 "Device version")
data value to write
Return values:
0,: success ERR_SGC_INVALID_CAMHANDLE : the camera handle is not valid
int Sgc_SaveBoardConfiguration ( SgcBoardHandle boardHandle,
const char *  configFileName 
)

save connection parameters of the board to a file

This function can be used to store the current camera connection parameters for all links/cameras to the hard disk. All Connection data like number of links, ordering of the links, link speed and assignment to then applet interface is exported and can be reloaded afterwards. It can be used e.g. after an automatic discovery or a manual setup of link configuration had taken place. The function can be used in combination with Sgc_LoadBoardConfiguration(), which reloads the parameters, that had been saved by using this method.

Parameters:
boardHandle a handle to the according board
configFileName filename
Return values:
0,: success, ERR_SGC_NO_DATA : currently no link configuration present (e.g. if no camera is found) ERR_SGC_FILEACCESS: file access failure when saving to hard disk ERR_SGC_INVALID_DATA: current link configuration is invalid
See also:
Sgc_LoadBoardConfiguration, Sgc_CxpConnect, Sgc_ScanPorts, Sgc_SetCameraProperty
int Sgc_SaveCameraParameters ( SgcCameraHandle cameraHandle,
const char *  paramFileName,
uint32_t  flags 
)

save the current camera parameters to a file

This function can be used to save the values of all camera registers based on the camera's GenICam interface to a file. Purpose of this method is the possibility of exporting and reloading the current state of parametrization of the camera.

Parameters:
cameraHandle a handle to the according camera
paramFileName filename, where to save the data
flags specific flags see :
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid out parameter
See also:
Sgc_LoadCameraParameters, Sgc_connectCamera
int Sgc_scanPorts ( SgcBoardHandle boardHandle,
const unsigned int  portMask,
const int  discoveryTimeout,
const int  speed 
)

Scans the defined ports of the frame grabber for present cameras.

This functions scans the frame grabber ports for present cameras (camera discovery). All defined ports will be checked, if cameras are present. The link discovery procedure will be initiated and possible link aggregations will be detected and established, according to the underlaying interfaces (in this case: CoaxPress). The detected link topology and recommended link speed according to the rules of discovery can be queried later by using the camera handles. Therefor the number of cameras and associated camera handles can be retrieved to get further connection details.

Parameters:
boardHandle Interface object to be released. Retrieved by Sgc_initBoard
portMask bit mask representing the physical frame grabber ports to be scanned
discoveryTimeout timeout,
speed preferred link speed, set to 0 in case of automatic detection at highest speed.
Return values:
0 in case of success, elsewise: error codes ERR_SGC_TOPOLOGY_MISMATCH, ERR_SGC_WAITFORLINK_TIMEOUT,
See also:
Sgc_getCamera, Sgc_getCameraCount
int Sgc_scanPortsEx ( SgcBoardHandle boardHandle,
const unsigned int  portMask,
const int  discoveryTimeout,
const int  speed,
const unsigned int  flags 
)

Scans the defined ports of the frame grabber for present cameras.

This functions scans the frame grabber ports for present cameras (camera discovery). All defined ports will be checked, if cameras are present. The link discovery procedure will be initiated and possible link aggregations will be detected and established, according to the underlaying interfaces (in this case: CoaxPress). The detected link topology and recommended link speed according to the rules of discovery can be queried later by using the camera handles. Therefor the number of cameras and associated camera handles can be retrieved to get further connection details.

Parameters:
boardHandle Interface object to be released. Retrieved by Sgc_initBoard
portMask bit mask representing the physical frame grabber ports to be scanned
discoveryTimeout timeout,
speed preferred link speed, set to 0 in case of automatic detection at highest speed.
flags Bit mask representing specific options, see SGC_SP_FLAG_XXXX
Return values:
0 in case of success, elsewise: error codes ERR_SGC_TOPOLOGY_MISMATCH, ERR_SGC_WAITFORLINK_TIMEOUT,
See also:
Sgc_getCamera, Sgc_getCameraCount
int Sgc_setBoardPropertyWithType ( SgcBoardHandle boardHandle,
const char *  propertyName,
const void *  propertyValue,
const int  propertyType,
void *  additionalValue 
)

set global board properties

This generic function allows to set any board property. The property itself is identified by a null terminated string value according to the defined values. The value has to be saved in variables inside the client and a pointer to this variable has to be passed to this function (parameter propertyValuePtr). The data type of this variable depends on the property itself and might be any standard C data type like integer, double, char[], etc. To allow a check inside the function, the used data type has to be passed at the parameter property type. Constants for definition of the data type passed at the propertyValue parameter can be seen at the SGC_PROPERTY_TYPE_XXX definitions. Some properties need additional addressing. In such cases the data has to be passed at the value parameter. In most cases, this pointer might be set to NULL.

Parameters:
boardHandle a handle to the according board
propertyName property identifier, see PROP_XXX
propertyValue pointer to data structure containing the data to be set e.g.
propertyType data type of the variable passed at the propertyValuePtr parameter
additionalValue additional value for addressing a property, might be NULL
Return values:
0 in case of success, error code (defined in ERR_SGC_XXX)
See also:
Sgc_getErrorDescription, Sgc_getBoardPropertyWithType
int Sgc_setBooleanValue ( SgcCameraHandle cameraHandle,
const char *  name,
unsigned int  value 
)

Set GenICam boolean value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
value value to write ( 1 : true, 0: false)
Return values:
0,: in case of success, <> 0: error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_setCameraPropertyWithType ( SgcCameraHandle cameraHandle,
const char *  propertyName,
const void *  value,
int  propertyType,
void *  additionalValue 
)

set camera or camera connection specific properties

This generic function allows to get various camera properties like current link speed, current stream packet size, state of connection etc. The available properties are defined at the CAM_PROP_XXX constants. Due to the variety of these parameters, the generic functions uses a void pointer to give access to any of these. The type of data (pointer to integer, pointer to double etc.) have to be passed at the property type parameter in order to allow a minimum check for data security. The available types are listed at the SGC_PROPERTY_TYPE_XXX constants. Some parameter need additional information to address the value correctly. In such cases, the pointer named value has to be used.

Parameters:
cameraHandle camera handle instance
propertyName string containing the name of property to be accessed. For valid values see CAM_PROP_XXX constants
value pointer to data structure, where the result value should be used. Needs to be large enough to carry the data completely.
propertyType type of data given at parameter propertyValuePtr see SGC_PROPERTY_TYPE_XXX constants
additionalValue additional parameter to address the the property (multi-purpose)
Return values:
0,: success ERR_SGC_INVALID_ARG : a needed data structure was not initialized or a data is not accepted ERR_SGC_INVALID_PROPERTY: tried to access an invalid property
int Sgc_setEnumerationValue ( SgcCameraHandle cameraHandle,
const char *  name,
const char *  value 
)

Set GenICam enumeration value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
value enum value to write as text, e.g. "Mono8"
Return values:
0 in case of success, error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_setFloatValue ( SgcCameraHandle cameraHandle,
const char *  name,
double  value 
)

Set GenICam floating point value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
value value to be set
Return values:
0,: in case of success, <> 0: error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_setGenICamXML ( SgcCameraHandle cameraHandle,
const char *  buffer,
const size_t  bufferSize 
)

sets the currently GenICam-XML from a buffer

Parameters:
cameraHandle camera handle instance
buffer the buffer, where to copy the data, if NULL, the required buffer size is returned
bufferSize the size of the buffer
Return values:
0 in case of success, error code (defined in ERR_SGC_XXX)
See also:
Sgc_getErrorDescription
int Sgc_setIntegerValue ( SgcCameraHandle cameraHandle,
const char *  name,
int64_t  value 
)

Set GenICam Integer value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
value value to be written
Return values:
0:in case of success, <> 0: error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML*
Remarks:
even if the functions prototype uses a 64 bit value as data, the library supports 32 bit integers only according to CoaxPress specification
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_setStringValue ( SgcCameraHandle cameraHandle,
const char *  name,
const char *  value 
)

Set GenICam string value at camera.

Parameters:
cameraHandle camera handle instance
name feature name
value buffer containing a NULL terminated string to be written to the camera
Return values:
0,: in case of success, <> 0: error code (defined in XXX_error.h) ERR_SGC_INVALID_FEATURE feature name cannot be found at the currently loaded GenICam XML
Remarks:
i.g. the string features at a camera are limited to a specific size. The Sgc_setStringValue does not do a check for this size. It is up to the caller to check the length before passing the string to this function.
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_startAcquisition ( SgcCameraHandle cameraHandle,
unsigned int  startCamera 
)

activates the the data flow towards the applet and activates the image acquisition at the camera This function is used in combination with the Fg_StartAcquire() function of the standard frame grabber SDK. Acquisition needs to be started from both sides always: from the applet side (Fg_startAcquire()) and from the camera side (Sgc_startAcquisition()). The order or the commands should be: 1. start grabbing at the applet side (fg_StartAcquire()) and 2. at the camera side. This ensures a correct image transmission. If the sequence is changed, it cannot be guaranteed, that the transferred images are correctly aligned at the beginning of a frame.

Parameters:
cameraHandle camera handle instance
startCamera send the according GenICam command to activate the image acquisition at the camera
Return values:
0 in case of success, error code (defined in XXX_error.h)
See also:
Sgc_connectCamera, Sgc_getErrorDescription
int Sgc_stopAcquisition ( SgcCameraHandle cameraHandle,
unsigned int  stopCamera 
)

stops the the data flow towards the applet and stops the image acquisition at the camera (optionally)

Parameters:
cameraHandle camera handle instance
stopCamera send the according GenICam command to stop the image acquisition at the camera
Return values:
0 in case of success, error code (defined in XXX_error.h)
See also:
Sgc_getErrorDescription
int Sgc_stringReadFromCamera ( SgcCameraHandle cameraHandle,
char *  data,
uint64_t  address,
unsigned int  length 
)

read a string value from a camera register This function can be used for a direct access to a camera without by bypassing the GenICam XML implementation and register name translations. It might be used, if the register address of the connected camera is known exactly.

The data will be copied to the buffer given at the data parameter. This buffer needs to be large enough to store the whole string. The number of bytes to be read have to be passed at the length parameter. The string is not necessarily 0 terminated.

Parameters:
cameraHandle camera handle instance
data address of the camera register (example 0x00002070 "Device version")
address address of the camera register (example 0x00002020 "DeviceModelName")
data pointer to a buffer for the return value
length number of bytes to be read
Return values:
0,: success, ERR_SGC_BUFFER_TOO_SMALL: Buffer too small
int Sgc_UnloadConnectionProfile ( SgcConnectionProfile connectionProfile  ) 

unload a connection profile

This function frees the resources allocated by a previous call to Sgc_LoadConnectionProfile function.

Parameters:
connectionProfile address for the allocated connection profile structure
Return values:
0,: success, ERR_SGC_INVALID_ARG : invalid connection profile address
See also:
Sgc_LoadConnectionProfile