libcmml  0.9.1
Data Structures | Typedefs | Enumerations | Functions
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

CMMLcmml_open (char *XMLfilename)
 
CMMLcmml_new (FILE *file)
 
FILE * cmml_destroy (CMML *cmml)
 
CMMLcmml_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_Preamblecmml_get_preamble (CMML *cmml)
 
CMML_Streamcmml_get_last_stream (CMML *cmml)
 
CMML_Headcmml_get_last_head (CMML *cmml)
 
CMML_Clipcmml_get_last_clip (CMML *cmml)
 
CMML_Clipcmml_get_previous_clip (CMML *cmml)
 
CMML_Errorcmml_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_Preamblecmml_preamble_new (char *encoding, char *id, char *lang, char *dir, char *granulerate)
 
CMML_Elementcmml_element_new (CMML_Element_Type type)
 
CMML_Streamcmml_stream_new (void)
 
CMML_Headcmml_head_new (void)
 
CMML_Clipcmml_clip_new (CMML_Time *start_time, CMML_Time *end_time)
 
CMML_Errorcmml_error_new (CMML_Error_Type type)
 
CMML_Preamblecmml_preamble_clone (CMML_Preamble *src)
 
CMML_Elementcmml_element_clone (CMML_Element *src)
 
CMML_Streamcmml_stream_clone (CMML_Stream *src)
 
CMML_Headcmml_head_clone (CMML_Head *src)
 
CMML_Clipcmml_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_Listcmml_list_new (void)
 
CMML_Listcmml_list_clone (CMML_List *list)
 
CMML_Listcmml_list_clone_with (CMML_List *list, CMML_CloneFunc clone)
 
CMML_Listcmml_list_tail (CMML_List *list)
 
CMML_Listcmml_list_prepend (CMML_List *list, void *data)
 
CMML_Listcmml_list_append (CMML_List *list, void *data)
 
CMML_Listcmml_list_add_before (CMML_List *list, void *data, CMML_List *node)
 
CMML_Listcmml_list_add_after (CMML_List *list, void *data, CMML_List *node)
 
CMML_Listcmml_list_find (CMML_List *list, void *data)
 
CMML_Listcmml_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_Listcmml_list_free_with (CMML_List *list, CMML_FreeFunc free_func)
 
CMML_Listcmml_list_free (CMML_List *list)
 
CMML_Timecmml_time_new (const char *s)
 
CMML_Timecmml_sec_new (const char *s)
 
CMML_Timecmml_time_new_secs (double seconds)
 
CMML_Timecmml_utc_new (const char *s)
 
int cmml_time_interval_new (const char *s, CMML_Time **t_start, CMML_Time **t_end)
 
CMML_Timecmml_time_new_in_sec (const char *s, CMML_Time *ref, double base)
 
CMML_Timecmml_time_utc_to_sec (CMML_Time *t, CMML_Time *ref, double base)
 
void cmml_time_free (CMML_Time *t)
 
CMML_Timecmml_time_clone (CMML_Time *t)
 
double cmml_sec_parse (const char *s)
 
CMML_UTCcmml_utc_parse (const char *s)
 
CMML_UTCcmml_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

◆ CMML

typedef void CMML

A CMML handle.

◆ CMML_Time_Type

CMML_Time_Type: enumerates the different time types

◆ CMML_List

typedef struct _CMML_List CMML_List

CMML_List: A doubly linked list

◆ CMML_CloneFunc

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

CMML_CloneFunc: Signature of a cloning function for CMML_List.

◆ CMML_FreeFunc

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

CMML_FreeFunc: Signature of a freeing function.

◆ CMML_CmpFunc

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

◆ CMML_Element_Type

CMML_Element_Type: indication of what the CMML_Element actually represents.

◆ 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

◆ CMMLReadStream

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
cmmlthe CMML* handle in use
streamthe stream element's content represented in a CMML_Stream*
user_datauser defined data
Returns
0 on success, 1 on error

◆ CMMLReadHead

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
cmmlthe CMML* handle in use
headthe head element's content represented in a CMML_Head*
user_datauser defined data
Returns
0 on success, 1 on error

◆ CMMLReadClip

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
cmmlthe CMML* handle in use
clipthe clip element's content represented in a CMML_Clip*
user_datauser defined data
Returns
0 on success, 1 on error

Enumeration Type Documentation

◆ _CMML_Time_Type

CMML_Time_Type: enumerates the different time types

Enumerator
CMML_SEC_TIME 

time is seconds

CMML_UTC_TIME 

time is utc

◆ _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

◆ _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
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_open()

CMML* cmml_open ( 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_open_stdio instead.

Parameters
XMLfilenamea 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_new()

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
filean open FILE pointer
Returns
a CMML* handle
Examples:
cmml-parse.c, and cmml-validate.c.

Referenced by main().

◆ cmml_destroy()

FILE* cmml_destroy ( CMML cmml)

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

Parameters
cmmla CMML* handle
Returns
the open FILE pointer
Examples:
cmml-parse.c.

◆ cmml_close()

CMML* cmml_close ( CMML cmml)

cmml_close: Close a CMML object.

Parameters
cmmla 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().

◆ cmml_set_read_callbacks()

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
cmmla CMML* handle
read_streama CMMLReadStream callback function for the stream tag
read_heada CMMLReadHead callback function for the head tag
read_clipa CMMLReadClip callback function for the a tag
user_dataa 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().

◆ cmml_read()

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
cmmla CMML* handle
nnumber 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().

◆ cmml_set_sloppy()

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
cmmla CMML* handle
valuea bool value to set the sloppy handling
Examples:
cmml-validate.c.

Referenced by main().

◆ cmml_get_preamble()

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
cmmla CMML* handle
Returns
1 if CMML tag specificed, 0 otherwise
Examples:
cmml-validate.c.

Referenced by main().

◆ cmml_get_last_stream()

CMML_Stream* cmml_get_last_stream ( CMML cmml)

cmml_get_last_stream: Return a copy of the current stream element.

Parameters
cmmla CMML* handle
Returns
a CMML_Stream* structure with the stream element details; NULL if none existed

◆ cmml_get_last_head()

CMML_Head* cmml_get_last_head ( CMML cmml)

cmml_get_last_head: Return a copy of the current head element.

Parameters
cmmla CMML* handle
Returns
a CMML_Head* structure with the head element details; NULL if none existed

◆ cmml_get_last_clip()

CMML_Clip* cmml_get_last_clip ( CMML cmml)

cmml_get_last_clip: Return a copy of the current clip element.

Parameters
cmmla CMML* handle
Returns
a CMML_Clip* structure with the clip element details; NULL if none existed

◆ cmml_get_previous_clip()

CMML_Clip* cmml_get_previous_clip ( CMML cmml)

cmml_get_previous_clip: Return a copy of the previous clip element.

Parameters
cmmla CMML* handle
Returns
a CMML_Clip* structure with the clip element details; NULL if none existed

◆ cmml_get_last_error()

CMML_Error* cmml_get_last_error ( CMML cmml)

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

Parameters
cmmla 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().

◆ cmml_error_clear()

void cmml_error_clear ( CMML cmml)

cmml_error_clear: Clear the last error.

Parameters
cmmla CMML* handle

◆ cmml_set_window()

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
cmmla CMML* handle
startthe start time of the interval given as CMML_Time* structure
endthe 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

◆ cmml_skip_to_secs()

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
cmmla CMML* handle
secondsthe 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().

◆ cmml_skip_to_utc()

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
cmmla CMML* handle
utcthe 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().

◆ cmml_skip_to_id()

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
cmmla CMML* handle
idthe 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().

◆ cmml_skip_to_offset()

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
cmmla CMML* handl
offsetthe 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_new()

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

cmml_preamble_new: Create a new CMML_Preamble.

Parameters
encodingthe character encoding to be used; UTF-8 if NULL
idthe id attribute of the cmml tag; not used if NULL
langthe lang attribute of the cmml tag; not used if NULL
dirthe dir attribute of the cmml tag; not used if NULL
granuleratethe granulerate attribute of the cmml tag; not used if NULL
Returns
a CMML preamble
Examples:
cmml-write.c.

Referenced by main().

◆ cmml_element_new()

CMML_Element* cmml_element_new ( CMML_Element_Type  type)

cmml_element_new: Create a new CMML_Element.

Parameters
typethe element type to create (head, stream, or clip)
Returns
a element of the requested type

◆ cmml_stream_new()

CMML_Stream* cmml_stream_new ( void  )

cmml_stream_new: Create a new CMML_Stream.

Returns
a stream element

◆ cmml_head_new()

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_new()

CMML_Clip* cmml_clip_new ( CMML_Time start_time,
CMML_Time end_time 
)

cmml_clip_new: Create a new CMML_Anchr.

Parameters
start_timethe start time at which to create an clip
end_timethe end time at which to end the clip
Returns
a clip element
Examples:
cmml-write.c.

Referenced by main().

◆ cmml_error_new()

CMML_Error* cmml_error_new ( CMML_Error_Type  type)

cmml_error_new: Create a new CMML_Error.

Parameters
typethe type of error to create as from the given list
Returns
an error type

◆ cmml_preamble_clone()

CMML_Preamble* cmml_preamble_clone ( CMML_Preamble src)

cmml_preamble_clone: Create a copy of a CMML_Preamble.

Parameters
srcthe original preamble
Returns
a copy of a CMML preamble

◆ cmml_element_clone()

CMML_Element* cmml_element_clone ( CMML_Element src)

cmml_element_clone: Create a copy of an element.

Parameters
srcthe original element
Returns
a copy of the element

◆ cmml_stream_clone()

CMML_Stream* cmml_stream_clone ( CMML_Stream src)

cmml_stream_clone: Create a copy of a stream element.

Parameters
srcthe original stream element
Returns
a copy of the stream element

◆ cmml_head_clone()

CMML_Head* cmml_head_clone ( CMML_Head src)

cmml_head_clone: Create a copy of a head element.

Parameters
srcthe original head element
Returns
a copy of the head element

◆ cmml_clip_clone()

CMML_Clip* cmml_clip_clone ( CMML_Clip src)

cmml_clip_clone: Create a copy of a clip element.

Parameters
srcthe original clip element
Returns
a copy of the clip element

Referenced by read_clip().

◆ cmml_preamble_destroy()

void cmml_preamble_destroy ( CMML_Preamble preamble)

cmml_preamble_destroy: Free all memory associated with a CMML_Preamble.

Parameters
preamblethe preamble to free
Examples:
cmml-write.c.

Referenced by main().

◆ cmml_element_destroy()

void cmml_element_destroy ( CMML_Element element)

cmml_element_destroy: Free all memory associated with a CMML_Element.

Parameters
elementthe element to free

◆ cmml_stream_destroy()

void cmml_stream_destroy ( CMML_Stream stream)

cmml_stream_destroy: Free a stream element.

Parameters
streamthe stream element to free

◆ cmml_head_destroy()

void cmml_head_destroy ( CMML_Head head)

cmml_head_destroy: Free a head element.

Parameters
headthe head element to free
Examples:
cmml-write.c.

Referenced by main().

◆ cmml_clip_destroy()

void cmml_clip_destroy ( CMML_Clip clip)

cmml_clip_destroy: Free a clip element.

Parameters
clipthe clip element to free
Examples:
cmml-write.c.

Referenced by main(), and read_clip().

◆ cmml_error_destroy()

void cmml_error_destroy ( CMML_Error error)

cmml_error_destroy: Free an error streucture.

Parameters
errorthe error structure to free

◆ cmml_preamble_snprint()

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
bufthe buffer to print into
nthe size of the buffer buf
prethe 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().

◆ cmml_element_snprint()

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
bufthe buffer to print into
nthe size of the buffer buf
elemthe element to print
Returns
the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

◆ cmml_stream_snprint()

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

cmml_stream_snprint: Prints a stream element into a buffer.

Parameters
bufthe buffer to print into
nthe size of the buffer buf
streamthe stream element structure
Returns
the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

◆ cmml_stream_pretty_snprint()

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

cmml_stream_pretty_snprint: Prints a stream element into a buffer.

Parameters
bufthe buffer to print into
nthe size of the buffer buf
streamthe 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().

◆ cmml_head_snprint()

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

cmml_head_snprint: Prints a head element into a buffer.

Parameters
bufthe buffer to print into
nthe size of the buffer buf
headthe 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.

◆ cmml_head_pretty_snprint()

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

cmml_head_pretty_snprint: Prints a head element into a buffer.

Parameters
bufthe buffer to print into
nthe size of the buffer buf
headthe 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().

◆ cmml_clip_snprint()

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

cmml_clip_snprint: Prints a clip element into a buffer.

Parameters
bufthe buffer to print into
nthe size of the buffer buf
clipthe 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.

◆ cmml_clip_pretty_snprint()

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

cmml_clip_pretty_snprint: Prints a clip element into a buffer.

Parameters
bufthe buffer to print into
nthe size of the buffer buf
clipthe 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().

◆ cmml_error_snprint()

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
bufthe buffer to print into
nthe size of the buffer buf
errorthe error structure
cmmlthe 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_new()

CMML_List* cmml_list_new ( void  )

cmml_list_new: Create a new list.

Returns
a new list

◆ cmml_list_clone()

CMML_List* cmml_list_clone ( CMML_List list)

cmml_list_clone: Copy a list using the default cloning function.

Parameters
listthe list to clone
Returns
a newly cloned list

◆ cmml_list_clone_with()

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
listthe list to clone
clonethe function to use to clone a list item
Returns
a newly cloned list

◆ cmml_list_tail()

CMML_List* cmml_list_tail ( CMML_List list)

cmml_list_tail: Returns the tail element of a list.

Parameters
listthe list
Returns
the tail element

◆ cmml_list_prepend()

CMML_List* cmml_list_prepend ( CMML_List list,
void *  data 
)

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

Parameters
listthe list
datathe data element of the newly created node
Returns
the new list head

◆ cmml_list_append()

CMML_List* cmml_list_append ( CMML_List list,
void *  data 
)

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

Parameters
listthe list
datathe data element of the newly created node
Returns
the head of the list

◆ cmml_list_add_before()

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
listthe list
datathe data element of the newly created node
nodethe node before which to add the newly created node
Returns
the head of the list (which may have changed)

◆ cmml_list_add_after()

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
listthe list
datathe data element of the newly created node
nodethe node after which to add the newly created node
Returns
the head of the list

◆ cmml_list_find()

CMML_List* cmml_list_find ( CMML_List list,
void *  data 
)

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

Parameters
listthe list
datathe data element to find
Returns
the first node containing given data, or NULL if it is not found

◆ cmml_list_remove()

CMML_List* cmml_list_remove ( CMML_List list,
CMML_List node 
)

cmml_list_remove: Remove a node from a list.

Parameters
listthe list
nodethe node to remove
Returns
the head of the list (which may have changed)

◆ cmml_list_length()

int cmml_list_length ( CMML_List list)

cmml_list_length: Query the number of items in a list.

Parameters
listthe list
Returns
the number of nodes in the list

◆ cmml_list_is_empty()

int cmml_list_is_empty ( CMML_List list)

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

Parameters
listthe list
Returns
1 if the list is empty, 0 otherwise

◆ cmml_list_is_singleton()

int cmml_list_is_singleton ( CMML_List list)

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

Parameters
listthe list
Returns
1 if the list is singleton, 0 otherwise

◆ cmml_list_free_with()

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
listthe list
free_funca function to free each data element
Returns
NULL on success

◆ cmml_list_free()

CMML_List* cmml_list_free ( CMML_List list)

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

Parameters
listthe list
Returns
NULL on success else the original list.

◆ cmml_time_new()

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
sname-value time specification string
Returns
a time struct with appropriate time type (utc or seconds).
Examples:
cmml-write.c.

Referenced by main().

◆ cmml_sec_new()

CMML_Time* cmml_sec_new ( const char *  s)

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

Parameters
sname-value time specification string
Returns
a time struct.

◆ cmml_time_new_secs()

CMML_Time* cmml_time_new_secs ( double  seconds)

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

Parameters
secondssec spec to be used for creating a new time struct
Returns
a time struct.

Referenced by read_clip().

◆ cmml_utc_new()

CMML_Time* cmml_utc_new ( const char *  s)

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

Parameters
sname-value time specification string
Returns
a time struct.

◆ cmml_time_interval_new()

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
sthe time construct; examples: npt:40-79 or smpte-25:00:20:20-00:21:30,00:40:21
t_startthe start time returned
t_endthe 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_new_in_sec()

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
sthe string that contains the time spec
refthe reference utc time if given in the stream tag
basethe basetime in seconds as given in the stream tag
Returns
a time structure in seconds

◆ cmml_time_utc_to_sec()

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
tthe given time struct
refthe reference utc time if given in the stream tag
basethe basetime in seconds as given in the stream tag
Returns
a time structure in seconds

◆ cmml_time_free()

void cmml_time_free ( CMML_Time t)

cmml_time_free: Free time struct

Parameters
tthe given time struct

Referenced by read_clip().

◆ cmml_time_clone()

CMML_Time* cmml_time_clone ( CMML_Time t)

cmml_time_clone: Copying times

Parameters
tthe given time struct
Returns
the cloned time struct

◆ cmml_sec_parse()

double cmml_sec_parse ( const char *  s)

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

Parameters
sthe string containing the name-value time specification
Returns
the parsed seconds as a double

Referenced by read_clip().

◆ cmml_utc_parse()

CMML_UTC* cmml_utc_parse ( const char *  s)

cmml_utc_parse: for parsing utc times with "clock:"

Parameters
sthe string containing only the utc string as YYYYMMDDTHHmmss.hhZ
Returns
a utc time structure

◆ cmml_utc_clone()

CMML_UTC* cmml_utc_clone ( CMML_UTC t)

cmml_utc_clone: for copying utc times

Parameters
tthe src utc time structure
Returns
the copied utc time structure

◆ cmml_utc_diff()

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
t2the more recent utc time
t1the less recent utc time
Returns
the difference between the two utc times in seconds

◆ cmml_npt_snprint()

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

cmml_npt_snprint: prints npt time to a string

Parameters
bufbuffer to print string to
nthe size of the buffer buf
secondsthe 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().

◆ cmml_utc_snprint()

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

cmml_utc_snprint: for printing utc times

Parameters
bufthe buffer to print into
nthe size of the buffer buf
tthe utc time structure
Returns
the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.

◆ cmml_utc_pretty_snprint()

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

cmml_utc_pretty_snprint: for printing utc times

Parameters
bufthe buffer to print into
nthe size of the buffer buf
tthe utc time structure
Returns
the number of characters written to the buffer (including the terminating \0) or -1 if buffer too small.