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]	pError	Pointer to a IC4_ERROR value to receive the error code.
[out]	message	Pointer to a character array to receive an error message. This parameter is optional and may be `NULL`.
[in,out]	message_length	Pointer 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.