Webcam Library Reference Documentation

Libs/libwebcam/libwebcam.c File Reference

---

Detailed Description

Webcam library implementation.

#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>

Defines
#define	V4L2_CTRL_TYPE_INTEGER64   5
Functions
static void	print_error (char *format,...)
	Prints a generic error message to stderr.
static void	print_c_error (CResult error, char *format,...)
	Prints a libwebcam error message to stderr.
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.
static Control *	find_control_by_id (Device *dev, CControlId id)
	Looks up the control with the given ID for the given device.
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.
int	open_v4l2_device (char *device_name)
	Open the V4L2 device node with the given name.
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.
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.
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.
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.
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.
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.
static Control *	create_control (Device *device, struct v4l2_queryctrl *v4l2_ctrl, int v4l2_dev, CResult *pret)
	Create a libwebcam control from a V4L2 control.
static void	delete_control (Control *ctrl)
	Frees all resources associated with the given control, including choice data.
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.
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.
static void	invalidate_device_list (void)
	Mark all entries in the device list as invalid.
static void	cleanup_device_list (void)
	Remove all entries marked as invalid from the device list.
CResult	c_init (void)
	Initializes libwebcam.
void	c_cleanup (void)
	Clean up resources.
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.

---

Function Documentation

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

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.

static Control* create_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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

static void print_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

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.

---