Webcam Library Reference Documentation

Common/include/webcam.h File Reference

Detailed Description

Webcam library interface definition.

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 _CUSBInfo CUSBInfo

USB specific information about a device.

typedef _CDevice CDevice

Webcam device information.

typedef _CControlRawValue CControlRawValue

A raw control value.

typedef _CControlValue CControlValue

A value of a control.

typedef _CControlChoice CControlChoice

A list of choices for a choice type of control.

typedef _CControl CControl

A description of a camera control.

typedef _CPixelFormat CPixelFormat

A description of a pixel format.

typedef _CFrameSize CFrameSize

A description of one or multiple frame sizes.

typedef _CFrameInterval CFrameInterval

A description of one or multiple frame intervals.

typedef _CEvent CEvent

An event descriptor.

typedef _CDynctrlMessage CDynctrlMessage

Message returned by the dynamic control configuration parser.

typedef _CVersionNumber CVersionNumber

Version number in the "major.minor" format.

typedef _CDynctrlInfoListStats CDynctrlInfoListStats

Statistics on the number of list elements that were processed.

typedef _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.

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

void c_cleanup ( void )

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

void c_close_device ( CHandle hDevice )

Closes a device handle.

Parameters:

hDevice a handle obtained from c_open_device()

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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


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 _CUSBInfo	CUSBInfo
	USB specific information about a device.
typedef _CDevice	CDevice
	Webcam device information.
typedef _CControlRawValue	CControlRawValue
	A raw control value.
typedef _CControlValue	CControlValue
	A value of a control.
typedef _CControlChoice	CControlChoice
	A list of choices for a choice type of control.
typedef _CControl	CControl
	A description of a camera control.
typedef _CPixelFormat	CPixelFormat
	A description of a pixel format.
typedef _CFrameSize	CFrameSize
	A description of one or multiple frame sizes.
typedef _CFrameInterval	CFrameInterval
	A description of one or multiple frame intervals.
typedef _CEvent	CEvent
	An event descriptor.
typedef _CDynctrlMessage	CDynctrlMessage
	Message returned by the dynamic control configuration parser.
typedef _CVersionNumber	CVersionNumber
	Version number in the "major.minor" format.
typedef _CDynctrlInfoListStats	CDynctrlInfoListStats
	Statistics on the number of list elements that were processed.
typedef _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.