Error Handling

This section describes error handling in this library.More...

Enumerations

enum   IC4_ERROR {
  IC4_ERROR_NOERROR = 0 , IC4_ERROR_UNKNOWN = 1 , IC4_ERROR_INTERNAL = 2 , IC4_ERROR_INVALID_OPERATION = 3 ,
  IC4_ERROR_OUT_OF_MEMORY = 4 , IC4_ERROR_LIBRARY_NOT_INITIALIZED = 5 , IC4_ERROR_DRIVER_ERROR = 6 , IC4_ERROR_INVALID_PARAM_VAL = 7 ,
  IC4_ERROR_CONVERSION_NOT_SUPPORTED = 8 , IC4_ERROR_NO_DATA = 9 , IC4_ERROR_GENICAM_FEATURE_NOT_FOUND = 101 , IC4_ERROR_GENICAM_DEVICE_ERROR = 102 ,
  IC4_ERROR_GENICAM_TYPE_MISMATCH = 103 , IC4_ERROR_GENICAM_ACCESS_DENIED = 106 , IC4_ERROR_GENICAM_NOT_IMPLEMENTED = 107 , IC4_ERROR_GENICAM_VALUE_ERROR = 108 ,
  IC4_ERROR_GENICAM_CHUNKDATA_NOT_CONNECTED = 109 , IC4_ERROR_BUFFER_TOO_SMALL = 50 , IC4_ERROR_SINK_TYPE_MISMATCH = 52 , IC4_ERROR_SNAP_ABORTED = 53 ,
  IC4_ERROR_FILE_FAILED_TO_WRITE_DATA = 201 , IC4_ERROR_FILE_ACCESS_DENIED = 202 , IC4_ERROR_FILE_PATH_NOT_FOUND = 203 , IC4_ERROR_FILE_FAILED_TO_READ_DATA = 204 ,
  IC4_ERROR_DEVICE_INVALID = 13 , IC4_ERROR_DEVICE_NOT_FOUND = 16 , IC4_ERROR_DEVICE_ERROR = 17 , IC4_ERROR_AMBIGUOUS = 18 ,
  IC4_ERROR_PARSE_ERROR = 21 , IC4_ERROR_TIMEOUT = 27 , IC4_ERROR_INCOMPLETE = 34 , IC4_ERROR_SINK_NOT_CONNECTED = 38 ,
  IC4_ERROR_IMAGETYPE_MISMATCH = 39 , IC4_ERROR_SINK_ALREADY_ATTACHED = 40 , IC4_ERROR_SINK_CONNECT_ABORTED = 41 , IC4_ERROR_HANDLER_ALREADY_REGISTERED = 60 ,
  IC4_ERROR_HANDLER_NOT_FOUND = 61
}

Contains the possible error codes. More...

Functions

bool  ic4_get_last_error (enum IC4_ERROR *pError, char *message, size_t *message_length)

Query information about the error of the previous library function call.

Detailed Description

This section describes error handling in this library.

Most functions of this library return a bool indicating success. Some have a designated error return value, e.g. as part of an enumeration type.

If a function fails, it sets a thread-local error value and error message. The error value and error message can be retrieved by calling the ic4_get_last_error() function.

If a function succeeds, the error value and message are cleared.

Enumeration Type Documentation

◆ IC4_ERROR

enum IC4_ERROR

Contains the possible error codes.

Enumerator
IC4_ERROR_NOERROR 

No error occurred, the operation was successful.

IC4_ERROR_UNKNOWN 

An unknown error occurred.

IC4_ERROR_INTERNAL 

An internal error (bug) occurred.

IC4_ERROR_INVALID_OPERATION 

The operation is not valid in the current state.

IC4_ERROR_OUT_OF_MEMORY 

Out of memory.

IC4_ERROR_LIBRARY_NOT_INITIALIZED 

InitLibrary has not been not called.

IC4_ERROR_DRIVER_ERROR 

Device driver behaved unexpectedly.

IC4_ERROR_INVALID_PARAM_VAL 

An invalid parameter was passed in.

IC4_ERROR_CONVERSION_NOT_SUPPORTED 

The operation would require an image format conversion that is not supported.

IC4_ERROR_NO_DATA 

The requested data is not available.

IC4_ERROR_GENICAM_FEATURE_NOT_FOUND 

No matching GenICam feature found.

IC4_ERROR_GENICAM_DEVICE_ERROR 

Error occured writing to device.

IC4_ERROR_GENICAM_TYPE_MISMATCH 

Attempted an operation on the wrong node type, e.g. command_execute on an integer.

IC4_ERROR_GENICAM_ACCESS_DENIED 

Tried to access a camera feature that is currently not accessible.

IC4_ERROR_GENICAM_NOT_IMPLEMENTED 

Tried to access a feature that is not implemented by the current camera.

IC4_ERROR_GENICAM_VALUE_ERROR 

Tried to set an invalid value, e.g. out of range.

IC4_ERROR_GENICAM_CHUNKDATA_NOT_CONNECTED 

Tried to read a value that is only available if chunk data is connected to the property map.

IC4_ERROR_BUFFER_TOO_SMALL 

A supplied buffer was too small to receive all available data.

IC4_ERROR_SINK_TYPE_MISMATCH 

Tried to call a sink type-specific function on an instance of a different sink type.

IC4_ERROR_SNAP_ABORTED 

A snap operation was not completed, because the camera was stopped before all requested frames could be captured.

IC4_ERROR_FILE_FAILED_TO_WRITE_DATA 

Failed to write data to a file.

IC4_ERROR_FILE_ACCESS_DENIED 

Failed to write to a file, because the location was not writable.

IC4_ERROR_FILE_PATH_NOT_FOUND 

Failed to write to a file, because the path was invalid.

IC4_ERROR_FILE_FAILED_TO_READ_DATA 

Failed to read data from a file.

IC4_ERROR_DEVICE_INVALID 

The device has become invalid (e. g. it was unplugged).

IC4_ERROR_DEVICE_NOT_FOUND 

The device was not found.

IC4_ERROR_DEVICE_ERROR 

The device behaved unexpectedly.

IC4_ERROR_AMBIGUOUS 

The parameter did not uniquely identify an item.

IC4_ERROR_PARSE_ERROR 

There was an error parsing the parameter or file.

IC4_ERROR_TIMEOUT 

The requested operation could not be completed before the timeout expired.

IC4_ERROR_INCOMPLETE 

The operation was only partially successful, e.g. not all properties of the grabber could be restored.

IC4_ERROR_SINK_NOT_CONNECTED 

Sink is not yet connected.

IC4_ERROR_IMAGETYPE_MISMATCH 

The passed buffer does not have the expected ImageType.

IC4_ERROR_SINK_ALREADY_ATTACHED 

The sink passed in is already attached to another graph.

IC4_ERROR_SINK_CONNECT_ABORTED 

The sink's connect handler signaled an error.

IC4_ERROR_HANDLER_ALREADY_REGISTERED 

Attempted to register the same notification handler twice.

IC4_ERROR_HANDLER_NOT_FOUND 

Attempted to use a non-existing notification handler.

Function Documentation

◆ ic4_get_last_error()

bool ic4_get_last_error ( enum IC4_ERROR pError,
char *  message,
size_t *  message_length 
)

Query information about the error of the previous library function call.

Parameters
[out]pErrorPointer to a IC4_ERROR value to receive the error code.
[out]messagePointer to a character array to receive an error message.
This parameter is optional and may be NULL.
[in,out]message_lengthPointer to a size_t describing the length of the array pointed to by message.
If message is not NULL, this parameter is required.
The function always writes the actual number of characters required to store the error message.
Returns
true on success.
If pError is NULL, the function fails and returns false.
If message is not NULL and message_length is NULL, the function fails and returns false.
If *message_length is lower than the number of characters required to store the error message, the function fails and returns false.
Note
The last error information is stored in a thread-local way. A call to ic4_get_last_error returns error information about the previous function call that happened on the same thread that ic4_get_last_error is called from.
An error while calling ic4_get_last_error does not update the internally stored last error.