Common/include/webcam.h File Reference

Webcam library interface definition. More...

Go to the source code of this file.

Data Structures
struct	_CUSBInfo
	USB specific information about a device. More...
struct	_CDevice
	Webcam device information. More...
struct	_CControlRawValue
	A raw control value. More...
struct	_CControlValue
	A value of a control. More...
struct	_CControlChoice
	A list of choices for a choice type of control. More...
struct	_CControl
	A description of a camera control. More...
struct	_CPixelFormat
	A description of a pixel format. More...
struct	_CFrameSize
	A description of one or multiple frame sizes. More...
struct	_CFrameInterval
	A description of one or multiple frame intervals. More...
struct	_CEvent
	An event descriptor. More...
struct	_CDynctrlMessage
	Message returned by the dynamic control configuration parser. More...
struct	_CVersionNumber
	Version number in the "major.minor" format. More...
struct	_CDynctrlInfoListStats
	Statistics on the number of list elements that were processed. More...
struct	_CDynctrlInfo
	Input flags and output data used/returned by the control configuration parser. More...
Typedefs
typedef unsigned int	CHandle
	Device handle for libwebcam.
typedef unsigned int	CResult
	Function return type for libwebcam.
typedef enum _CControlId	CControlId
	Control identifiers.
typedef enum _CControlFlags	CControlFlags
	Flags specifying control properties and capabilities.
typedef enum _CControlType	CControlType
	Types for controls.
typedef enum _CEventId	CEventId
	Event identifiers.
typedef enum _CEventFlags	CEventFlags
	Flags specifying properties of events.
typedef enum _CFrameSizeTypes	CFrameSizeTypes
	Types of frame size specifications.
typedef enum _CFrameIntervalTypes	CFrameIntervalTypes
	Types of frame interval specification.
typedef enum _CDynctrlFlags	CDynctrlFlags
	Flags specifying control properties and capabilities.
typedef enum _CDynctrlMessageSeverity	CDynctrlMessageSeverity
	Severity levels for messages returned by the dynamic control functions.
typedef struct _CUSBInfo	CUSBInfo
	USB specific information about a device.
typedef struct _CDevice	CDevice
	Webcam device information.
typedef struct _CControlRawValue	CControlRawValue
	A raw control value.
typedef struct _CControlValue	CControlValue
	A value of a control.
typedef struct _CControlChoice	CControlChoice
	A list of choices for a choice type of control.
typedef struct _CControl	CControl
	A description of a camera control.
typedef struct _CPixelFormat	CPixelFormat
	A description of a pixel format.
typedef struct _CFrameSize	CFrameSize
	A description of one or multiple frame sizes.
typedef struct _CFrameInterval	CFrameInterval
	A description of one or multiple frame intervals.
typedef struct _CEvent	CEvent
	An event descriptor.
typedef struct _CDynctrlMessage	CDynctrlMessage
	Message returned by the dynamic control configuration parser.
typedef struct _CVersionNumber	CVersionNumber
	Version number in the "major.minor" format.
typedef struct _CDynctrlInfoListStats	CDynctrlInfoListStats
	Statistics on the number of list elements that were processed.
typedef struct _CDynctrlInfo	CDynctrlInfo
	Input flags and output data used/returned by the control configuration parser.
typedef void(*	CEventHandler )(CHandle hDevice, CEventId event_id, void *context)
	Prototype for event handlers.
Enumerations
enum	_CResults {   C_SUCCESS = 0, C_NOT_IMPLEMENTED, C_INIT_ERROR, C_INVALID_ARG,   C_INVALID_HANDLE, C_INVALID_DEVICE, C_NOT_EXIST, C_NOT_FOUND,   C_BUFFER_TOO_SMALL, C_SYNC_ERROR, C_NO_MEMORY, C_NO_HANDLES,   C_V4L2_ERROR, C_SYSFS_ERROR, C_PARSE_ERROR, C_CANNOT_WRITE,   C_CANNOT_READ }
	Return values for libwebcam functions. More...
enum	_CControlId {   CC_BRIGHTNESS = 1, CC_CONTRAST, CC_GAIN, CC_SATURATION,   CC_HUE, CC_GAMMA, CC_SHARPNESS, CC_WHITE_BALANCE_TEMPERATURE,   CC_AUTO_WHITE_BALANCE_TEMPERATURE, CC_WHITE_BALANCE_COMPONENT, CC_AUTO_WHITE_BALANCE_COMPONENT, CC_BACKLIGHT_COMPENSATION,   CC_POWER_LINE_FREQUENCY, CC_AUTO_HUE, CC_AUTO_EXPOSURE_MODE, CC_AUTO_EXPOSURE_PRIORITY,   CC_EXPOSURE_TIME_ABSOLUTE, CC_EXPOSURE_TIME_RELATIVE, CC_AUTO_FOCUS, CC_FOCUS_ABSOLUTE,   CC_FOCUS_RELATIVE, CC_IRIS_ABSOLUTE, CC_IRIS_RELATIVE, CC_ZOOM_ABSOLUTE,   CC_ZOOM_RELATIVE, CC_DIGITAL_ZOOM, CC_PAN_ABSOLUTE, CC_PAN_RELATIVE,   CC_TILT_ABSOLUTE, CC_TILT_RELATIVE, CC_ROLL_ABSOLUTE, CC_ROLL_RELATIVE,   CC_PRIVACY, CC_PAN_RESET, CC_TILT_RESET, CC_V4L2_BASE = 0x1000,   CC_V4L2_CUSTOM_BASE = 0x2000, CC_V4L2_MPEG_BASE = 0x3000, CC_V4L2_CAMERA_CLASS_BASE = 0x4000, CC_LOGITECH_BASE = 0x046d0000,   CC_LOGITECH_PANTILT_RELATIVE, CC_LOGITECH_PANTILT_RESET, CC_LOGITECH_LED1_MODE, CC_LOGITECH_LED1_FREQUENCY,   CC_LOGITECH_DISABLE_PROCESSING, CC_LOGITECH_RAW_BITS_PER_PIXEL }
	Control identifiers. More...
enum	_CControlFlags {   CC_CAN_READ = 1 << 0, CC_CAN_WRITE = 1 << 1, CC_CAN_NOTIFY = 1 << 2, CC_IS_CUSTOM = 1 << 8,   CC_IS_RELATIVE = 1 << 9, CC_IS_ACTION = 1 << 10 }
	Flags specifying control properties and capabilities. More...
enum	_CControlType {   CC_TYPE_RAW = 1, CC_TYPE_BOOLEAN, CC_TYPE_CHOICE, CC_TYPE_BYTE,   CC_TYPE_WORD, CC_TYPE_DWORD }
	Types for controls. More...
enum	_CEventId { CE_CONTROL_INVALID = 0 }
	Event identifiers.
enum	_CEventFlags { CE_INVALID = 0 }
	Flags specifying properties of events.
enum	_CFrameSizeTypes { CF_SIZE_DISCRETE = 1, CF_SIZE_CONTINUOUS, CF_SIZE_STEPWISE }
	Types of frame size specifications. More...
enum	_CFrameIntervalTypes { CF_INTERVAL_DISCRETE = 1, CF_INTERVAL_CONTINUOUS, CF_INTERVAL_STEPWISE }
	Types of frame interval specification. More...
enum	_CDynctrlFlags { CD_DONT_VALIDATE = 1 << 0, CD_REPORT_ERRORS = 1 << 1, CD_RETRIEVE_META_INFO = 1 << 2 }
	Flags specifying control properties and capabilities. More...
enum	_CDynctrlMessageSeverity { CD_SEVERITY_ERROR = 2, CD_SEVERITY_WARNING = 3, CD_SEVERITY_INFO = 4 }
	Severity levels for messages returned by the dynamic control functions. More...
Functions
CResult	c_init (void)
	Initializes libwebcam.
void	c_cleanup (void)
	Clean up resources.
CHandle	c_open_device (const char *device_name)
	Opens a camera device.
void	c_close_device (CHandle hDevice)
	Closes a device handle.
CResult	c_enum_devices (CDevice *devices, unsigned int *size, unsigned int *count)
	Enumerates all devices available in the system.
CResult	c_get_device_info (CHandle hDevice, const char *device_name, CDevice *info, unsigned int *size)
	Returns information about a given camera device.
CResult	c_enum_pixel_formats (CHandle hDevice, CPixelFormat *formats, unsigned int *size, unsigned int *count)
	Enumerates all pixel formats supported by the given camera.
CResult	c_enum_frame_sizes (CHandle hDevice, const CPixelFormat *pixelformat, CFrameSize *sizes, unsigned int *size, unsigned int *count)
	Enumerates all frame sizes supported for the given pixel format.
CResult	c_enum_frame_intervals (CHandle hDevice, const CPixelFormat *pixelformat, const CFrameSize *framesize, CFrameInterval *intervals, unsigned int *size, unsigned int *count)
	Enumerates all frame intervals supported for the given pixel format and frame size.
CResult	c_enum_controls (CHandle hDevice, CControl *controls, unsigned int *size, unsigned int *count)
	Enumerates all controls supported by the given device.
CResult	c_set_control (CHandle hDevice, CControlId control_id, const CControlValue *value)
	Sets the value of a device control.
CResult	c_get_control (CHandle hDevice, CControlId control_id, CControlValue *value)
	Returns the value of a device control.
CResult	c_enum_events (CHandle hDevice, CEvent *events, unsigned int *size, unsigned int *count)
	Enumerates the events supported by the given device.
CResult	c_subscribe_event (CHandle hDevice, CEventId event_id, CEventHandler handler, void *context)
	Subscribes the caller to receive the given event.
CResult	c_unsubscribe_event (CHandle hDevice, CEventId event_id)
	Unsubscribes the caller from the given event.
CResult	c_add_control_mappings_from_file (const char *file_name, CDynctrlInfo *info)
	Parses a dynamic controls configuration file and adds the contained controls and control mappings to the UVC driver.
char *	c_get_error_text (CResult error)
	Returns the error message associated with a given error code.
char *	c_get_handle_error_text (CHandle hDevice, CResult error)
	Returns the error message associated with a given error code and device handle.

---

Detailed Description

Webcam library interface definition.

---

Typedef Documentation

typedef struct _CControlChoice CControlChoice

A list of choices for a choice type of control.

See also:

CC_TYPE_CHOICE

typedef enum _CControlId CControlId

Control identifiers.

This is an exhaustive list of all controls supported by libwebcam. As new controls appear, these should be added to this list.

typedef enum _CControlType CControlType

Types for controls.

These types give both hints to graphical user interfaces on how to display the control to the user as well as to the implementation in terms of data length required to store control values.

typedef struct _CFrameInterval CFrameInterval

A description of one or multiple frame intervals.

Each frame interval is described as a fraction of a second.

---

Enumeration Type Documentation

enum _CControlFlags

Flags specifying control properties and capabilities.

Enumerator:

CC_CAN_READ	The control can be read, i.e. its current value can be queried. This flag is usually not set for action controls.
CC_CAN_WRITE	The control can be changed, i.e. it can be set to a new value. Note that this flag does not imply CC_CAN_READ. Action controls accept values but cannot necessarily be queried.
CC_CAN_NOTIFY	The control supports value change notification.

enum _CControlId

Control identifiers.

This is an exhaustive list of all controls supported by libwebcam. As new controls appear, these should be added to this list.

Enumerator:

CC_BRIGHTNESS	Image brightness.
CC_CONTRAST	Image contrast.
CC_GAIN	Gain control.
CC_SATURATION	Image color saturation.
CC_HUE	Hue.
CC_GAMMA	Gamma correction.
CC_SHARPNESS	Image sharpness.
CC_WHITE_BALANCE_TEMPERATURE	White balance color temperature.
CC_AUTO_WHITE_BALANCE_TEMPERATURE	Enable/disable automatic while balance color temperature selection.
CC_WHITE_BALANCE_COMPONENT	White balance color component control (red, blue).
CC_AUTO_WHITE_BALANCE_COMPONENT	Enable/disable automatic white balance color component selection.
CC_BACKLIGHT_COMPENSATION	Backlight compensation mode.
CC_POWER_LINE_FREQUENCY	Local power line frequency for anti-flicker processing.
CC_AUTO_HUE	Enable/disable automatic hue control.
CC_AUTO_EXPOSURE_MODE	Mode for automatic exposure control.
CC_AUTO_EXPOSURE_PRIORITY	Constraints for automatic exposure control (e.g. adaptive vs. constant frame rate).
CC_EXPOSURE_TIME_ABSOLUTE	Length of exposure (electronic shutter speed).
CC_EXPOSURE_TIME_RELATIVE	Relative change to the current length of exposure.
CC_AUTO_FOCUS	Enable/disable automatic focus adjustment.
CC_FOCUS_ABSOLUTE	Distance to optimally focused target.
CC_FOCUS_RELATIVE	Relative change in distance to currently focused target.
CC_IRIS_ABSOLUTE	Aperture setting.
CC_IRIS_RELATIVE	Relative change to the current aperture setting.
CC_ZOOM_ABSOLUTE	Objective lens focal length.
CC_ZOOM_RELATIVE	Relative change to the current objective lens focal length.
CC_DIGITAL_ZOOM	Digital zoom multiplier applied to the optical image.
CC_PAN_ABSOLUTE	Pan angle (rotation on a vertical axis).
CC_PAN_RELATIVE	Relative change to the current pan angle.
CC_TILT_ABSOLUTE	Tilt angle (rotation in a vertical plane).
CC_TILT_RELATIVE	Relative change to the current tilt angle.
CC_ROLL_ABSOLUTE	Roll angle (rotation along the image viewing axis).
CC_ROLL_RELATIVE	Relative change to the current roll angle.
CC_PRIVACY	Temporarily prevent image from being acquired.
CC_PAN_RESET	Reset pan angle to a safe default value.
CC_TILT_RESET	Reset tilt angle to a safe default value.
CC_V4L2_BASE	Base for unknown V4L2 controls.
CC_V4L2_CUSTOM_BASE	Base for custom V4L2 driver controls.
CC_V4L2_MPEG_BASE	Base for unknown V4L2 MPEG controls.
CC_V4L2_CAMERA_CLASS_BASE	Base for unknown V4L2 camera class controls.
CC_LOGITECH_PANTILT_RELATIVE	Relative change to the current pan and tilt angles. This control is specific to Logitech cameras that support panning and tilting such as the QuickCam Orbit series.
CC_LOGITECH_PANTILT_RESET	Reset pan and tilt angles to a safe default value. This control is specific to Logitech cameras that support panning and tilting such as the QuickCam Orbit series.

enum _CControlType

Types for controls.

These types give both hints to graphical user interfaces on how to display the control to the user as well as to the implementation in terms of data length required to store control values.

Enumerator:

CC_TYPE_RAW	The control uses raw binary data. Usually (but not necessarily) this includes values that cannot be easily mapped to simple data types.
CC_TYPE_BOOLEAN	The control knows only one enabled/disabled state. Controls of this type are typically displayed as checkboxes.
CC_TYPE_CHOICE	The control accepts a defined list of values. Controls of this type are typically displayed as combo boxes or lists.
CC_TYPE_BYTE	The control accepts 8-bit integer values.
CC_TYPE_WORD	The control accepts 16-bit integer values.
CC_TYPE_DWORD	The control accepts 32-bit integer values.

enum _CDynctrlFlags

Flags specifying control properties and capabilities.

Enumerator:

CD_DONT_VALIDATE	Disable XML schema validation.
CD_REPORT_ERRORS	Collect errors and warnings during the process.
CD_RETRIEVE_META_INFO	Return meta data during the XML parsing process.

enum _CDynctrlMessageSeverity

Severity levels for messages returned by the dynamic control functions.

Enumerator:

CD_SEVERITY_ERROR	Error.
CD_SEVERITY_WARNING	Warning.
CD_SEVERITY_INFO	Informational.

enum _CFrameIntervalTypes

Types of frame interval specification.

Enumerator:

CF_INTERVAL_DISCRETE	One discrete time interval.
CF_INTERVAL_CONTINUOUS	Minimum and maximum values for the time interval.
CF_INTERVAL_STEPWISE	Minimum, maximum, and step values for the time interval.

enum _CFrameSizeTypes

Types of frame size specifications.

Enumerator:

CF_SIZE_DISCRETE	One discrete width/height combination.
CF_SIZE_CONTINUOUS	Minimum and maximum values for both width and height.
CF_SIZE_STEPWISE	Minimum, maximum, and step values for both width and height.

enum _CResults

Return values for libwebcam functions.

Enumerator:

C_SUCCESS	Success.
C_NOT_IMPLEMENTED	The function is not implemented.
C_INIT_ERROR	Error during initialization or library not initialized.
C_INVALID_ARG	Invalid argument.
C_INVALID_HANDLE	Invalid handle.
C_INVALID_DEVICE	Invalid device or device cannot be opened.
C_NOT_EXIST	The device to which the handle points no longer exists.
C_NOT_FOUND	Object not found.
C_BUFFER_TOO_SMALL	Buffer too small.
C_SYNC_ERROR	Error during data synchronization.
C_NO_MEMORY	Out of memory.
C_NO_HANDLES	Out of handles.
C_V4L2_ERROR	A Video4Linux2 API call returned an unexpected error.
C_SYSFS_ERROR	A sysfs file access returned an error.
C_PARSE_ERROR	A control could not be parsed.
C_CANNOT_WRITE	Writing not possible (e.g. read-only control).
C_CANNOT_READ	Reading not possible (e.g. write-only control).

---

Function Documentation

CResult c_add_control_mappings_from_file	(	const char *	file_name,
		CDynctrlInfo *	info
	)

Parses a dynamic controls configuration file and adds the contained controls and control mappings to the UVC driver.

Notes:

• Just because the function returns C_SUCCESS doesn't mean there were no errors. The dynamic controls parsing process tries to be very forgiving on syntax errors or if processing of a single control/mapping fails. Check the info->messages list for details after processing is done.
• If the info parameter is not NULL the caller must free the info->messages field if it is not NULL.
• Note that this function is not thread-safe.

Parameters:

	file_name	name of the device to open.
	info	structure to pass operation flags and retrieve status information. Can be NULL.

Returns:

• C_INIT_ERROR if the library has not been initialized
• C_INVALID_DEVICE if no supported devices are available
• C_NO_MEMORY if memory could not be allocated
• C_SUCCESS if the parsing was successful and no fatal error occurred
• C_NOT_IMPLEMENTED if libwebcam was compiled with dynctrl support disabled

References add_control_mappings(), add_error(), add_info(), C_BUFFER_TOO_SMALL, C_CANNOT_WRITE, c_close_device(), c_enum_devices(), c_get_handle_error_text(), C_INIT_ERROR, C_INVALID_DEVICE, C_NO_MEMORY, C_NOT_IMPLEMENTED, c_open_device(), C_SUCCESS, _ParseContext::cd, _ParseContext::constants, _ParseContext::controls, _CDevice::driver, _ParseContext::handle, _UVCXUControl::id, _ParseContext::info, initialized, _Constant::name, _UVCXUControl::next, _Constant::next, parse_dynctrl_file(), and _CDevice::shortName.

void c_cleanup

(

void

)

Clean up resources.

This method should be called when the library is no longer used.

References cleanup_device_list(), initialized, invalidate_device_list(), lock_mutex(), _HandleList::mutex, _DeviceList::mutex, and unlock_mutex().

Referenced by __attribute__().

void c_close_device

(

CHandle

hDevice

)

Closes a device handle.

Parameters:

hDevice

a handle obtained from c_open_device()

References close_handle(), and initialized.

Referenced by c_add_control_mappings_from_file().

CResult c_enum_controls	(	CHandle	hDevice,
		CControl *	controls,
		unsigned int *	size,
		unsigned int *	count
	)

Enumerates all controls supported by the given device.

If the buffer is not large enough, C_BUFFER_TOO_SMALL is returned and the size parameter is modified to contain the required buffer size.

Parameters:

	hDevice	a device handle obtained from c_open_device()
	controls	a pointer to a buffer that retrieves the list of supported controls.
	size	a pointer to an integer that contains or receives the size of the controls buffer.
	count	a pointer to an integer that receives the number of controls supported. Can be NULL. If this argument is not NULL, the control count is returned independent of whether or not the buffer is large enough.

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_INVALID_HANDLE if the given device handle is invalid
• C_SYNC_ERROR if the synchronization structures could not be initialized
• C_INVALID_ARG if no size pointer was given or if a size pointer was given but no controls buffer was given
• C_BUFFER_TOO_SMALL if the supplied buffer is not large enough

References C_BUFFER_TOO_SMALL, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_HANDLE, C_NOT_EXIST, C_SUCCESS, C_SYNC_ERROR, CC_TYPE_CHOICE, _CControl::choices, _Control::control, _Device::controls, _ControlList::count, _ControlList::first, get_control_dynamics_length(), GET_HANDLE, HANDLE_OPEN, HANDLE_VALID, initialized, lock_mutex(), _ControlList::mutex, _CControl::name, _Control::next, _CControl::type, and unlock_mutex().

CResult c_enum_devices	(	CDevice *	devices,
		unsigned int *	size,
		unsigned int *	count
	)

Enumerates all devices available in the system.

Users must call c_init() prior to using this function.

If the buffer is not large enough, C_BUFFER_TOO_SMALL is returned and the size parameter is modified to contain the required buffer size.

Parameters:

	devices	a pointer to a buffer that retrieves the list of devices
	size	a pointer to an integer that contains or receives the size of the devices buffer
	count	a pointer to an integer that receives the number of devices available. Can be NULL. If this argument is not NULL, the device count is returned independent of whether or not the buffer is large enough.

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_SYNC_ERROR if the synchronization structures could not be initialized
• C_INVALID_ARG if no size pointer was given or if a size pointer was given but no devices buffer was given
• C_BUFFER_TOO_SMALL if the supplied buffer is not large enough

References C_BUFFER_TOO_SMALL, C_INIT_ERROR, C_INVALID_ARG, C_SUCCESS, C_SYNC_ERROR, copy_string_to_buffer(), _DeviceList::count, _Device::device, _CDevice::driver, _DeviceList::first, get_devices_dynamics_length(), initialized, _CDevice::location, lock_mutex(), _DeviceList::mutex, _CDevice::name, _Device::next, refresh_device_list(), _CDevice::shortName, and unlock_mutex().

Referenced by c_add_control_mappings_from_file().

CResult c_enum_events	(	CHandle	hDevice,
		CEvent *	events,
		unsigned int *	size,
		unsigned int *	count
	)

Enumerates the events supported by the given device.

[unimplemented]

Returns:

• C_INIT_ERROR if the library has not been initialized
• C_NOT_IMPLEMENTED

References C_INIT_ERROR, C_NOT_IMPLEMENTED, and initialized.

CResult c_enum_frame_intervals	(	CHandle	hDevice,
		const CPixelFormat *	pixelformat,
		const CFrameSize *	framesize,
		CFrameInterval *	intervals,
		unsigned int *	size,
		unsigned int *	count
	)

Enumerates all frame intervals supported for the given pixel format and frame size.

If the buffer is not large enough, C_BUFFER_TOO_SMALL is returned and the size parameter is modified to contain the required buffer size.

A list of pixel formats can be obtained from c_enum_pixel_formats(). In a similar manner the list of supported frame sizes for each pixel format can be obtained from c_enum_frame_sizes().

Parameters:

	hDevice	a handle obtained from c_open_device()
	pixelformat	the pixel format for which the frame intervals should be enumerated
	framesize	the frame size for which the frame intervals should be enumerated. Note that this frame size's type must be discrete.
	intervals	a pointer to a buffer that retrieves the list of frame intervals
	size	a pointer to an integer that contains or receives the size of the intervals buffer
	count	a pointer to an integer that receives the number of frame intervals supported for the given pixel format and frame size. Can be NULL. If this argument is not NULL, the frame size count is returned independent of whether or not the buffer is large enough.

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_INVALID_HANDLE if the given device handle is invalid
• C_INVALID_ARG if no size pointer was given; if a size pointer was given but no sizes buffer was given; if pixelformat or framesize were not given; if a non-descrete frame size was given
• C_INVALID_DEVICE if the device could not be opened
• C_BUFFER_TOO_SMALL if the supplied buffer is not large enough
• C_NO_MEMORY if no temporary memory could be allocated
• C_V4L2_ERROR if a V4L2 error occurred during frame interval enumeration

References C_BUFFER_TOO_SMALL, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_DEVICE, C_INVALID_HANDLE, C_NO_MEMORY, C_NOT_EXIST, C_SUCCESS, C_V4L2_ERROR, CF_INTERVAL_CONTINUOUS, CF_INTERVAL_DISCRETE, CF_INTERVAL_STEPWISE, CF_SIZE_DISCRETE, _CPixelFormat::fourcc, GET_HANDLE, HANDLE_OPEN, HANDLE_VALID, _CFrameSize::height, initialized, open_v4l2_device(), set_last_error(), _CFrameSize::type, _Device::v4l2_name, and _CFrameSize::width.

CResult c_enum_frame_sizes	(	CHandle	hDevice,
		const CPixelFormat *	pixelformat,
		CFrameSize *	sizes,
		unsigned int *	size,
		unsigned int *	count
	)

Enumerates all frame sizes supported for the given pixel format.

If the buffer is not large enough, C_BUFFER_TOO_SMALL is returned and the size parameter is modified to contain the required buffer size.

A list of pixel formats can be obtained from c_enum_pixel_formats().

Parameters:

	hDevice	a handle obtained from c_open_device()
	pixelformat	the pixel format for which the frame sizes should be enumerated
	sizes	a pointer to a buffer that retrieves the list of frame sizes
	size	a pointer to an integer that contains or receives the size of the sizes buffer
	count	a pointer to an integer that receives the number of frame sizes supported for the given pixel format. Can be NULL. If this argument is not NULL, the frame size count is returned independent of whether or not the buffer is large enough.

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_INVALID_HANDLE if the given device handle is invalid
• C_INVALID_ARG if no size pointer was given; if a size pointer was given but no sizes buffer was given; if no pixelformat was given
• C_INVALID_DEVICE if the device could not be opened
• C_BUFFER_TOO_SMALL if the supplied buffer is not large enough
• C_NO_MEMORY if no temporary memory could be allocated
• C_V4L2_ERROR if a V4L2 error occurred during frame size enumeration

References C_BUFFER_TOO_SMALL, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_DEVICE, C_INVALID_HANDLE, C_NO_MEMORY, C_NOT_EXIST, C_SUCCESS, C_V4L2_ERROR, CF_SIZE_CONTINUOUS, CF_SIZE_DISCRETE, CF_SIZE_STEPWISE, _CPixelFormat::fourcc, GET_HANDLE, HANDLE_OPEN, HANDLE_VALID, initialized, open_v4l2_device(), set_last_error(), and _Device::v4l2_name.

CResult c_enum_pixel_formats	(	CHandle	hDevice,
		CPixelFormat *	formats,
		unsigned int *	size,
		unsigned int *	count
	)

Enumerates all pixel formats supported by the given camera.

If the buffer is not large enough, C_BUFFER_TOO_SMALL is returned and the size parameter is modified to contain the required buffer size.

Parameters:

	hDevice	a handle obtained from c_open_device()
	formats	a pointer to a buffer that retrieves the list of pixel formats
	size	a pointer to an integer that contains or receives the size of the formats buffer
	count	a pointer to an integer that receives the number of pixel formats supported. Can be NULL. If this argument is not NULL, the device count is returned independent of whether or not the buffer is large enough.

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_INVALID_HANDLE if the given device handle is invalid
• C_INVALID_ARG if no size pointer was given or if a size pointer was given but no formats buffer was given
• C_INVALID_DEVICE if the device could not be opened
• C_BUFFER_TOO_SMALL if the supplied buffer is not large enough
• C_NO_MEMORY if no temporary memory could be allocated
• C_V4L2_ERROR if a V4L2 error occurred during pixel format enumeration

References C_BUFFER_TOO_SMALL, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_DEVICE, C_INVALID_HANDLE, C_NO_MEMORY, C_NOT_EXIST, C_SUCCESS, C_V4L2_ERROR, copy_string_to_buffer(), GET_HANDLE, get_mimetype_from_fourcc(), HANDLE_OPEN, HANDLE_VALID, initialized, _CPixelFormat::mimeType, _CPixelFormat::name, open_v4l2_device(), set_last_error(), and _Device::v4l2_name.

CResult c_get_control	(	CHandle	hDevice,
		CControlId	control_id,
		CControlValue *	value
	)

Returns the value of a device control.

Parameters:

	hDevice	a device handle obtained from c_open_device()
	control_id	the ID of the control whose value shall be read
	value	a pointer to receive the value read

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_INVALID_HANDLE if the given device handle is invalid
• C_INVALID_ARG if no value is given
• C_NOT_FOUND if the device does not support the given control
• C_CANNOT_READ if the given control is not readable
• C_INVALID_DEVICE if the device could not be opened
• C_V4L2_ERROR if a V4L2 error occurred during control access

References C_CANNOT_READ, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_HANDLE, C_NOT_EXIST, C_NOT_FOUND, C_SUCCESS, CC_CAN_READ, _Control::control, find_control_by_id(), _CControl::flags, GET_HANDLE, HANDLE_OPEN, HANDLE_VALID, initialized, read_v4l2_control(), and _Control::v4l2_control.

CResult c_get_device_info	(	CHandle	hDevice,
		const char *	device_name,
		CDevice *	info,
		unsigned int *	size
	)

Returns information about a given camera device.

The function returns information about a device specified using a device handle obtained from c_open_device() or a string that would be recognized by the same function. The hDevice and device_name arguments are mutually exclusive. If both are specified, the handle is used. If the device name should be used, hDevice should be set to zero.

If the buffer is not large enough, C_BUFFER_TOO_SMALL is returned and the size parameter is modified to contain the required buffer size.

Specifying a size of sizeof(CDevice) + strlen(device_name) + 84 will usually be enough. This information can be used to try receiving device information in a statically allocated buffer first. The number comes from the field lengths that V4L2 uses internally. There is no guarantee, however, that this does not change in the future, so applications must be prepared to allocate more memory if indicated by a return value of C_BUFFER_TOO_SMALL.

Parameters:

	hDevice	a handle obtained from c_open_device()
	device_name	a device name as accepted by c_open_device()
	info	a pointer to a buffer to receive the device information
	size	a pointer to an integer that contains or receives the size of the info buffer

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_SYNC_ERROR if the synchronization structures could not be initialized
• C_INVALID_ARG if no size pointer was given or if a size pointer was given but no info buffer was given
• C_INVALID_HANDLE if a non-zero invalid handle was specified
• C_BUFFER_TOO_SMALL if the supplied buffer is not large enough

References C_BUFFER_TOO_SMALL, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_HANDLE, C_NOT_EXIST, C_NOT_FOUND, C_SUCCESS, copy_string_to_buffer(), _Device::device, _CDevice::driver, find_device_by_name(), get_device_dynamics_length(), GET_HANDLE, HANDLE_OPEN, HANDLE_VALID, initialized, _CDevice::location, _CDevice::name, and _CDevice::shortName.

char* c_get_error_text

(

CResult

error

)

Returns the error message associated with a given error code.

Note that the caller must free the buffer returned by this function.

Parameters:

error

error code for which the message should be retrieved

Returns:

• a newly allocated string describing the given error code
• NULL if not enough memory was available or if the error code is unknown

References c_get_handle_error_text().

Referenced by print_c_error().

char* c_get_handle_error_text	(	CHandle	hDevice,
		CResult	error
	)

Returns the error message associated with a given error code and device handle.

Note that the caller must free the buffer returned by this function. Compared to the c_get_error_text() function, this function can take the handle's last system error into account.

Parameters:

	hDevice	an open device handle. If this parameter is 0, the function behaves exactly like c_get_error_text().
	error	error code for which the message should be retrieved

Returns:

• a newly allocated string describing the given error code
• NULL if not enough memory was available or if the error code is unknown

References C_BUFFER_TOO_SMALL, C_CANNOT_READ, C_CANNOT_WRITE, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_DEVICE, C_INVALID_HANDLE, C_NO_HANDLES, C_NO_MEMORY, C_NOT_FOUND, C_NOT_IMPLEMENTED, C_PARSE_ERROR, C_SUCCESS, C_SYNC_ERROR, C_SYSFS_ERROR, C_V4L2_ERROR, GET_HANDLE, and HANDLE_OPEN.

Referenced by c_add_control_mappings_from_file(), and c_get_error_text().

CResult c_init

(

void

)

Initializes libwebcam.

This method must be called prior to using most of the other methods. To release resources allocated during initialization, users should make a call to c_cleanup() when the library is no longer used.

References C_INIT_ERROR, C_SUCCESS, _DeviceList::count, _DeviceList::first, _HandleList::first_free, initialized, _DeviceList::mutex, _HandleList::mutex, and refresh_device_list().

CHandle c_open_device

(

const char *

device_name

)

Opens a camera device.

The function returns a handle that can be used for all functions that require a device handle.

Parameters:

device_name

Name of the device to open. Two different naming schemes are accepted: Full device names (e.g. '/dev/video0') and short names (e.g. 'video0') as returned by c_enum_devices().

Returns:

• a device handle greater than zero on success
• 0 if an error has occurred

References create_handle(), find_device_by_name(), initialized, and print_error().

Referenced by c_add_control_mappings_from_file().

CResult c_set_control	(	CHandle	hDevice,
		CControlId	control_id,
		const CControlValue *	value
	)

Sets the value of a device control.

Parameters:

	hDevice	a device handle obtained from c_open_device()
	control_id	the ID of the control whose value shall be set
	value	the value to which the control shall be set

Returns:

• C_SUCCESS on success
• C_INIT_ERROR if the library has not been initialized
• C_INVALID_HANDLE if the given device handle is invalid
• C_INVALID_ARG if no value is given
• C_NOT_FOUND if the device does not support the given control
• C_CANNOT_WRITE if the given control is not writable
• C_INVALID_DEVICE if the device could not be opened
• C_V4L2_ERROR if a V4L2 error occurred during control access

References C_CANNOT_WRITE, C_INIT_ERROR, C_INVALID_ARG, C_INVALID_HANDLE, C_NOT_EXIST, C_NOT_FOUND, C_SUCCESS, CC_CAN_WRITE, _Control::control, find_control_by_id(), _CControl::flags, GET_HANDLE, HANDLE_OPEN, HANDLE_VALID, initialized, _Control::v4l2_control, and write_v4l2_control().

CResult c_subscribe_event	(	CHandle	hDevice,
		CEventId	event_id,
		CEventHandler	handler,
		void *	context
	)

Subscribes the caller to receive the given event.

[unimplemented]

Returns:

• C_INIT_ERROR if the library has not been initialized
• C_NOT_IMPLEMENTED

References C_INIT_ERROR, C_NOT_IMPLEMENTED, and initialized.

CResult c_unsubscribe_event	(	CHandle	hDevice,
		CEventId	event_id
	)

Unsubscribes the caller from the given event.

[unimplemented]

Returns:

• C_INIT_ERROR if the library has not been initialized
• C_NOT_IMPLEMENTED

References C_INIT_ERROR, C_NOT_IMPLEMENTED, and initialized.