The Application Interface (API)

The Application Interface and corresponding library is intended to perform several functions:

1. Allow the application to locate an appropriate codec for handling a given data format in a given way.
2. Allow the application to open and interact with the codec with a minimum of overhead, and without needing to know details of the codec's own implementation, or even of the UCI codec interface.
3. Support the easy management and handling of arbitrary codec parameters.
4. Transparently perform some common data conversions to allow various applications to interact with various codecs easily (for example, if a codec only supports YUV, but the application only works with RGB, the library will be able to convert between the two transparently so that the application can use the codec without thinking too hard about it (obviously, however, native formats are still preferable, such conversion will only be used as a fallback if the application/codec requires it)).
5. Support the use of user-level and system-level configuration files to augment default behavior for individual applications, individual codecs, or the entire system.

[this section is pretty much entirely unwritten.. here's a quick list of at least some of the functions/macros which are involved]

Library Setup, Configuration, and Miscellany

int uci_init(const char *appname, int flags)

This function must be called before any other UCI library functions are used. The parameters are as follows:

appname

This is a string indicating the "application name" for the program using the library. This can be anything, but it is reccomended that it be a short, descriptive, ASCII string identifying the current program or suite. If the current program is part of a group of interrelated applications, it is reccomended that one name be used for all of the applications in the suite. Users can use this name in UCI configuration files to identify configuration directives that should apply only to this program or group of programs.

flags

Flags for library initialization. Currently supported flag bits are:

UCI_INITFLAG_SKIPCONFIG

Skip reading and interpretation of the usual set of UCI configuration files. This should only be used if the application has some reason to want to change the files (or order of files, or etc) which are used to configure the UCI library.

This function returns UCI_STATUS_OK on success, or an error code on failure.

int uci_end(void)

This should always be called at the end of all UCI processing to clean up any resources which have been allocated by the UCI library. This should always be called even if the application will be terminating shortly afterward, as some resources may be allocated outside of the current program scope (temporary files in the filesystem, etc) which may still require cleanup.

const char *uci_strerror(int error)

Return a human-readable error string for the given error code (similar in function to strerror() for UCI-related errors)

NOTE: This function can be called without previous successful library initialization.

[To be documented:]

  uci_default_configfiles
  uci_parse_configfile
  uci_parse_configline
  uci_scan_codecs

(By default the library will automatically read and parse a standard set of config files upon library initialization, and will search for codecs in standard locations and locations specified by those config files. The uci_parse_config* and uci_scan_codecs functions are just in case an application has a need to override or extend that behavior)

Locating an Appropriate Codec and Format

[To be documented:]

  uci_avail_formats
  uci_find_format
  uci_find_fourcc
  uci_find_guid
  uci_find_mcf_id
  uci_find_acm_id

Managing Codec Parameters

uci_paramset *uci_new_paramset(uci_codechandle ch, const char *format, int type)

Obtain a new uci_paramset structure for the given codec instance. format is a string describing the format to be used. type must be one of:

UCI_PARAMSET_ENCODE_INIT

parameter set suitable for passing to uci_encode_init

UCI_PARAMSET_ENCODE

parameter set suitable for passing as an encoding function's parameters

UCI_PARAMSET_ENCODE_RESULTS

parameter set suitable for retrieving an encoding function's results

UCI_PARAMSET_DECODE_INIT

parameter set suitable for passing to uci_decode_init

UCI_PARAMSET_DECODE

parameter set suitable for passing as a decoding function's parameters

UCI_PARAMSET_DECODE_RESULTS

parameter set suitable for retrieving a decoding function's results

void uci_free_paramset(uci_params *p)

Free a paramset structure allocated by uci_new_paramset.

[To be documented:]

  uci_get_param_type
  uci_get_param_description
  uci_get_param_max
  uci_get_param_min
  uci_get_param_enumdata
  uci_get_param
  uci_get_paramptr

  uci_apply_paramstring

  UCI_P_<TYPE>
  uci_get_param_<type>
  uci_set_param_<type>
  uci_get_paramptr_<type>
  uci_get_param_max_<type>
  uci_get_param_min_<type>

Opening and Using Codecs

int uci_open_codec(uci_codechandle *ch, int type, const char *name)

Open the given codec. On success, *ch will contain a valid uci_codechandle, and UCI_STATUS_OK is returned. On failure, an error code will be returned.

ch

A pointer to a uci_codechandle variable. On successful completion, the memory location pointed to by this pointer will be set to a valid uci_codechandle to be passed to other UCI functions.

type

The type of codec being used. Currently supported types are UCI_CODECTYPE_AUDIO or UCI_CODECTYPE_VIDEO.

name

A string indicating the name of the codec to open. Valid codec names can be obtained by calling uci_avail_formats or uci_find_*.

int uci_close_codec(uci_codechandle ch)

Close a codec opened by uci_open_codec. Returns UCI_STATUS_OK on success or an error code on failure.

int uci_raw_encode_formats(uci_codechandle ch, const char *format, uci_paramset *iparams)

int uci_raw_decode_formats(uci_codechandle ch, const char *format, uci_paramset *iparams)

[To be documented:]

  uci_encode_init
  uci_encode_end
  uci_decode_init
  uci_decode_end