The Application Interface (API)

Note: Some information presented here may be slightly out of date, as the specifications and code underneath all this is still somewhat a moving target. If you find something here which doesn't look right, please do not be too alarmed, as it may just need updating.
Last Updated: Sept 23, 2002

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:

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 for library initialization. Currently supported flag bits are:
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:]


(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:]


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:

parameter set suitable for passing to uci_encode_init
parameter set suitable for passing as an encoding function's parameters
parameter set suitable for retrieving an encoding function's results
parameter set suitable for passing to uci_decode_init
parameter set suitable for passing as a decoding function's parameters
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:]




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.

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.
The type of codec being used. Currently supported types are UCI_CODECTYPE_AUDIO or UCI_CODECTYPE_VIDEO.
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:]