libcmml: cmml.h File Reference

# cmml.h File Reference

`#include <stdio.h>`
`#include <expat.h>`

Go to the source code of this file.

## Data Structures
struct | CMML_UTC
struct | CMML_Time
struct | _CMML_List
struct | CMML_Preamble
struct | CMML_ParamElement
struct | CMML_ImportElement
struct | CMML_Stream
struct | CMML_MetaElement
struct | CMML_LinkElement
struct | CMML_Head
struct | CMML_Clip
struct | CMML_Element
struct | CMML_Error
## Typedefs
typedef void | CMML
typedef enum _CMML_Time_Type | CMML_Time_Type
typedef struct _CMML_List | CMML_List
typedef void *(* | CMML_CloneFunc )(void *data)
typedef void *(* | CMML_FreeFunc )(void *data)
typedef int(* | CMML_CmpFunc )(void *cmp_ctx, void *s1, void *s2)
typedef enum _CMML_Element_Type | CMML_Element_Type
typedef enum _CMML_Error_Type | CMML_Error_Type
typedef int(* | CMMLReadStream )(CMML *cmml, const CMML_Stream *stream, void *user_data)
typedef int(* | CMMLReadHead )(CMML *cmml, const CMML_Head *head, void *user_data)
typedef int(* | CMMLReadClip )(CMML *cmml, const CMML_Clip *clip, void *user_data)
## Enumerations
enum | _CMML_Time_Type { CMML_SEC_TIME, CMML_UTC_TIME }
enum | _CMML_Element_Type { CMML_NONE, CMML_CMML, CMML_STREAM, CMML_IMPORT, CMML_HEAD, CMML_CLIP }
enum | _CMML_Error_Type { CMML_OK, CMML_EOF, CMML_READ_ERROR, CMML_TIME_ERROR, CMML_MALLOC_ERROR, CMML_EXPAT_ERROR, CMML_PARSE_ERROR, CMML_NO_CMML_TAG, CMML_NO_HEAD_TAG, CMML_STREAM_NOT_FIRST, CMML_HEAD_AFTER_CLIP, CMML_DUPLICATE_STREAM, CMML_DUPLICATE_HEAD, CMML_FORMAT_ERROR, CMML_UNKNOWN_TAG, CMML_TAG_IGNORED, CMML_XMLNS_REDEFINED, CMML_NONSEQUENTIAL_CLIP }
## Functions
CMML * | cmml_open (const char *XMLfilename)
CMML * | cmml_new (FILE *file)
FILE * | cmml_destroy (CMML *cmml)
CMML * | cmml_close (CMML *cmml)
int | cmml_set_read_callbacks (CMML *cmml, CMMLReadStream read_stream, CMMLReadHead read_head, CMMLReadClip read_clip, void *user_data)
long | cmml_read (CMML *cmml, long n)
void | cmml_set_sloppy (CMML *cmml, int value)
CMML_Preamble * | cmml_get_preamble (CMML *cmml)
CMML_Stream * | cmml_get_last_stream (CMML *cmml)
CMML_Head * | cmml_get_last_head (CMML *cmml)
CMML_Clip * | cmml_get_last_clip (CMML *cmml)
CMML_Clip * | cmml_get_previous_clip (CMML *cmml)
CMML_Error * | cmml_get_last_error (CMML *cmml)
void | cmml_error_clear (CMML *cmml)
int | cmml_set_window (CMML *cmml, CMML_Time *start, CMML_Time *end)
double | cmml_skip_to_secs (CMML *cmml, double seconds)
double | cmml_skip_to_utc (CMML *cmml, const char *utc)
double | cmml_skip_to_id (CMML *cmml, const char *id)
double | cmml_skip_to_offset (CMML *cmml, const char *offset)
CMML_Preamble * | cmml_preamble_new (const char *encoding, const char *id, const char *lang, const char *dir, const char *granulerate)
CMML_Element * | cmml_element_new (CMML_Element_Type type)
CMML_Stream * | cmml_stream_new (void)
CMML_Head * | cmml_head_new (void)
CMML_Clip * | cmml_clip_new (CMML_Time *start_time, CMML_Time *end_time)
CMML_Error * | cmml_error_new (CMML_Error_Type type)
CMML_Preamble * | cmml_preamble_clone (CMML_Preamble *src)
CMML_Element * | cmml_element_clone (CMML_Element *src)
CMML_Stream * | cmml_stream_clone (CMML_Stream *src)
CMML_Head * | cmml_head_clone (CMML_Head *src)
CMML_Clip * | cmml_clip_clone (CMML_Clip *src)
void | cmml_preamble_destroy (CMML_Preamble *preamble)
void | cmml_element_destroy (CMML_Element *element)
void | cmml_stream_destroy (CMML_Stream *stream)
void | cmml_head_destroy (CMML_Head *head)
void | cmml_clip_destroy (CMML_Clip *clip)
void | cmml_error_destroy (CMML_Error *error)
int | cmml_preamble_snprint (char *buf, int n, CMML_Preamble *pre)
int | cmml_element_snprint (char *buf, int n, CMML_Element *elem)
int | cmml_stream_snprint (char *buf, int n, CMML_Stream *stream)
int | cmml_stream_pretty_snprint (char *buf, int n, CMML_Stream *stream)
int | cmml_head_snprint (char *buf, int n, CMML_Head *head)
int | cmml_head_pretty_snprint (char *buf, int n, CMML_Head *head)
int | cmml_clip_snprint (char *buf, int n, CMML_Clip *clip)
int | cmml_clip_pretty_snprint (char *buf, int n, CMML_Clip *clip)
int | cmml_error_snprint (char *buf, int n, CMML_Error *error, CMML *cmml)
CMML_List * | cmml_list_new (void)
CMML_List * | cmml_list_clone (CMML_List *list)
CMML_List * | cmml_list_clone_with (CMML_List *list, CMML_CloneFunc clone)
CMML_List * | cmml_list_tail (CMML_List *list)
CMML_List * | cmml_list_prepend (CMML_List *list, void *data)
CMML_List * | cmml_list_append (CMML_List *list, void *data)
CMML_List * | cmml_list_add_before (CMML_List *list, void *data, CMML_List *node)
CMML_List * | cmml_list_add_after (CMML_List *list, void *data, CMML_List *node)
CMML_List * | cmml_list_find (CMML_List *list, void *data)
CMML_List * | cmml_list_remove (CMML_List *list, CMML_List *node)
int | cmml_list_length (CMML_List *list)
int | cmml_list_is_empty (CMML_List *list)
int | cmml_list_is_singleton (CMML_List *list)
CMML_List * | cmml_list_free_with (CMML_List *list, CMML_FreeFunc free_func)
CMML_List * | cmml_list_free (CMML_List *list)
CMML_Time * | cmml_time_new (const char *s)
CMML_Time * | cmml_sec_new (const char *s)
CMML_Time * | cmml_time_new_secs (double seconds)
CMML_Time * | cmml_utc_new (const char *s)
int | cmml_time_interval_new (const char *s, CMML_Time **t_start, CMML_Time **t_end)
CMML_Time * | cmml_time_new_in_sec (const char *s, CMML_Time *ref, double base)
CMML_Time * | cmml_time_utc_to_sec (CMML_Time *t, CMML_Time *ref, double base)
void | cmml_time_free (CMML_Time *t)
CMML_Time * | cmml_time_clone (CMML_Time *t)
double | cmml_sec_parse (const char *s)
CMML_UTC * | cmml_utc_parse (const char *s)
CMML_UTC * | cmml_utc_clone (CMML_UTC *t)
double | cmml_utc_diff (CMML_UTC *t2, CMML_UTC *t1)
int | cmml_npt_snprint (char *buf, int n, double seconds)
int | cmml_utc_snprint (char *buf, int n, CMML_UTC *t)
int | cmml_utc_pretty_snprint (char *buf, int n, CMML_UTC *t)

## Detailed Description

cmml.h includes definitions of the public API and data types required to parse CMML 2.0 files.

## Typedef Documentation

typedef void CMML

A CMML handle.

Examples:
  cmml-parse.c, cmml-seek-clip.c, cmml-seek-offset.c, cmml-seek-utc.c, cmml-uri-file.c, cmml-validate.c, and cmml.dtd.

typedef enum _CMML_Time_Type CMML_Time_Type

CMML_Time_Type: enumerates the different time types

typedef struct _CMML_List CMML_List

CMML_List: A doubly linked list

typedef void*(* CMML_CloneFunc)(void *data)

CMML_CloneFunc: Signature of a cloning function for CMML_List.

typedef void*(* CMML_FreeFunc)(void *data)

CMML_FreeFunc: Signature of a freeing function.

typedef int(* CMML_CmpFunc)(void *cmp_ctx, void *s1, void *s2)

CMML_CmpFunc: Signature of a comparison function for CMML_List to compares two scalars, returning: +ve, s1 > s2 0, s1 == s2 -ve, s1 < s2

typedef enum _CMML_Element_Type CMML_Element_Type

CMML_Element_Type: indication of what the CMML_Element actually represents.

typedef enum _CMML_Error_Type CMML_Error_Type

CMML_Error_Type: indication of the type of error that occured. There are three classes of errors:

- general processing feedback (CMML_OK, CMML_EOF)
- fatal processing feedback (these errors render the CMML file useless)
- tolerable processing errors (these lead to ignoring certain tags) The user may select to ignore sloppy errors

typedef int(* CMMLReadStream)(CMML *cmml, const CMML_Stream *stream, void *user_data)

CMMLReadStream: Signature for a callback called when the CMML stream element is parsed

Parameters:

  | cmml | the CMML* handle in use
  | stream | the stream element's content represented in a CMML_Stream*
  | user_data | user defined data

Returns:
  0 on success, 1 on error

typedef int(* CMMLReadHead)(CMML *cmml, const CMML_Head *head, void *user_data)

CMMLReadHead: Signature for a callback called when the CMML head element is parsed

Parameters:

  | cmml | the CMML* handle in use
  | head | the head element's content represented in a CMML_Head*
  | user_data | user defined data

Returns:
  0 on success, 1 on error

typedef int(* CMMLReadClip)(CMML *cmml, const CMML_Clip *clip, void *user_data)

CMMLReadClip: Signature for a callback called when a CMML clip element is parsed

Parameters:

  | cmml | the CMML* handle in use
  | clip | the clip element's content represented in a CMML_Clip*
  | user_data | user defined data

Returns:
  0 on success, 1 on error

## Enumeration Type Documentation

enum _CMML_Time_Type

CMML_Time_Type: enumerates the different time types

Enumerator:

  CMML_SEC_TIME | time is seconds
  CMML_UTC_TIME | time is utc

enum _CMML_Element_Type

CMML_Element_Type: indication of what the CMML_Element actually represents.

Enumerator:

  CMML_NONE | no element
  CMML_CMML | cmml element
  CMML_STREAM | stream element
  CMML_IMPORT | import element
  CMML_HEAD | head element
  CMML_CLIP | clip element

enum _CMML_Error_Type

CMML_Error_Type: indication of the type of error that occured. There are three classes of errors:

- general processing feedback (CMML_OK, CMML_EOF)
- fatal processing feedback (these errors render the CMML file useless)
- tolerable processing errors (these lead to ignoring certain tags) The user may select to ignore sloppy errors

Enumerator:

  CMML_OK | everything went fine and EOF was not encountered
  CMML_EOF | EOF, but everything went fine
  CMML_READ_ERROR | Reading the raw CMML doc into a buffer
  CMML_TIME_ERROR | Error in formatting of time in a required tag
  CMML_MALLOC_ERROR | Memory allocation error
  CMML_EXPAT_ERROR | Expat reported an error
  CMML_PARSE_ERROR | General parsing error
  CMML_NO_CMML_TAG | No cmml tag was found
  CMML_NO_HEAD_TAG | No head tag was found
  CMML_STREAM_NOT_FIRST | there is a head or a tag before the stream
  CMML_HEAD_AFTER_CLIP | there is a clip tag before the head tag
  CMML_DUPLICATE_STREAM | there are two stream tags
  CMML_DUPLICATE_HEAD | there are two head tags
  CMML_FORMAT_ERROR | error in the formatting of an implied attribute
  CMML_UNKNOWN_TAG | skipping an unknown tag
  CMML_TAG_IGNORED | skipping a faulty tag
  CMML_XMLNS_REDEFINED | xmlns in cmml tag is wrongly redefined
  CMML_NONSEQUENTIAL_CLIP | clip with start time in the "past" skipped

## Function Documentation

CMML* cmml_open | ( | const char * | XMLfilename | ) |

cmml_open: Takes a filename and opens it as read-only. Then checks whether it is an XML file satisfying the CMML specification with the xml directive and the cmml tag. It returns a CMML object. If you're working on an already opened FILE*, use cmml_new instead.

Parameters:

  | XMLfilename | a CMML file to open

Returns:
  a CMML* handle

Examples:
  cmml-seek-clip.c, cmml-seek-offset.c, cmml-seek-utc.c, cmml-uri-file.c, and cmml-validate.c.

Referenced by main().

CMML* cmml_new | ( | FILE * | file | ) |

cmml_attach_parser: Takes a FILE pointer to an already-opened CMML document. Returns a CMML object containing internal initialised data structures, etc, which is used in subsequent operations on the CMML file. This function must be called exactly once, after the file descriptor has been opened.

Parameters:

  | file | an open FILE pointer

Returns:
  a CMML* handle

Examples:
  cmml-parse.c, and cmml-validate.c.

Referenced by main().

FILE* cmml_destroy | ( | CMML * | cmml | ) |

cmml_detach_parser: Close a CMML object. Return the FILE pointer from which the CMML object was derived.

Parameters:

  | cmml | a CMML* handle

Returns:
  the open FILE pointer

Examples:
  cmml-parse.c.

CMML* cmml_close | ( | CMML * | cmml | ) |

cmml_close: Close a CMML object.

Parameters:

  | cmml | a CMML* handle

Returns:
  NULL on success or the unchanged CMML object (e.g. in case of a system error on close())

Examples:
  cmml-seek-clip.c, cmml-seek-offset.c, cmml-seek-utc.c, cmml-uri-file.c, and cmml-validate.c.

Referenced by main().

int cmml_set_read_callbacks | ( | CMML * | cmml,
|  | CMMLReadStream | read_stream,
|  | CMMLReadHead | read_head,
|  | CMMLReadClip | read_clip,
|  | void * | user_data |
| ) |  |  |

cmml_set_read_callbacks: registration function for callbacks.

Parameters:

  | cmml | a CMML* handle
  | read_stream | a CMMLReadStream callback function for the stream tag
  | read_head | a CMMLReadHead callback function for the head tag
  | read_clip | a CMMLReadClip callback function for the a tag
  | user_data | a pointer to a user defined object being passed to the callbacks

Returns:
  0 on success, -1 on failure

Examples:
  cmml-parse.c, cmml-seek-clip.c, cmml-seek-offset.c, cmml-seek-utc.c, cmml-uri-file.c, and cmml-validate.c.

Referenced by main().

long cmml_read | ( | CMML * | cmml,
|  | long | n |
| ) |  |  |

cmml_read: read n bytes from a file descriptor and parse them. Activates registered callbacks when reaching stream, head or clip end tags and blocks until they have completed. Stores parsed info in status. If an error or EOF occurs, returns -1 in which case you can check the error code with cmml_last_error().

Parameters:

  | cmml | a CMML* handle
  | n | number of bytes to read

Returns:
  the actual number of bytes read

Examples:
  cmml-parse.c, cmml-seek-clip.c, cmml-seek-offset.c, cmml-seek-utc.c, cmml-uri-file.c, and cmml-validate.c.

Referenced by main().

void cmml_set_sloppy | ( | CMML * | cmml,
|  | int | value |
| ) |  |  |

cmml_set_sloppy: Sets the parsing and error indication to ignore sloppy errors, which are defined below the CMML_FORMAT_ERROR in the CMML_ErrorType struct

Parameters:

  | cmml | a CMML* handle
  | value | a bool value to set the sloppy handling

Examples:
  cmml-validate.c.

Referenced by main().

CMML_Preamble* cmml_get_preamble | ( | CMML * | cmml | ) |

cmml_get_preamble: returns a structure containing some of the parsing informtion received out of a stream.

Parameters:

  | cmml | a CMML* handle

Returns:
  1 if CMML tag specificed, 0 otherwise

Examples:
  cmml-validate.c.

Referenced by main().

CMML_Stream* cmml_get_last_stream | ( | CMML * | cmml | ) |

cmml_get_last_stream: Return a copy of the current stream element.

Parameters:

  | cmml | a CMML* handle

Returns:
  a CMML_Stream* structure with the stream element details; NULL if none existed

CMML_Head* cmml_get_last_head | ( | CMML * | cmml | ) |

cmml_get_last_head: Return a copy of the current head element.

Parameters:

  | cmml | a CMML* handle

Returns:
  a CMML_Head* structure with the head element details; NULL if none existed

CMML_Clip* cmml_get_last_clip | ( | CMML * | cmml | ) |

cmml_get_last_clip: Return a copy of the current clip element.

Parameters:

  | cmml | a CMML* handle

Returns:
  a CMML_Clip* structure with the clip element details; NULL if none existed

CMML_Clip* cmml_get_previous_clip | ( | CMML * | cmml | ) |

cmml_get_previous_clip: Return a copy of the previous clip element.

Parameters:

  | cmml | a CMML* handle

Returns:
  a CMML_Clip* structure with the clip element details; NULL if none existed

CMML_Error* cmml_get_last_error | ( | CMML * | cmml | ) |

cmml_get_last_error: Return the error status of the most recently executed cmml command.

Parameters:

  | cmml | a CMML* handle

Returns:
  a CMML_Error* structure with the error details; NULL if none happened

Examples:
  cmml-validate.c.

Referenced by main(), read_clip(), read_head(), and read_stream().

void cmml_error_clear | ( | CMML * | cmml | ) |

cmml_error_clear: Clear the last error.

Parameters:

  | cmml | a CMML* handle

int cmml_set_window | ( | CMML * | cmml,
|  | CMML_Time * | start,
|  | CMML_Time * | end |
| ) |  |  |

cmml_set_window: sets the active temporal interval of a cmml stream; all clips outside that interval get ignored

Parameters:

  | cmml | a CMML* handle
  | start | the start time of the interval given as CMML_Time* structure
  | end | the end time of the interval given as CMML_Time* structure

Returns:
  2 if both times could be set, 1 for one only, and 0 if none

double cmml_skip_to_secs | ( | CMML * | cmml,
|  | double | seconds |
| ) |  |  |

cmml_skip_to_secs: seeks forward thru clip tags to required time offset (no backwards seeking: streaming!).

Parameters:

  | cmml | a CMML* handle
  | seconds | the time offset to seek to

Returns:
  the actual time offset seeked to or -1 on error

Examples:
  cmml-seek-offset.c, and cmml-validate.c.

Referenced by main().

double cmml_skip_to_utc | ( | CMML * | cmml,
|  | const char * | utc |
| ) |  |  |

cmml_skip_to_utc: seeks forward thru clip tags to required time offset (no backwards seeking: streaming!).

Parameters:

  | cmml | a CMML* handle
  | utc | the time offset to seek to

Returns:
  the actual time offset seeked to in seconds or -1 on error

Examples:
  cmml-seek-utc.c, and cmml-validate.c.

Referenced by main().

double cmml_skip_to_id | ( | CMML * | cmml,
|  | const char * | id |
| ) |  |  |

cmml_skip_to_id: seeks forward thru clip tags to required id (no backwards seeking: streaming!).

Parameters:

  | cmml | a CMML* handle
  | id | the name of the clip tag to seek to

Returns:
  the actual time offset seeked to in seconds or -1 on error

Examples:
  cmml-seek-clip.c, and cmml-validate.c.

Referenced by main().

double cmml_skip_to_offset | ( | CMML * | cmml,
|  | const char * | offset |
| ) |  |  |

cmml_skip_to_offset: seek forward thru clip tags and time to required fragment offset (no backwards seeking: streaming!).

Parameters:

  | cmml | a CMML* handl
  | offset | the offset given as id or time spec

Returns:
  the actual time offset seeked to in seconds or -1 on error

Examples:
  cmml-uri-file.c.

CMML_Preamble* cmml_preamble_new | ( | const char * | encoding,
|  | const char * | id,
|  | const char * | lang,
|  | const char * | dir,
|  | const char * | granulerate |
| ) |  |  |

cmml_preamble_new: Create a new CMML_Preamble.

Parameters:

  | encoding | the character encoding to be used; UTF-8 if NULL
  | id | the id attribute of the cmml tag; not used if NULL
  | lang | the lang attribute of the cmml tag; not used if NULL
  | dir | the dir attribute of the cmml tag; not used if NULL
  | granulerate | the granulerate attribute of the cmml tag; not used if NULL

Returns:
  a CMML preamble

Examples:
  cmml-write.c.

Referenced by main().

CMML_Element* cmml_element_new | ( | CMML_Element_Type | type | ) |

cmml_element_new: Create a new CMML_Element.

Parameters:

  | type | the element type to create (head, stream, or clip)

Returns:
  a element of the requested type

CMML_Stream* cmml_stream_new | ( | void |  | ) |

cmml_stream_new: Create a new CMML_Stream.

Returns:
  a stream element

CMML_Head* cmml_head_new | ( | void |  | ) |

cmml_head_new: Create a new CMML_Head.

Returns:
  a head element

Examples:
  cmml-write.c.

Referenced by main().

CMML_Clip* cmml_clip_new | ( | CMML_Time * | start_time,
|  | CMML_Time * | end_time |
| ) |  |  |

cmml_clip_new: Create a new CMML_Anchr.

Parameters:

  | start_time | the start time at which to create a clip
  | end_time | the end time at which to end the clip

Returns:
  a clip element

Examples:
  cmml-write.c.

Referenced by main().

CMML_Error* cmml_error_new | ( | CMML_Error_Type | type | ) |

cmml_error_new: Create a new CMML_Error.

Parameters:

  | type | the type of error to create as from the given list

Returns:
  an error type

CMML_Preamble* cmml_preamble_clone | ( | CMML_Preamble * | src | ) |

cmml_preamble_clone: Create a copy of a CMML_Preamble.

Parameters:

  | src | the original preamble

Returns:
  a copy of a CMML preamble

CMML_Element* cmml_element_clone | ( | CMML_Element * | src | ) |

cmml_element_clone: Create a copy of an element.

Parameters:

  | src | the original element

Returns:
  a copy of the element

CMML_Stream* cmml_stream_clone | ( | CMML_Stream * | src | ) |

cmml_stream_clone: Create a copy of a stream element.

Parameters:

  | src | the original stream element

Returns:
  a copy of the stream element

CMML_Head* cmml_head_clone | ( | CMML_Head * | src | ) |

cmml_head_clone: Create a copy of a head element.

Parameters:

  | src | the original head element

Returns:
  a copy of the head element

CMML_Clip* cmml_clip_clone | ( | CMML_Clip * | src | ) |

cmml_clip_clone: Create a copy of a clip element.

Parameters:

  | src | the original clip element

Returns:
  a copy of the clip element

Referenced by read_clip().

void cmml_preamble_destroy | ( | CMML_Preamble * | preamble | ) |

cmml_preamble_destroy: Free all memory associated with a CMML_Preamble.

Parameters:

  | preamble | the preamble to free

Examples:
  cmml-write.c.

Referenced by main().

void cmml_element_destroy | ( | CMML_Element * | element | ) |

cmml_element_destroy: Free all memory associated with a CMML_Element.

Parameters:

  | element | the element to free

void cmml_stream_destroy | ( | CMML_Stream * | stream | ) |

cmml_stream_destroy: Free a stream element.

Parameters:

  | stream | the stream element to free

void cmml_head_destroy | ( | CMML_Head * | head | ) |

cmml_head_destroy: Free a head element.

Parameters:

  | head | the head element to free

Examples:
  cmml-write.c.

Referenced by main().

void cmml_clip_destroy | ( | CMML_Clip * | clip | ) |

cmml_clip_destroy: Free a clip element.

Parameters:

  | clip | the clip element to free

Examples:
  cmml-write.c.

Referenced by main(), and read_clip().

void cmml_error_destroy | ( | CMML_Error * | error | ) |

cmml_error_destroy: Free an error streucture.

Parameters:

  | error | the error structure to free

int cmml_preamble_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Preamble * | pre |
| ) |  |  |

cmml_preamble_snprint: Prints the preamble as given in the cmml structure into the buffer buf of size n.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | pre | the preamble to print

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-validate.c, and cmml-write.c.

Referenced by main().

int cmml_element_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Element * | elem |
| ) |  |  |

cmml_element_snprint: Given a buffer buf of size n, write a CMML representation of a CMML_Element into it.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | elem | the element to print

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

int cmml_stream_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Stream * | stream |
| ) |  |  |

cmml_stream_snprint: Prints a stream element into a buffer.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | stream | the stream element structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

int cmml_stream_pretty_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Stream * | stream |
| ) |  |  |

cmml_stream_pretty_snprint: Prints a stream element into a buffer.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | stream | the stream element structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-validate.c.

Referenced by read_stream().

int cmml_head_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Head * | head |
| ) |  |  |

cmml_head_snprint: Prints a head element into a buffer.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | head | the head element structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-write.c.

int cmml_head_pretty_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Head * | head |
| ) |  |  |

cmml_head_pretty_snprint: Prints a head element into a buffer.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | head | the head element structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-validate.c.

Referenced by main(), and read_head().

int cmml_clip_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Clip * | clip |
| ) |  |  |

cmml_clip_snprint: Prints a clip element into a buffer.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | clip | the clip element structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-write.c.

int cmml_clip_pretty_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Clip * | clip |
| ) |  |  |

cmml_clip_pretty_snprint: Prints a clip element into a buffer.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | clip | the clip element structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-validate.c.

Referenced by main(), and read_clip().

int cmml_error_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_Error * | error,
|  | CMML * | cmml |
| ) |  |  |

cmml_error_snprint: Prints a string description of the CMML_Error.

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | error | the error structure
  | cmml | the cmml status structure (required for expat errors)

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

Examples:
  cmml-validate.c.

Referenced by main(), read_clip(), read_head(), and read_stream().

CMML_List* cmml_list_new | ( | void |  | ) |

cmml_list_new: Create a new list.

Returns:
  a new list

CMML_List* cmml_list_clone | ( | CMML_List * | list | ) |

cmml_list_clone: Copy a list using the default cloning function.

Parameters:

  | list | the list to clone

Returns:
  a newly cloned list

CMML_List* cmml_list_clone_with | ( | CMML_List * | list,
|  | CMML_CloneFunc | clone |
| ) |  |  |

cmml_list_clone_with: Clone a list using a custom clone function.

Parameters:

  | list | the list to clone
  | clone | the function to use to clone a list item

Returns:
  a newly cloned list

CMML_List* cmml_list_tail | ( | CMML_List * | list | ) |

cmml_list_tail: Returns the tail element of a list.

Parameters:

  | list | the list

Returns:
  the tail element

CMML_List* cmml_list_prepend | ( | CMML_List * | list,
|  | void * | data |
| ) |  |  |

cmml_list_prepend: Prepend a new node to a list containing given data.

Parameters:

  | list | the list
  | data | the data element of the newly created node

Returns:
  the new list head

CMML_List* cmml_list_append | ( | CMML_List * | list,
|  | void * | data |
| ) |  |  |

cmml_list_append: Append a new node to a list containing given data.

Parameters:

  | list | the list
  | data | the data element of the newly created node

Returns:
  the head of the list

CMML_List* cmml_list_add_before | ( | CMML_List * | list,
|  | void * | data,
|  | CMML_List * | node |
| ) |  |  |

cmml_list_add_before: Add a new node containing given data before a given node

Parameters:

  | list | the list
  | data | the data element of the newly created node
  | node | the node before which to add the newly created node

Returns:
  the head of the list (which may have changed)

CMML_List* cmml_list_add_after | ( | CMML_List * | list,
|  | void * | data,
|  | CMML_List * | node |
| ) |  |  |

cmml_list_add_after: Add a new node containing given data after a given node.

Parameters:

  | list | the list
  | data | the data element of the newly created node
  | node | the node after which to add the newly created node

Returns:
  the head of the list

CMML_List* cmml_list_find | ( | CMML_List * | list,
|  | void * | data |
| ) |  |  |

cmml_list_find: Find the first node containing given data in a list.

Parameters:

  | list | the list
  | data | the data element to find

Returns:
  the first node containing given data, or NULL if it is not found

CMML_List* cmml_list_remove | ( | CMML_List * | list,
|  | CMML_List * | node |
| ) |  |  |

cmml_list_remove: Remove a node from a list.

Parameters:

  | list | the list
  | node | the node to remove

Returns:
  the head of the list (which may have changed)

int cmml_list_length | ( | CMML_List * | list | ) |

cmml_list_length: Query the number of items in a list.

Parameters:

  | list | the list

Returns:
  the number of nodes in the list

int cmml_list_is_empty | ( | CMML_List * | list | ) |

cmml_list_is_empty: Query if a list is empty, ie. contains no items.

Parameters:

  | list | the list

Returns:
  1 if the list is empty, 0 otherwise

int cmml_list_is_singleton | ( | CMML_List * | list | ) |

cmml_list_is_singleton: Query if the list is singleton, ie. contains exactly one item

Parameters:

  | list | the list

Returns:
  1 if the list is singleton, 0 otherwise

CMML_List* cmml_list_free_with | ( | CMML_List * | list,
|  | CMML_FreeFunc | free_func |
| ) |  |  |

cmml_list_free_with: Free a list, using a given function to free each data element

Parameters:

  | list | the list
  | free_func | a function to free each data element

Returns:
  NULL on success

CMML_List* cmml_list_free | ( | CMML_List * | list | ) |

cmml_list_free: Free a list, using anx_free() to free each data element.

Parameters:

  | list | the list

Returns:
  NULL on success else the original list.

CMML_Time* cmml_time_new | ( | const char * | s | ) |

cmml_time_new: Creates a time struct from a string that contains a name-value time spec pair.

Parameters:

  | s | name-value time specification string

Returns:
  a time struct with appropriate time type (utc or seconds).

Examples:
  cmml-write.c.

Referenced by main().

CMML_Time* cmml_sec_new | ( | const char * | s | ) |

cmml_sec_new: Creates a time struct only from name-value sec specs.

Parameters:

  | s | name-value time specification string

Returns:
  a time struct.

CMML_Time* cmml_time_new_secs | ( | double | seconds | ) |

cmml_time_new_sec: Creates a time struct from a npt sec specs.

Parameters:

  | seconds | sec spec to be used for creating a new time struct

Returns:
  a time struct.

Referenced by read_clip().

CMML_Time* cmml_utc_new | ( | const char * | s | ) |

cmml_utc_new: Creates a time struct only from name-value utc specs.

Parameters:

  | s | name-value time specification string

Returns:
  a time struct.

int cmml_time_interval_new | ( | const char * | s,
|  | CMML_Time ** | t_start,
|  | CMML_Time ** | t_end |
| ) |  |  |

cmml_time_interval_new: Handles start and end times for clip tags, where we will only store sec offsets.

Parameters:

  | s | the time construct; examples: npt:40-79 or smpte-25:00:20:20-00:21:30,00:40:21
  | t_start | the start time returned
  | t_end | the end time (if any) returned

Returns:
  creates two time constructs if the string was a time range, otherwise just a t_start time, and returns the number of times created or -1 otherwise.

CMML_Time* cmml_time_new_in_sec | ( | const char * | s,
|  | CMML_Time * | ref,
|  | double | base |
| ) |  |  |

cmml_time_new_in_sec: For parsing/converting start and end time specs in clips into a seconds representation, which is the only one libcmml stores internally for clips.

Parameters:

  | s | the string that contains the time spec
  | ref | the reference utc time if given in the stream tag
  | base | the basetime in seconds as given in the stream tag

Returns:
  a time structure in seconds

CMML_Time* cmml_time_utc_to_sec | ( | CMML_Time * | t,
|  | CMML_Time * | ref,
|  | double | base |
| ) |  |  |

cmml_time_utc_to_sec: Convert a time from utc to seconds with reference to a basetime

Parameters:

  | t | the given time struct
  | ref | the reference utc time if given in the stream tag
  | base | the basetime in seconds as given in the stream tag

Returns:
  a time structure in seconds

void cmml_time_free | ( | CMML_Time * | t | ) |

cmml_time_free: Free time struct

Parameters:

  | t | the given time struct

Referenced by read_clip().

CMML_Time* cmml_time_clone | ( | CMML_Time * | t | ) |

cmml_time_clone: Copying times

Parameters:

  | t | the given time struct

Returns:
  the cloned time struct

double cmml_sec_parse | ( | const char * | s | ) |

cmml_sec_parse: for parsing sec specs with "npt:", "smpte:" etc.

Parameters:

  | s | the string containing the name-value time specification

Returns:
  the parsed seconds as a double

Referenced by read_clip().

CMML_UTC* cmml_utc_parse | ( | const char * | s | ) |

cmml_utc_parse: for parsing utc times with "clock:"

Parameters:

  | s | the string containing only the utc string as YYYYMMDDTHHmmss.hhZ

Returns:
  a utc time structure

CMML_UTC* cmml_utc_clone | ( | CMML_UTC * | t | ) |

cmml_utc_clone: for copying utc times

Parameters:

  | t | the src utc time structure

Returns:
  the copied utc time structure

double cmml_utc_diff | ( | CMML_UTC * | t2,
|  | CMML_UTC * | t1 |
| ) |  |  |

cmml_utc_diff: for calculating the difference between two utc times as t2-t1 in seconds

Parameters:

  | t2 | the more recent utc time
  | t1 | the less recent utc time

Returns:
  the difference between the two utc times in seconds

int cmml_npt_snprint | ( | char * | buf,
|  | int | n,
|  | double | seconds |
| ) |  |  |

cmml_npt_snprint: prints npt time to a string

Parameters:

  | buf | buffer to print string to
  | n | the size of the buffer buf
  | seconds | the npt time in seconds as a double

Returns:
  number of characters written to the buffer (including the terminating \0) or a negative value on failure.

Examples:
  cmml-write.c.

Referenced by main().

int cmml_utc_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_UTC * | t |
| ) |  |  |

cmml_utc_snprint: for printing utc times

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | t | the utc time structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

int cmml_utc_pretty_snprint | ( | char * | buf,
|  | int | n,
|  | CMML_UTC * | t |
| ) |  |  |

cmml_utc_pretty_snprint: for printing utc times

Parameters:

  | buf | the buffer to print into
  | n | the size of the buffer buf
  | t | the utc time structure

Returns:
  the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.