Webcam library implementation. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <limits.h>
#include <dirent.h>
#include <pthread.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdarg.h>
#include <sys/ioctl.h>
#include <errno.h>
#include "webcam.h"
#include "libwebcam.h"
#include "compat.h"
#include <dynctrl-logitech.h>

Functions
void	print_libwebcam_error (char *format,...)
	Prints a generic error message to stderr.

static void	print_libwebcam_c_error (CResult error, char *format,...)
	Prints a libwebcam error message to stderr. More...

static unsigned int	get_control_dynamics_length (Device device, unsigned int names_length, unsigned int *choices_length)
	Returns the length required to store all the (null-terminated) names of the given device's controls in a buffer. More...

static Control *	find_control_by_id (Device *dev, CControlId id)
	Looks up the control with the given ID for the given device. More...

static CResult	refresh_device_list (void)
	Synchronizes the device list with the information available in sysfs.

static Device *	find_device_by_name (const char *name)
	Searches the device list for the device with the given name.

static int	get_device_dynamics_length (CDevice *device)
	Returns the length required to store all the (null-terminated) strings of the given device in a buffer.

static int	get_devices_dynamics_length (void)
	Returns the length required to store all the (null-terminated) strings of the current devices in a buffer. More...

int	open_v4l2_device (char *device_name)
	Open the V4L2 device node with the given name. More...

static CResult	read_v4l2_control (Device device, Control control, CControlValue *value, CHandle hDevice)
	Retrieves the value of a given V4L2 control.

static CResult	write_v4l2_control (Device device, Control control, const CControlValue *value, CHandle hDevice)
	Changes the value of a given V4L2 control.

static CControlId	get_control_id_from_v4l2 (int v4l2_id, Device *dev)
	Converts a V4L2 control ID to a libwebcam control ID. More...

static CResult	get_device_usb_info (Device device, CUSBInfo usbinfo)
	Reads the USB information for the given device into the given CUSBInfo structure.

static CResult	get_mimetype_from_fourcc (char **mimetype, unsigned int fourcc)
	Converts a FourCC code into a MIME type string.

static CHandle	create_handle (Device *device)
	Creates a new device handle for the given device. More...

static void	close_handle (CHandle hDevice)
	Closes the given handle.

static void	set_last_error (CHandle hDevice, int error)
	Sets the last system error for the given handle.

CHandle	c_open_device (const char *device_name)
	Opens a camera device. More...

void	c_close_device (CHandle hDevice)
	Closes a device handle. More...

CResult	c_enum_devices (CDevice devices, unsigned int size, unsigned int *count)
	Enumerates all devices available in the system. More...

CResult	c_get_device_info (CHandle hDevice, const char device_name, CDevice info, unsigned int *size)
	Returns information about a given camera device. More...

CResult	c_enum_pixel_formats (CHandle hDevice, CPixelFormat formats, unsigned int size, unsigned int *count)
	Enumerates all pixel formats supported by the given camera. More...

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. More...

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. More...

CResult	c_enum_controls (CHandle hDevice, CControl controls, unsigned int size, unsigned int *count)
	Enumerates all controls supported by the given device. More...

CResult	c_set_control (CHandle hDevice, CControlId control_id, const CControlValue *value)
	Sets the value of a device control. More...

CResult	c_get_control (CHandle hDevice, CControlId control_id, CControlValue *value)
	Returns the value of a device control. More...

CResult	c_enum_events (CHandle hDevice, CEvent events, unsigned int size, unsigned int *count)
	Enumerates the events supported by the given device. More...

CResult	c_subscribe_event (CHandle hDevice, CEventId event_id, CEventHandler handler, void *context)
	Subscribes the caller to receive the given event. More...

CResult	c_unsubscribe_event (CHandle hDevice, CEventId event_id)
	Unsubscribes the caller from the given event. More...

char *	c_get_error_text (CResult error)
	Returns the error message associated with a given error code. More...

char *	c_get_handle_error_text (CHandle hDevice, CResult error)
	Returns the error message associated with a given error code and device handle. More...

static CResult	create_control_choices (Control ctrl, struct v4l2_queryctrl v4l2_ctrl, int v4l2_dev)
	Queries the control choice values of the given V4L2 control and uses the results to fill in the choice structures of a libwebcam control. More...

static Control *	create_v4l2_control (Device device, struct v4l2_queryctrl v4l2_ctrl, int v4l2_dev, CResult *pret)
	Create a libwebcam control from a V4L2 control. More...

static void	delete_control (Control *ctrl)
	Frees all resources associated with the given control, including choice data. More...

static void	clear_control_list (Device *dev)
	Clears the control list of the given device and frees all associated resources.

static CResult	refresh_control_list (Device *dev)
	Scans the given device for supported controls and adds them to the internal list. More...

static CResult	refresh_device_details (Device *dev)
	Retrieve device information for the given device.

static Device *	create_device (char *name)
	Allocate a new device with the given name and add it to the global device list.

static void	delete_device (Device *dev)
	Free up the given device. More...

static void	invalidate_device_list (void)
	Mark all entries in the device list as invalid. More...

static void	cleanup_device_list (void)
	Remove all entries marked as invalid from the device list. More...

CResult	c_init (void)
	Initializes libwebcam. More...

void	c_cleanup (void)
	Clean up resources. More...

static void	__attribute__ ((constructor))
	Make sure the library resources are cleaned up when the library is unloaded.

Variables
int	initialized = 0
	A flag indicating whether the library was initialized.

static DeviceList	device_list
	A list of webcam devices found in the system.

HandleList	handle_list
	The fixed size list of file handles.

Detailed Description

Webcam library implementation.

Function Documentation

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(), _DeviceList::mutex, _HandleList::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, _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_libwebcam_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_libwebcam_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.

static void cleanup_device_list ( void )

static

Remove all entries marked as invalid from the device list.

Note: The device list should be locked before calling this function.

References _DeviceList::count, delete_device(), _DeviceList::first, _Device::next, and _Device::valid.

Referenced by c_cleanup(), and refresh_device_list().

static CResult create_control_choices	(	Control *	ctrl,
		struct v4l2_queryctrl *	v4l2_ctrl,
		int	v4l2_dev
	)

static

Queries the control choice values of the given V4L2 control and uses the results to fill in the choice structures of a libwebcam control.

Parameters

ctrl	Internal control for which the choice data is requested.
v4l2_ctrl	Pointer to a structure obtained from VIDIOC_QUERYCTRL and containing the V4L2 control data.
v4l2_dev	Open V4L2 device handle.

References C_NO_MEMORY, C_NOT_IMPLEMENTED, C_SUCCESS, C_V4L2_ERROR, _Control::control, print_libwebcam_error(), and V4L2_MENU_CTRL_MAX_NAME_SIZE.

Referenced by create_v4l2_control().

static CHandle create_handle ( Device * device )

static

Creates a new device handle for the given device.

Returns

0 if there are no free handles left.
A libwebcam handle > 0 on success.

References C_SYNC_ERROR, _HandleList::first_free, GET_HANDLE, HANDLE_OPEN, _Device::handles, lock_mutex(), MAX_HANDLES, _HandleList::mutex, print_libwebcam_error(), unlock_mutex(), and _Device::v4l2_name.

Referenced by c_open_device().

static Control* create_v4l2_control	(	Device *	device,
		struct v4l2_queryctrl *	v4l2_ctrl,
		int	v4l2_dev,
		CResult *	pret
	)

static

Create a libwebcam control from a V4L2 control.

If necessary, further information is requested by this function, e.g. in the case of a choice control.

Parameters

device	Device to which the control should be appended.
v4l2_ctrl	Pointer to a structure obtained from VIDIOC_QUERYCTRL and containing the V4L2 control data.
v4l2_dev	Open V4L2 device handle.
pret	Pointer to receive the error code in the case of an error. (Can be NULL.)

Returns

NULL if an error occurred. The associated error can be found in pret.
Pointer to the newly created control.

References C_NO_MEMORY, C_NOT_IMPLEMENTED, C_PARSE_ERROR, C_SUCCESS, CC_CAN_READ, CC_CAN_WRITE, CC_TYPE_BOOLEAN, CC_TYPE_CHOICE, CC_TYPE_DWORD, CC_TYPE_RAW, _Control::control, _Device::controls, _ControlList::count, create_control_choices(), _CControl::def, _ControlList::first, _CControl::flags, get_control_id_from_v4l2(), _CControl::id, _CControl::max, _CControl::min, _CControl::name, _Control::next, print_libwebcam_error(), _CControlValue::raw, _CControlRawValue::size, _CControl::step, _CControl::type, UNKNOWN_CONTROL_NAME, _Control::v4l2_control, _CControlValue::value, and _CControl::value.

Referenced by refresh_control_list().

static void delete_control ( Control * ctrl )

static

Frees all resources associated with the given control, including choice data.

Note that this functino does not remove the control from its device's control list.

References CC_TYPE_CHOICE, _Control::control, _CControl::name, and _CControl::type.

Referenced by clear_control_list().

static void delete_device ( Device * dev )

static

Free up the given device.

Note that this function does not remove the device from the global device list.

References clear_control_list(), _Device::device, _CDevice::driver, GET_HANDLE, HANDLE_OPEN, _Device::handles, _CDevice::location, lock_mutex(), MAX_HANDLES, _HandleList::mutex, _CDevice::name, _CDevice::shortName, unlock_mutex(), and _Device::v4l2_name.

Referenced by cleanup_device_list().

static Control * find_control_by_id	(	Device *	dev,
		CControlId	id
	)

static

Looks up the control with the given ID for the given device.

Returns

NULL if no corresponding control was found for the given device.
Pointer to the control if it was found.

References _Control::control, _Device::controls, _ControlList::first, _CControl::id, and _Control::next.

Referenced by c_get_control(), and c_set_control().

static unsigned int get_control_dynamics_length	(	Device *	device,
		unsigned int *	names_length,
		unsigned int *	choices_length
	)

static

Returns the length required to store all the (null-terminated) names of the given device's controls in a buffer.

Note: The control list should be locked before calling this function.

References CC_TYPE_CHOICE, _Control::control, _Device::controls, _ControlList::first, _CControl::name, _Control::next, and _CControl::type.

Referenced by c_enum_controls().

static CControlId get_control_id_from_v4l2	(	int	v4l2_id,
		Device *	dev
	)

static

Converts a V4L2 control ID to a libwebcam control ID.

Parameters

v4l2_id	V4L2 ID that should be converted.
dev	Pointer to the device to which the control belongs.

References CC_AUTO_EXPOSURE_MODE, CC_AUTO_EXPOSURE_PRIORITY, CC_AUTO_FOCUS, CC_AUTO_HUE, CC_AUTO_WHITE_BALANCE_TEMPERATURE, CC_BACKLIGHT_COMPENSATION, CC_BRIGHTNESS, CC_CONTRAST, CC_EXPOSURE_TIME_ABSOLUTE, CC_FOCUS_ABSOLUTE, CC_FOCUS_RELATIVE, CC_GAIN, CC_GAMMA, CC_HUE, CC_LOGITECH_PANTILT_RELATIVE, CC_LOGITECH_PANTILT_RESET, CC_PAN_ABSOLUTE, CC_PAN_RELATIVE, CC_PAN_RESET, CC_POWER_LINE_FREQUENCY, CC_PRIVACY, CC_SATURATION, CC_SHARPNESS, CC_TILT_ABSOLUTE, CC_TILT_RELATIVE, CC_TILT_RESET, CC_V4L2_BASE, CC_V4L2_CAMERA_CLASS_BASE, CC_V4L2_CUSTOM_BASE, CC_V4L2_MPEG_BASE, CC_WHITE_BALANCE_TEMPERATURE, CC_ZOOM_ABSOLUTE, CC_ZOOM_RELATIVE, _Device::device, _CDevice::driver, and print_libwebcam_error().

Referenced by create_v4l2_control().

static int get_devices_dynamics_length ( void )

static

Returns the length required to store all the (null-terminated) strings of the current devices in a buffer.

Note: The device list should be locked before calling this function.

References _Device::device, _DeviceList::first, get_device_dynamics_length(), and _Device::next.

Referenced by c_enum_devices().

static void invalidate_device_list ( void )

static

Mark all entries in the device list as invalid.

This allows the cleanup_device_list() function to be used to clear the entire device list.

Note: The device list should be locked before calling this function.

References _DeviceList::first, _Device::next, and _Device::valid.

Referenced by c_cleanup(), and refresh_device_list().

int open_v4l2_device ( char * device_name )

Open the V4L2 device node with the given name.

Parameters

device_name A device name as accepted by c_open_device()

Returns

0 if the device could not be opened
a device handle > 0 on success

References C_INVALID_ARG.

Referenced by add_control_mappings(), c_enum_frame_intervals(), c_enum_frame_sizes(), c_enum_pixel_formats(), read_v4l2_control(), refresh_control_list(), refresh_device_details(), and write_v4l2_control().

static void print_libwebcam_c_error	(	CResult	error,
		char *	format,
			...
	)

static

Prints a libwebcam error message to stderr.

Parameters

error	a CResult error code whose error text is appended
format	a printf compatible format

References c_get_error_text().

Referenced by refresh_device_list().

static CResult refresh_control_list ( Device * dev )

static

Scans the given device for supported controls and adds them to the internal list.

Note that this function clears all existing controls prior to reenumerating them.

References C_INVALID_DEVICE, C_NOT_IMPLEMENTED, C_PARSE_ERROR, C_SUCCESS, C_SYNC_ERROR, clear_control_list(), CONTROL_IO_ERROR_RETRIES, _Device::controls, create_v4l2_control(), _Device::device, _CDevice::driver, lock_mutex(), _ControlList::mutex, open_v4l2_device(), print_libwebcam_error(), unlock_mutex(), and _Device::v4l2_name.

Referenced by refresh_device_list().

Functions

Variables

Detailed Description

Function Documentation