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.