Webcam Library Reference Documentation  Logitech logo

Libs/libwebcam/dynctrl.c File Reference

Detailed Description

Dynamic control support for the Linux UVC driver.

#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <limits.h>
#include <ctype.h>
#include <unistd.h>
#include <stdarg.h>
#include <sys/ioctl.h>
#include <linux/videodev.h>
#include <errno.h>
#include <iconv.h>
#include "webcam.h"
#include "libwebcam.h"
#include "uvcvideo.h"
#include <libxml/parser.h>
#include <libxml/tree.h>

Data Structures

struct  _Constant
 Constant read from the XML configuration file. More...
struct  _UVCXUControl
 UVC extension unit control for use with UVCIOC_CTRL_ADD. More...
struct  _ParseContext
 Helper structure that contains handles and information useful during the XML parsing process. More...

Defines

#define GUID_SIZE   16
 Size of a GUID in bytes.
#define GUID_FORMAT   "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x"
 Format string to print a GUID byte array with printf.
#define GUID_ARGS(guid)
 Argument macro to print a GUID byte array with printf.
#define HEX_DECODE_CHAR(c)   ((c) >= '0' && (c) <= '9' ? (c) - '0' : (tolower(c)) - 'a' + 0xA)
 Convert a single hex character into its numeric value.
#define HEX_DECODE_BYTE(cc)   ((HEX_DECODE_CHAR((cc)[0]) << 4) + HEX_DECODE_CHAR((cc)[1]))
 Convert two hex characters into their byte value.
#define UNICODE_TO_ASCII(s)   (unicode_to_ascii(s, ctx))
 Helper macro to convert the UTF-8 strings used by libxml2 into ASCII.
#define UNICODE_TO_NORM_ASCII(s)   (unicode_to_normalized_ascii(s, ctx))
 Helper macro to convert the UTF-8 strings used by libxml2 into whitespace normalized ASCII.

Typedefs

typedef enum _ConstantType ConstantType
 Type of constants that are allowed in the XML configuration file.
typedef _Constant Constant
 Constant read from the XML configuration file.
typedef _UVCXUControl UVCXUControl
 UVC extension unit control for use with UVCIOC_CTRL_ADD.
typedef _ParseContext ParseContext
 Helper structure that contains handles and information useful during the XML parsing process.

Enumerations

enum  _ConstantType { CT_INVALID = 0, CT_INTEGER, CT_GUID }
 Type of constants that are allowed in the XML configuration file. More...

Functions

static void guid_to_byte_array (const char *guid, __u8 *array)
 Converts a GUID string into a GUID byte array.
static int is_valid_integer_string (const char *string, int *value)
 Checks whether a given string contains a valid integer value.
static int is_valid_size (int value, int max)
 Checks whether a given value represents a valid size.
static int is_valid_size_string (const char *string, int *value, int max)
 Checks whether a given string represents a valid size.
static int is_valid_guid (const char *string)
 Checks whether a given string represents a valid GUID.
static int string_to_version (const char *string, unsigned int *major, unsigned int *minor)
 Converts a string to a version consisting of major and minor version.
static __u32 get_uvc_request_by_name (const xmlChar *name)
 Converts the name of a UVC request into its corresponding constant.
static enum uvc_control_data_type get_uvc_ctrl_type_by_name (const xmlChar *name)
 Converts the name of a UVC data type constant into its corresponding numerical value.
static enum v4l2_ctrl_type get_v4l2_ctrl_type_by_name (const xmlChar *name)
 Converts the name of a V4L2 data type constant into its corresponding numerical value.
static char * normalize_string (const char *input)
 Normalizes a string in terms of whitespace.
static char * unicode_to_ascii (const xmlChar *unicode, ParseContext *ctx)
 Converts a UTF-8 string to ASCII.
static char * unicode_to_normalized_ascii (const xmlChar *unicode, ParseContext *ctx)
 Converts a UTF-8 string to ASCII and then normalizes the string's whitespace.
static const xmlChar * xml_get_node_text (const xmlNode *node)
 Returns the text content of the given node.
static xmlNode * xml_get_first_child_by_name (const xmlNode *node, const char *name)
 Returns the first child node with a given name.
static xmlNode * xml_get_next_sibling_by_name (const xmlNode *node, const char *name)
 Returns the next sibling node with a given name.
static Constant * lookup_constant (const char *find_name, ConstantType find_type, ParseContext *ctx)
 Look up a constant by its name.
static CResult lookup_or_convert_to_integer (const xmlChar *text, int *value, ParseContext *ctx)
 Convert the given string to an integer or look up a constant with the given name.
static CResult lookup_or_convert_to_guid (const xmlChar *text, __u8 *guid, ParseContext *ctx)
 Convert the given string to a GUID or look up a constant with the given name.
static UVCXUControl * lookup_control (const xmlChar *name, ParseContext *ctx)
 Lookup a UVC extension unit control with the given name.
static CResult resize_message_buffer (ParseContext *ctx, CDynctrlMessage *msg)
 Reorganize the buffer that is used to store the messages that are logged during parsing.
static CResult add_message_v (ParseContext *ctx, int line, int col, CDynctrlMessageSeverity severity, const char *format, va_list va)
 Adds a new message to the message list.
static CResult add_message (ParseContext *ctx, int line, int col, CDynctrlMessageSeverity severity, const char *format,...)
 Adds a new message to the message list.
static CResult add_info (ParseContext *ctx, const char *format,...)
 Adds a new informational message to the message list.
static CResult add_error (ParseContext *ctx, const char *format,...)
 Adds a new error message to the message list.
static CResult add_error_at_node (ParseContext *ctx, const xmlNode *node, const char *format,...)
 Adds a new error message concerning a given xmlNode to the message list.
static CResult parse_dynctrl_file (const char *file_name, xmlDoc **xml_doc, ParseContext *ctx)
 Parse a dynamic controls configuration XML file and return an XML document tree.
static CResult process_mapping (const xmlNode *node_mapping, ParseContext *ctx)
 Process a mapping node and add the contained mapping to the UVC driver.
static CResult process_mappings (const xmlNode *node_mappings, ParseContext *ctx)
 Process a mappings node.
static CResult process_control (xmlNode *node_control, ParseContext *ctx)
 Process a control node by adding the contained control to the UVC driver.
static CResult process_controls (const xmlNode *node_controls, ParseContext *ctx)
 Process a controls node.
static CResult process_device (const xmlNode *node_device, ParseContext *ctx)
 Process a device node.
static CResult process_devices (const xmlNode *node_devices, ParseContext *ctx)
 Process a devices node.
static CResult process_constant (xmlNode *node_constant, ParseContext *ctx)
 Process a constant node by adding the contained constant to an internal list.
static CResult process_constants (const xmlNode *node_constants, ParseContext *ctx)
 Process a constants node.
static CResult process_meta (const xmlNode *node_meta, ParseContext *ctx)
 Process a meta node by filling in the corresponding info structure.
static CResult process_dynctrl_doc (xmlDoc *xml_doc, ParseContext *ctx)
 Process an XML document tree representing a dynamic controls configuration file.
static CResult device_supports_dynctrl (ParseContext *ctx)
 Checks whether the driver behind the current device supports dynamic controls.
static CResult add_control_mappings (xmlDoc *xml_doc, ParseContext *ctx)
 Adds controls and control mappings contained in the given XML tree to the UVC driver.
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.

Define Documentation

#define GUID_ARGS (  guid   ) 
 

Value:

(guid)[3],  (guid)[2],  (guid)[1],  (guid)[0], \
        (guid)[5],  (guid)[4], \
        (guid)[7],  (guid)[6], \
        (guid)[8],  (guid)[9], \
        (guid)[10], (guid)[11], (guid)[12], \
        (guid)[13], (guid)[14], (guid)[15]
Argument macro to print a GUID byte array with printf.

Enumeration Type Documentation

enum _ConstantType
 

Type of constants that are allowed in the XML configuration file.

Enumerator:
CT_INVALID  Invalid type (used internally).
CT_INTEGER  Signed integer constant.
CT_GUID  GUID.

Function Documentation

static CResult add_control_mappings (  xmlDoc *  xml_doc,
ParseContext *  ctx
)  [static]
 

Adds controls and control mappings contained in the given XML tree to the UVC driver.

Parameters:
xml_doc XML document tree corresponding to the dynctrl format
ctx current parse context
Returns:

static CResult add_error_at_node (  ParseContext *  ctx,
const xmlNode *  node,
const char *  format,
  ...
)  [static]
 

Adds a new error message concerning a given xmlNode to the message list.

The node is used to extract the line number.

static CResult add_message (  ParseContext *  ctx,
int  line,
int  col,
CDynctrlMessageSeverity  severity,
const char *  format,
  ...
)  [static]
 

Adds a new message to the message list.

Parameters:
ctx current parse context
line line number that the message concerns (e.g. line of the syntax error)
col column number that the message concerns
severity severity level of the message (warning, error, etc.)
format a printf compatible format to print the variable parameter list

static CResult add_message_v (  ParseContext *  ctx,
int  line,
int  col,
CDynctrlMessageSeverity  severity,
const char *  format,
va_list  va
)  [static]
 

Adds a new message to the message list.

This function works like add_message() but takes a va_list argument instead of a parameter list.

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:

static CResult device_supports_dynctrl (  ParseContext *  ctx  )  [static]
 

Checks whether the driver behind the current device supports dynamic controls.

The check is done by redefining the brightness control which is hardcoded in the UVC driver. If the driver supports dynamic controls, it will return EEXIST. If the driver does not support dynamic controls, the ioctl will fail with EINVAL.

Parameters:
ctx current parse context
Returns:

static enum uvc_control_data_type get_uvc_ctrl_type_by_name (  const xmlChar *  name  )  [static]
 

Converts the name of a UVC data type constant into its corresponding numerical value.

Parameters:
name data type string to be converted. Can be NULL.
Returns:
  • -1 if the conversion failed, i.e. the data type name was not recognized
  • a UVC_CTRL_DATA_TYPE_* constant if the conversion was successful

static __u32 get_uvc_request_by_name (  const xmlChar *  name  )  [static]
 

Converts the name of a UVC request into its corresponding constant.

Parameters:
name request string to be converted. Can be NULL.
Returns:
  • 0 if the conversion failed, i.e. the request name was not recognized
  • a UVC_CONTROL_* constant if the conversion was successful

static enum v4l2_ctrl_type get_v4l2_ctrl_type_by_name (  const xmlChar *  name  )  [static]
 

Converts the name of a V4L2 data type constant into its corresponding numerical value.

Note that not all V4L2 data types are recognized. Only the ones relevant for libwebcam and allowed by the schema are considered valid.

Parameters:
name data type string to be converted. Can be NULL.
Returns:
  • 0 if the conversion failed, i.e. the data type name was not recognized
  • a V4L2_CTRL_TYPE_* constant if the conversion was successful

static void guid_to_byte_array (  const char *  guid,
__u8 *  array
)  [static]
 

Converts a GUID string into a GUID byte array.

This function assumes that guid is a valid GUID string. No validation is performed.

static int is_valid_integer_string (  const char *  string,
int *  value
)  [static]
 

Checks whether a given string contains a valid integer value.

This function considers all integers recognized by strtol() as valid. This includes hexadecimal numbers with a '0x' prefix and octal numbers with a leading zero.

Parameters:
string String containing an integer. Can be NULL.
value A pointer in which the converted value will be stored. Can be NULL if conversion is not required.
Returns:
boolean indicating whether the string represents a valid integer

static int is_valid_size (  int  value,
int  max
)  [inline, static]
 

Checks whether a given value represents a valid size.

Only positive numbers are considered valid size values. In addition, an upper threshold can be specified, above which values will be considered invalid.

Parameters:
value value to be checked
max upper threshold for the validity of value. If the threshold is negative, no threshold check is performed, i.e. max == INT_MAX is assumed.
Returns:
boolean indicating whether the value is a valid size

static int is_valid_size_string (  const char *  string,
int *  value,
int  max
)  [static]
 

Checks whether a given string represents a valid size.

This function works just like is_valid_size() but accepts an input string and a buffer to store the converted value.

static Constant* lookup_constant (  const char *  find_name,
ConstantType  find_type,
ParseContext *  ctx
)  [static]
 

Look up a constant by its name.

Parameters:
ctx current parse context
find_name name of the constant to look up
find_type only search for constants with this type. Specify CT_INVALID to disable the type filter.
Returns:
  • NULL if no constant with the given name (and given type) could be found
  • a pointer to the constant if the search was successful

static CResult lookup_or_convert_to_guid (  const xmlChar *  text,
__u8 *  guid,
ParseContext *  ctx
)  [static]
 

Convert the given string to a GUID or look up a constant with the given name.

This function works like lookup_or_convert_to_integer() except that it looks for GUIDs instead of integers.

static CResult lookup_or_convert_to_integer (  const xmlChar *  text,
int *  value,
ParseContext *  ctx
)  [static]
 

Convert the given string to an integer or look up a constant with the given name.

The function first tries to convert the given string to an integer. If successful, the converted value is returned. If the conversion fails, the string is interpreted as a name and a constant with that name is looked up. If the lookup is successful, the value of the constant is returned.

Parameters:
text pointer to the name or integer value. Can be NULL.
value pointer to an integer to receive the converted or constant value
ctx current parse context
Returns:
  • C_SUCCESS if the string was successfully converted to an integer
  • C_SUCCESS if the string was not converted but a constant was found
  • C_PARSE_ERROR if text is NULL, or if both conversion and lookup fail

static char* normalize_string (  const char *  input  )  [static]
 

Normalizes a string in terms of whitespace.

The function returns a copy of the input string with leading and trailing whitespace removed and all internal whitespace reduced to simple spaces. Examples: " text " => "text" " Multi\nline text" => "Multi line text"

This function allocates a new buffer that needs to be freed by the caller.

Parameters:
input input string to be normalized. This string is not modified.
Returns:
  • NULL if input is NULL or if memory could not be allocated
  • a newly allocated buffer containing the output string

static CResult parse_dynctrl_file (  const char *  file_name,
xmlDoc **  xml_doc,
ParseContext *  ctx
)  [static]
 

Parse a dynamic controls configuration XML file and return an XML document tree.

Note that the pointer stored in *xml_doc must be freed using xmlFreeDoc() if the return value of this functino is C_SUCCESS.

Parameters:
file_name name (with an optional path) of the file to be parsed
xml_doc address of a pointer to store the XML document tree
ctx current parse context
Returns:
  • C_NO_MEMORY if a buffer or structure could not be allocated
  • C_PARSE_ERROR if the XML file is malformed
  • C_SUCCESS if parsing was successful

static CResult process_device (  const xmlNode *  node_device,
ParseContext *  ctx
)  [static]
 

Process a device node.

Note that the contained match sections are currently ignored.

static CResult resize_message_buffer (  ParseContext *  ctx,
CDynctrlMessage *  msg
)  [static]
 

Reorganize the buffer that is used to store the messages that are logged during parsing.

The buffer that is used to store the messages is completely self-contained. It consists of an array of CDynctrlMessage structures and an area for "dynamics" which stores dynamic data like strings. All string pointers in the array point to strings in the dynamics area, so for clean up only a single buffer needs to be freed.

Every time a new array element is added, the buffer has to be enlarged, and a new array element has to be inserted between the current last element and the dynamics area. The dynamics area is moved by sizeof(CDynctrlMessage) bytes and all pointers to it are updated to point to the new direction.

Parameters:
ctx current parse context
msg pointer to the new message to be added. Note that this is only a temporary buffer. Its content (including its strings) is copied into the message buffer and the temporary buffer is no longer required after the function returns.
Returns:
  • C_NO_MEMORY if the buffer could not be enlarged for lack of memory
  • C_SUCCESS otherwise

static int string_to_version (  const char *  string,
unsigned int *  major,
unsigned int *  minor
)  [static]
 

Converts a string to a version consisting of major and minor version.

Accepted formats are "x.y" and "x" where x is the major and y the minor version.

Parameters:
string version string to be converted
major pointer to an integer where the major version number should be stored
minor pointer to an integer where the minor version number should be stored
Returns:
boolean indicating whether the conversion succeeded or not

static char* unicode_to_ascii (  const xmlChar *  unicode,
ParseContext *  ctx
)  [static]
 

Converts a UTF-8 string to ASCII.

The function may convert some characters in a non-reversible way.

Parameters:
unicode input string to be converted.
ctx current parse context
Returns:
  • NULL if the input buffer is NULL or an error occurs
  • a copy of the input string if there is no iconv conversion descriptor
  • a newly allocated buffer containing only ASCII characters

static char* unicode_to_normalized_ascii (  const xmlChar *  unicode,
ParseContext *  ctx
)  [static]
 

Converts a UTF-8 string to ASCII and then normalizes the string's whitespace.

This function is effectively a combination of unicode_to_ascii() and normalize_string(). Note that the caller must free the returned string.

static xmlNode* xml_get_first_child_by_name (  const xmlNode *  node,
const char *  name
)  [static]
 

Returns the first child node with a given name.

Parameters:
node pointer to the parent node whose children are to be searched
name the name of the child node to be searched for
Returns:
  • a pointer to the first child node with the given name
  • NULL if no child node has the given name

static xmlNode* xml_get_next_sibling_by_name (  const xmlNode *  node,
const char *  name
)  [static]
 

Returns the next sibling node with a given name.

Parameters:
node pointer to the node whose siblings are to be searched
name the name of the sibling node to be searched for
Returns:
  • a pointer to the first sibling node with the given name
  • NULL if no sibling node has the given name

static const xmlChar* xml_get_node_text (  const xmlNode *  node  )  [static]
 

Returns the text content of the given node.

Parameters:
node Pointer to a node. May be NULL.
Returns:
  • the content of the first text child node if it exists
  • NULL if a node in the path does not exist or does not contain text

Generated on Tue Nov 8 08:41:15 2011 for Webcam Library by Doxygen 1.4.6
Copyright © 2006-2008 Logitech.