genapic/GenApiC.h#

GenApi C bindings.

Types#

Functions#

Defines#

Types Documentation#

typedef GENAPI_FILE_HANDLE#

typedef struct GENAPI_FILE_HANDLE_* GENAPI_FILE_HANDLE;

A handle for a GenApi file object.

typedef NODE_CALLBACK_HANDLE#

typedef struct NODE_CALLBACK_HANDLE_* NODE_CALLBACK_HANDLE;

A handle for a node callback object.

typedef NODE_HANDLE#

typedef struct NODE_HANDLE_* NODE_HANDLE;

A handle for a node object.

typedef NodeCallbackFunction_t#

typedef void NodeCallbackFunction_t(NODE_HANDLE h);

typedef NODEMAP_HANDLE#

typedef struct NODEMAP_HANDLE_* NODEMAP_HANDLE;

A handle for a node map object.

Functions Documentation#

function GenApiBooleanGetValue#

GENAPIC_RESULT GenApiBooleanGetValue(
    NODE_HANDLE hNode,
    _Bool * pValue
)

Return a node's boolean value.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Get the boolean value of a node. The function will fail if the node is of a type that has no such value.

function GenApiBooleanSetValue#

GENAPIC_RESULT GenApiBooleanSetValue(
    NODE_HANDLE hNode,
    _Bool value
)

Set a node's boolean value.

Parameters:

• hNode Node to operate on
• value Boolean value to set

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Set the node to a particular boolean value. The function will fail if the node is of a type that has no such value.

function GenApiCategoryGetFeatureByIndex#

GENAPIC_RESULT GenApiCategoryGetFeatureByIndex(
    NODE_HANDLE hNode,
    size_t index,
    NODE_HANDLE * phEntry
)

Get a feature node from a category by its index.

Parameters:

• hNode Category node handle
• index Index in category
• phEntry result node handle pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Returns a NODE_HANDLE for a feature node identified by its index. Using the value returned by GenApiCategoryGetNumFeatures(), this can be used to implement a loop to iterate over all feature nodes in a given category.

function GenApiCategoryGetNumFeatures#

GENAPIC_RESULT GenApiCategoryGetNumFeatures(
    NODE_HANDLE hNode,
    size_t * pValue
)

Returns the number of features in a category.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the number of feature nodes that a category node manages.

function GenApiCommandExecute#

GENAPIC_RESULT GenApiCommandExecute(
    NODE_HANDLE hNode
)

Trigger the execution of a command.

Parameters:

• hNode Node to operate on

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Execute the command associated with a command node.

function GenApiCommandIsDone#

GENAPIC_RESULT GenApiCommandIsDone(
    NODE_HANDLE hNode,
    _Bool * pValue
)

Check whether command has finished.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

After initiating a command using GenApiCommandExecute(), use this function to check whether the command has run to completion.

function GenApiEnumerationEntryGetSymbolic#

GENAPIC_RESULT GenApiEnumerationEntryGetSymbolic(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return the symbolic name of an enumeration entry node.

Parameters:

• hNode Node to operate on
• pBuf Pointer to user-supplied character buffer, or NULL
• pBufLen Pointer to actual buffer size

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the symbolic name of an 'enumeration entry' node. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiEnumerationEntryGetValue#

GENAPIC_RESULT GenApiEnumerationEntryGetValue(
    NODE_HANDLE hNode,
    int * pValue
)

Returns the numerical index of an enumeration entry.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the numerical index of an 'enumeration entry' node.

function GenApiEnumerationGetEntryByIndex#

GENAPIC_RESULT GenApiEnumerationGetEntryByIndex(
    NODE_HANDLE hNode,
    size_t index,
    NODE_HANDLE * pEntry
)

Get an entry from an enumeration by index.

Parameters:

• hNode Node to operate on
• index Index of entry to get
• pEntry Pointer to variable receiving result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return a handle for an enumeration entry node identified by a numerical index. Using the number of entries returned by GenApiEnumerationGetNumEntries(), this can be used to iterate over every enumeration entry contained in an enumeration.

function GenApiEnumerationGetEntryByName#

GENAPIC_RESULT GenApiEnumerationGetEntryByName(
    NODE_HANDLE hNode,
    const char * pName,
    NODE_HANDLE * pEntry
)

Get an entry from an enumeration by name.

Parameters:

• hNode Node to operate on
• pName Name of entry to get
• pEntry Pointer to variable receiving result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return a handle for an enumeration entry node identified by its name.

function GenApiEnumerationGetNumEntries#

GENAPIC_RESULT GenApiEnumerationGetNumEntries(
    NODE_HANDLE hNode,
    size_t * pValue
)

Get the number of entries in an enumeration.

Parameters:

• hNode Node to operate on
• pValue Pointer to variable receiving result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Get the number of entries for an enumeration node.

function GenApiFileClose#

GENAPIC_RESULT GenApiFileClose(
    GENAPI_FILE_HANDLE hFile
)

Closes a file.

Parameters:

• hFile The file handle.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Closes a file. The handle is invalid after closing.

function GenApiFileExists#

GENAPIC_RESULT GenApiFileExists(
    NODEMAP_HANDLE hMap,
    const char * pFileName,
    _Bool * pResult
)

Check whether a file exists.

Parameters:

• hMap Device Node map handle.
• pFileName The name of the file.
• pResult Returns true if the file exists.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Check whether a file exists.

function GenApiFileOpen#

GENAPIC_RESULT GenApiFileOpen(
    NODEMAP_HANDLE hMap,
    const char * pFileName,
    EGenApiFileAccessMode accessMode,
    GENAPI_FILE_HANDLE * phFile
)

Opens a file.

Parameters:

• hMap Device Node map handle.
• pFileName The name of the file.
• accessMode Specifies read or write access.
• phFile Returns the file handle.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Only one file can be opened at a time per node map. The file is automatically closed if the node map is destroyed.

function GenApiFileRead#

GENAPIC_RESULT GenApiFileRead(
    GENAPI_FILE_HANDLE hFile,
    void * pBuffer,
    size_t * pLength
)

Reads binary data from a file.

Parameters:

• hFile The file handle.
• pBuffer The data buffer.
• pLength Specifies the size of the buffer. Returns the count of bytes read.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

The end of file is reached if zero bytes are returned and the return error code is GENAPI_E_OK.

function GenApiFilesAreSupported#

GENAPIC_RESULT GenApiFilesAreSupported(
    NODEMAP_HANDLE hMap,
    _Bool * pResult
)

Check whether the device supports accessing files.

Parameters:

• hMap Device Node map handle.
• pResult Returns true if files are supported.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Check whether the device supports accessing files.

function GenApiFileWrite#

GENAPIC_RESULT GenApiFileWrite(
    GENAPI_FILE_HANDLE hFile,
    const void * pBuffer,
    size_t length
)

Writes binary data to a file.

Parameters:

• hFile The file handle.
• pBuffer The data buffer.
• length Specifies the number of bytes to write.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Writes binary data to a file.

function GenApiFloatGetMax#

GENAPIC_RESULT GenApiFloatGetMax(
    NODE_HANDLE hNode,
    double * pValue
)

Get a node's maximum floating-point value.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the maximum floating-point value of a node.

function GenApiFloatGetMin#

GENAPIC_RESULT GenApiFloatGetMin(
    NODE_HANDLE hNode,
    double * pValue
)

Get a node's minimum floating-point value.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the minimum floating-point value of a node.

function GenApiFloatGetRepresentation#

GENAPIC_RESULT GenApiFloatGetRepresentation(
    NODE_HANDLE hNode,
    EGenApiRepresentation * pValue
)

Get a node's preferred representation.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the preferred representation for the node's value. This value is a hint telling how the value should best be represented in a graphical user interface.

function GenApiFloatGetUnit#

GENAPIC_RESULT GenApiFloatGetUnit(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return a floating-point node's unit.

Parameters:

• hNode Node to operate on
• pBuf Buffer to receive result
• pBufLen Result buffer size

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for the unit that applies to its value. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiFloatGetValue#

GENAPIC_RESULT GenApiFloatGetValue(
    NODE_HANDLE hNode,
    double * pValue
)

Get a node's floating-point value without validation.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the floating-point value of a node. No validation is performed on the value returned.

function GenApiFloatGetValueEx#

GENAPIC_RESULT GenApiFloatGetValueEx(
    NODE_HANDLE hNode,
    _Bool verify,
    double * pValue
)

Return a node's floating-point value with optional validation.

Parameters:

• hNode Node to operate on
• verify Boolean switch to enable validation
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the floating-point value of a node. If verify equals true, the result value is checked to ensure that it does not violate any of the node's constraints.

function GenApiFloatSetValue#

GENAPIC_RESULT GenApiFloatSetValue(
    NODE_HANDLE hNode,
    double value
)

Set a node's floating-point value with mandatory validation.

Parameters:

• hNode Node to operate on
• value Value to set

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Set the node to a particular value. The function will fail if the value to be set conflicts with any relevant constraints.

function GenApiFloatSetValueEx#

GENAPIC_RESULT GenApiFloatSetValueEx(
    NODE_HANDLE hNode,
    _Bool verify,
    double value
)

Set a node's floating-point value with optional validation.

Parameters:

• hNode Node to operate on
• verify Boolean switch to enable validation
• value Value to set

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Set the node to a particular value. If verify equals true, the function will fail if the value to be set conflicts with any relevant constraints.

function GenApiGetLastErrorDetail#

GENAPIC_RESULT GenApiGetLastErrorDetail(
    char * pBuf,
    size_t * pBufLen
)

Get detailed textual description for the latest error details, e.g. the origin of the error.

Parameters:

• pBuf Pointer to the user-supplied character buffer, or NULL
• pBufLen Pointer to the actual buffer size

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Whenever a function reports an error, it also sets up a string that describes the error in more detail than the brief error message returned by GenApiGetLastErrorMessage(). This function can be used to retrieve that description by copying it to a user-provided buffer. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiGetLastErrorMessage#

GENAPIC_RESULT GenApiGetLastErrorMessage(
    char * pBuf,
    size_t * pBufLen
)

Get a brief textual description of the latest error.

Parameters:

• pBuf Pointer to user-supplied character buffer, or NULL
• pBufLen Pointer to the actual buffer size

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Whenever a function reports an error, it also sets up a string description for it. This function can be used to retrieve that description by copying it to a user-provided buffer. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiIntegerGetInc#

GENAPIC_RESULT GenApiIntegerGetInc(
    NODE_HANDLE hNode,
    int64_t * pValue
)

Get the value increment from an integer node.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the integer value increment of a node.

function GenApiIntegerGetMax#

GENAPIC_RESULT GenApiIntegerGetMax(
    NODE_HANDLE hNode,
    int64_t * pValue
)

Get the maximum value from an integer node.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the maximum integer value of a node.

function GenApiIntegerGetMin#

GENAPIC_RESULT GenApiIntegerGetMin(
    NODE_HANDLE hNode,
    int64_t * pValue
)

Get the minimum value from an integer node.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the minimum integer value of a node.

function GenApiIntegerGetRepresentation#

GENAPIC_RESULT GenApiIntegerGetRepresentation(
    NODE_HANDLE hNode,
    EGenApiRepresentation * pValue
)

Get a node's preferred representation.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the preferred representation for the node's value. This value is a hint telling how the value should best be represented in a graphical user interface.

function GenApiIntegerGetValue#

GENAPIC_RESULT GenApiIntegerGetValue(
    NODE_HANDLE hNode,
    int64_t * pValue
)

Get a node's integer value without validation.

Parameters:

• hNode Node to operate on
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the integer value of a node. No validation is performed on the value returned.

function GenApiIntegerGetValueEx#

GENAPIC_RESULT GenApiIntegerGetValueEx(
    NODE_HANDLE hNode,
    _Bool verify,
    int64_t * pValue
)

Return a node's integer value with optional validation.

Parameters:

• hNode Node to operate on
• verify Boolean switch to enable validation
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the integer value of a node. If verify equals true, the result value is checked to ensure that it does not violate any of the node's constraints.

function GenApiIntegerSetValue#

GENAPIC_RESULT GenApiIntegerSetValue(
    NODE_HANDLE hNode,
    int64_t value
)

Set a node's integer value with mandatory validation.

Parameters:

• hNode Node to operate on
• value Value to set

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Set the node to a particular value. The function will fail if the value to be set conflicts with any relevant constraints.

function GenApiIntegerSetValueEx#

GENAPIC_RESULT GenApiIntegerSetValueEx(
    NODE_HANDLE hNode,
    _Bool verify,
    int64_t value
)

Set a node's integer value with optional validation.

Parameters:

• hNode Node to operate on
• verify Boolean switch to enable validation
• value Value to set

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Set the node to a particular value. If verify equals true, the function will fail if the value to be set conflicts with any relevant constraints.

function GenApiNodeDeregisterCallback#

GENAPIC_RESULT GenApiNodeDeregisterCallback(
    NODE_HANDLE hNode,
    NODE_CALLBACK_HANDLE hCb
)

Remove a node callback function.

Parameters:

• hNode Node to operate on
• hCb Callback handle

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Remove a callback function previously installed by GenApiNodeRegisterCallback() from a node.

function GenApiNodeFromString#

GENAPIC_RESULT GenApiNodeFromString(
    NODE_HANDLE hNode,
    const char * pString
)

Set a node's value from a text string with mandatory validation.

Parameters:

• hNode Node to operate on
• pString Buffer containing text string

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

This function takes a text string in pString and tries to convert it to a value to set the node to. This may fail for a number of reasons, e.g. due to the node not being writeable or not having a value that could be set. The function will also fail if the value to be set conflicts with any relevant constraints.

function GenApiNodeFromStringEx#

GENAPIC_RESULT GenApiNodeFromStringEx(
    NODE_HANDLE hNode,
    _Bool verify,
    const char * pString
)

Set a node's value from a text string with optional validation.

Parameters:

• hNode Node to operate on
• verify Boolean switch to enable validation
• pString Buffer containing text string

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

This function takes a text string in pString and tries to convert it to a value to set the node to. This may fail for a number of reasons, e.g. due to the node not being writeable or not having a value that could be set. If verify equals true, the function will also fail if the value to be set conflicts with any relevant constraints.

function GenApiNodeGetAccessMode#

GENAPIC_RESULT GenApiNodeGetAccessMode(
    NODE_HANDLE hNode,
    EGenApiAccessMode * pAccessMode
)

Query node for allowed access modes.

Parameters:

• hNode Node to operate on
• pAccessMode Pointer to variable receiving access mode

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

The value returned in the variable pointed to by pAccessMode indicates what kinds of access are allowed for the node referred to by hNode.

function GenApiNodeGetAlias#

GENAPIC_RESULT GenApiNodeGetAlias(
    NODE_HANDLE hNode,
    NODE_HANDLE * phNode
)

Get a node's alias.

Parameters:

• hNode Node to operate on
• phNode Result pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

This function returns a node's alias if available. An invalid handle is returned if no alias exists. If an alias exists, a handle for the alias node is returned in the variable pointed to by phNode.

function GenApiNodeGetCachingMode#

GENAPIC_RESULT GenApiNodeGetCachingMode(
    NODE_HANDLE hNode,
    EGenApiCachingMode * pCachingMode
)

Query node for its caching mode.

Parameters:

• hNode Node to operate on
• pCachingMode Pointer to variable receiving result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Caching may be implemented differently for nodes with different characteristics. There is an enumerated type EGenApiCachingMode that is used to encode the caching strategy for a particular node. Use this function to get a node's caching mode.

function GenApiNodeGetDescription#

GENAPIC_RESULT GenApiNodeGetDescription(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return a node's description text.

Parameters:

• hNode Node to operate on
• pBuf Buffer to receive result
• pBufLen Result buffer size on input and buffer size needed on output

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for its associated 'description' text. This is a text string describing the node and its purpose in some more detail than GenApiNodeGetToolTip(), suitable for being displayed as an on-line help by interactive programs that offer access to the node. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiNodeGetDisplayName#

GENAPIC_RESULT GenApiNodeGetDisplayName(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return a node's user-friendly name.

Parameters:

• hNode Node to operate on
• pBuf Buffer to receive result
• pBufLen Result buffer size on input and buffer size needed on output

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for its associated 'user-friendly' name. While the node name returned by GenApiNodeGetName() is meant to be a unique identification tag, this is a more descriptive name meant to be used to identify a node in a dialog. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiNodeGetName#

GENAPIC_RESULT GenApiNodeGetName(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return a node's name.

Parameters:

• hNode Node to operate on
• pBuf Buffer to receive result
• pBufLen Result buffer size on input and buffer size needed on output

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for its name. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiNodeGetNameSpace#

GENAPIC_RESULT GenApiNodeGetNameSpace(
    NODE_HANDLE hNode,
    EGenApiNameSpace * pNamespace
)

Return a node's name space.

Parameters:

• hNode Node to operate on
• pNamespace Pointer to variable receiving name space

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for the name space (custom or standard) it belongs to.

function GenApiNodeGetPollingTime#

GENAPIC_RESULT GenApiNodeGetPollingTime(
    NODE_HANDLE hNode,
    int64_t * pPollingTime
)

Query a node for its recommended polling interval.

Parameters:

• hNode Node to operate on
• pPollingTime Pointer to variable receiving result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Nodes that are subject to asynchronous state changes must be periodically queried (polled) in order to detect state changes. Such nodes have an associated attribute specifying a recommended polling interval in milliseconds. Use this function to get that value.

function GenApiNodeGetToolTip#

GENAPIC_RESULT GenApiNodeGetToolTip(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return a node's tool tip text.

Parameters:

• hNode Node to operate on
• pBuf Buffer to receive result
• pBufLen Result buffer size on input and buffer size needed on output

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for its associated 'tool tip' text. This is a text string briefly describing the node and its purpose, suitable for being displayed as a pop-up by interactive programs that offer access to the node. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiNodeGetType#

GENAPIC_RESULT GenApiNodeGetType(
    NODE_HANDLE hNode,
    EGenApiNodeType * pType
)

Get node type.

Parameters:

• hNode Node to operate on
• pType Result pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for its type.

function GenApiNodeGetVisibility#

GENAPIC_RESULT GenApiNodeGetVisibility(
    NODE_HANDLE hNode,
    EGenApiVisibility * pVisibility
)

Return a node's visibility.

Parameters:

• hNode Node to operate on
• pVisibility Pointer to variable receiving visibility

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Query the node represented by hNode for its level of visibility (Beginner, Expert, Guru, or Invisible).

function GenApiNodeImposeAccessMode#

GENAPIC_RESULT GenApiNodeImposeAccessMode(
    NODE_HANDLE hNode,
    EGenApiAccessMode imposedAccessMode
)

Modify a node's accessibility.

Parameters:

• hNode Node to operate on
• imposedAccessMode Desired new access mode

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Whether a particular node allows read, write, or any access at all, is encoded in its access mode. The original access mode for a node, which is computed taking into account node interdependencies, can be further restricted by means of this function. It is not possible to set the access mode to one more permissive than the original mode. An attempt to do so will be ignored.

function GenApiNodeImposeVisibility#

GENAPIC_RESULT GenApiNodeImposeVisibility(
    NODE_HANDLE hNode,
    EGenApiVisibility imposedVisibility
)

Modify a node's visibility.

Parameters:

• hNode Node to operate on
• imposedVisibility Desired new visibility

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

A particular node is only visible if the current user level is set at least as high as the node's visibility. This function can be used to further limit a node's visibility. The function cannot be used to increase a node's visibility (so that it would become visible at a lower user level). Any attempt to do so will have no effect.

function GenApiNodeInvalidateNode#

GENAPIC_RESULT GenApiNodeInvalidateNode(
    NODE_HANDLE hNode
)

Mark node as possibly changed.

Parameters:

• hNode Node to operate on

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Calling this function invalidates the currently cached status for the node. Then, callbacks for all dependent nodes are triggered.

function GenApiNodeIsAvailable#

GENAPIC_RESULT GenApiNodeIsAvailable(
    NODE_HANDLE hNode,
    _Bool * pResult
)

Check whether a feature's value is available.

Parameters:

• hNode Node to operate on
• pResult Pointer to variable receiving boolean result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Check whether the value of the feature represented by hNode is currently accessible (GenApiNodeGetAccessMode() returns neither NA nor NI).

function GenApiNodeIsImplemented#

GENAPIC_RESULT GenApiNodeIsImplemented(
    NODE_HANDLE hNode,
    _Bool * pResult
)

Check whether a feature is implemented.

Parameters:

• hNode Node to operate on
• pResult Pointer to variable receiving boolean result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Check whether the feature represented by hNode is actually implemented (GenApiNodeGetAccessMode() returns not NI).

function GenApiNodeIsReadable#

GENAPIC_RESULT GenApiNodeIsReadable(
    NODE_HANDLE hNode,
    _Bool * pResult
)

Check whether a feature's value is readable.

Parameters:

• hNode Node to operate on
• pResult Pointer to variable receiving boolean result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Check whether the value of the feature represented by hNode can be read (GenApiNodeGetAccessMode() returns RO or RW).

function GenApiNodeIsWritable#

GENAPIC_RESULT GenApiNodeIsWritable(
    NODE_HANDLE hNode,
    _Bool * pResult
)

Check whether a feature's value is writable.

Parameters:

• hNode Node to operate on
• pResult Pointer to variable receiving boolean result

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Check whether the value of the feature represented by hNode can be written (GenApiNodeGetAccessMode() returns WO or RW).

function GenApiNodeMapGetNode#

GENAPIC_RESULT GenApiNodeMapGetNode(
    NODEMAP_HANDLE hMap,
    const char * pName,
    NODE_HANDLE * phNode
)

Find a node by its name.

Parameters:

• hMap Node map handle
• pName Node name to find
• phNode Result pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Use this function to search a node map for a node with a given name. An invalid handle is returned if not found. If found, a handle for the node is returned in the variable pointed to by phNode.

function GenApiNodeMapGetNodeByIndex#

GENAPIC_RESULT GenApiNodeMapGetNodeByIndex(
    NODEMAP_HANDLE hMap,
    size_t index,
    NODE_HANDLE * phNode
)

Find a node by its index.

Parameters:

• hMap Node map handle
• index Index of node to get
• phNode Result pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Translate a numerical index to a node handle. By using GenApiNodeMapGetNumNodes() to get the number of nodes in a node map, this function can be used to get a handle for every node contained, without having to know its name.

function GenApiNodeMapGetNumNodes#

GENAPIC_RESULT GenApiNodeMapGetNumNodes(
    NODEMAP_HANDLE hMap,
    size_t * pValue
)

Get the number of nodes contained in a node map.

Parameters:

• hMap Node map handle
• pValue Result value pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Return the number of nodes contained in a node map. This value can be used to traverse a node map, visiting every node using GenApiNodeMapGetNodeByIndex().

function GenApiNodeMapPoll#

GENAPIC_RESULT GenApiNodeMapPoll(
    NODEMAP_HANDLE hMap,
    int64_t timestamp
)

Poll all nodes in a node map.

Parameters:

• hMap Node map handle
• timestamp Current time stamp in ms

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Poll all nodes in the node map and execute callbacks for those that are expired.

function GenApiNodeRegisterCallback#

GENAPIC_RESULT GenApiNodeRegisterCallback(
    NODE_HANDLE hNode,
    NodeCallbackFunction_t * pCbFunction,
    NODE_CALLBACK_HANDLE * phCb
)

Install a node callback function.

Parameters:

• hNode Node to operate on
• pCbFunction Callback function pointer
• phCb Callback handle

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Note If you need to perform special processing whenever the node's value changes you need to retrieve the value using any of the GetValue functions.

Install a callback function, to be called whenever any of the node's attributes changes. This also includes the access mode of the node.

The callback handle returned can be used to remove the callback using GenApiNodeDeregisterCallback().

function GenApiNodeToString#

GENAPIC_RESULT GenApiNodeToString(
    NODE_HANDLE hNode,
    char * pBuf,
    size_t * pBufLen
)

Return a textual representation of a node's value.

Parameters:

• hNode Node to operate on
• pBuf Buffer to receive result
• pBufLen Result buffer size

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Convert a node's value to a human-readable text string. The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiNodeToStringEx#

GENAPIC_RESULT GenApiNodeToStringEx(
    NODE_HANDLE hNode,
    _Bool verify,
    char * pBuf,
    size_t * pBufLen
)

Return a textual representation of a node's value with optional validation.

Parameters:

• hNode Node to operate on
• verify Boolean switch to enable validation
• pBuf Buffer to receive result
• pBufLen Result buffer size

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Convert a node's value to a human-readable text string, with optional validation. If verify equals true, the node's value is first checked against any relevant constraints, and an error is returned if the value is invalid. This check is not done if verify equals false, in this case, the function behaves identically to GenApiNodeToString(). The buffer passed to this function must be large enough to hold the entire string, including a terminating zero. If the function is called with pBuf set to NULL, the variable pointed to by pBufLen is set to the required buffer size.

function GenApiPortRead#

GENAPIC_RESULT GenApiPortRead(
    NODE_HANDLE hNode,
    void * pBuffer,
    int64_t Address,
    size_t Length
)

Perform a raw read on the port implemented by the node passed.

Parameters:

• hNode Node of the port to read from. Use GenApiNodeMapGetNode to get the node handle.
• pBuffer Points to the buffer to copy the data to.
• Address Address to start reading data from.
• Length Number of bytes to read starting at Address.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Reads raw data from a port implemented by a node. Some nodes (i.e. the "Device" node) can be used to read- and write directly to the device. Specify the address from where to read data. The count of data bytes passed in Length is read. The data read will be written to the buffer passed in pBuffer. Make sure the buffer has at least a size of Length-bytes.

function GenApiPortWrite#

GENAPIC_RESULT GenApiPortWrite(
    NODE_HANDLE hNode,
    const void * pBuffer,
    int64_t Address,
    size_t Length
)

Perform a raw write on the port implemented by the node passed.

Parameters:

• hNode Node of the port to write to. Use GenApiNodeMapGetNode to get the node handle.
• pBuffer Points to the buffer to read the data.
• Address Address where to start writing data to.
• Length Number of bytes to write starting at Address.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Writes raw data to a port implemented by a node. Some nodes (i.e. the "Device" node) can be used to read- and write directly to the device. Specify the address from where to read data. The count of data bytes passed in Length is read. The data written will be read from the buffer passed in pBuffer. Make sure the buffer has at least a size of Length-bytes.

function GenApiRegisterGetAddress#

GENAPIC_RESULT GenApiRegisterGetAddress(
    NODE_HANDLE hNode,
    int64_t * pAddress
)

Returns the address of the register node.

Parameters:

• hNode Node to operate on. Use GenApiNodeMapGetNode() to get the node handle.
• pAddress On sucessful return, the value points to the register address of the node. This parameter must not be NULL.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Returns the length in bytes of the register node. You can use the returned value when calling GenApiRegisterGetValue() or GenApiRegisterSetValue().

function GenApiRegisterGetLength#

GENAPIC_RESULT GenApiRegisterGetLength(
    NODE_HANDLE hNode,
    size_t * pLength
)

Returns the length in bytes of the register node.

Parameters:

• hNode Node to operate on. Use GenApiNodeMapGetNode() to get the node handle.
• pLength On successful return, the value points to the length in bytes of the register node. This parameter must not be NULL.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Returns the length in bytes of the register node. You can use the returned value when calling GenApiRegisterGetValue() or GenApiRegisterSetValue().

function GenApiRegisterGetValue#

GENAPIC_RESULT GenApiRegisterGetValue(
    NODE_HANDLE hNode,
    void * pBuffer,
    size_t * pLength
)

Reads binary data from the register node.

Parameters:

• hNode Node to operate on. Use GenApiNodeMapGetNode() to get the node handle.
• pBuffer Points to the buffer for storing the data read from the node. This parameter must not be NULL.
• pLength On input, the value points to size in bytes of the buffer passed in pBuffer. Use GenApiRegisterGetLength() to get the length of the register. On successful return, it will point to the number of bytes written to pBuffer. This parameter must not be NULL.

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Read binary data from a register node. The data retrieved will be written to the buffer passed in pBuffer. You can retrieve the length of the register by calling GenApiRegisterGetLength().

function GenApiRegisterSetValue#

GENAPIC_RESULT GenApiRegisterSetValue(
    NODE_HANDLE hNode,
    const void * pBuffer,
    size_t length
)

Writes binary data to the register node.

Parameters:

• hNode Node to operate on. Use GenApiNodeMapGetNode() to get the node handle.
• pBuffer Points to the buffer holding the data to write to the node. This parameter must not be NULL.
• length The number of bytes of the buffer passed in pBuffer. Use GenApiRegisterGetLength() to get the length of the register. This parameter must be less or equal to the value returned by GenApiRegisterGetLength().

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Writes binary data to a register node. You can retrieve the length of the register by calling GenApiRegisterGetLength().

function GenApiSelectorGetNumSelectedFeatures#

GENAPIC_RESULT GenApiSelectorGetNumSelectedFeatures(
    NODE_HANDLE hNode,
    size_t * pValue
)

Return the number of selected nodes.

Parameters:

• hNode Node to operate on
• pValue Number of selected nodes

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Returns the number of nodes selected by this node.

function GenApiSelectorGetNumSelectingFeatures#

GENAPIC_RESULT GenApiSelectorGetNumSelectingFeatures(
    NODE_HANDLE hNode,
    size_t * pValue
)

Return the number of selecting features.

Parameters:

• hNode Node to operate on
• pValue Number of selecting features

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

Returns the number of features selecting this node.

function GenApiSelectorGetSelectedFeatureByIndex#

GENAPIC_RESULT GenApiSelectorGetSelectedFeatureByIndex(
    NODE_HANDLE hNode,
    size_t index,
    NODE_HANDLE * phNode
)

Get a selected node by its index.

Parameters:

• hNode Node to operate on
• index Index in selected nodes
• phNode result node handle pointer of the selected node

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

A feature node may select one or more other features. This function returns a NODE_HANDLE for a selected node identified by its index. Using the value returned by GenApiNodeGetNumSelectedFeatures(), this can be used to implement a loop to iterate over all selected nodes of a given node.

function GenApiSelectorGetSelectingFeatureByIndex#

GENAPIC_RESULT GenApiSelectorGetSelectingFeatureByIndex(
    NODE_HANDLE hNode,
    size_t index,
    NODE_HANDLE * phNode
)

Return a selecting feature by its index.

Parameters:

• hNode Node to operate on
• index Index in selectors
• phNode result node handle pointer

Return: If the function succeeds, the return value is GENAPI_E_OK.

If the function fails, the return value will be any of error codes described in the section ErrorCodes.

A feature node may be selected by one or more other features. This function returns a NODE_HANDLE for a selector node identified by its index. Using the value returned by GenApiNodeGetNumSelectingFeatures(), this can be used to implement a loop to iterate over all selectors of a given node.

Macros Documentation#

define GENAPIC_DECLARE_HANDLE#

#define GENAPIC_DECLARE_HANDLE(
    name
)
struct name##_; typedef struct name##_ *name

define GENAPIC_INVALID_HANDLE#

#define GENAPIC_INVALID_HANDLE ( (void*)0 )

A value for invalid / uninitialized handles.