cmml.h

Go to the documentation of this file.

/* Copyright (C) 2003 CSIRO Australia
 
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:
   
   - Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
   
   - Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
   
   - Neither the name of the CSIRO nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
   
   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
   PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
 
/* cmml.h */
 
#ifndef __CMML_H__
#define __CMML_H__
 
#include <stdio.h>
#include <expat.h>
 
#ifndef _CMML_PRIVATE
typedef void CMML;
#endif
 
/* ------------------------- TYPES --------------------------------- */
/* CMML_Time and CMML_List are kept here and not in cmml_private.h   */
/* because the library user may need detailed access to these fields */
 
typedef struct {
  short   tm_hsec; 
  short   tm_sec;  
  short   tm_min;  
  short   tm_hour; 
  short   tm_mday; 
  short   tm_mon;  
  short   tm_year; 
} CMML_UTC;
 
typedef enum _CMML_Time_Type {
  CMML_SEC_TIME,   
  CMML_UTC_TIME    
} CMML_Time_Type;
 
 
typedef struct {
  char *tstr;          
  CMML_Time_Type type; 
  union {
    CMML_UTC * utc;    
    double sec;        
  } t;
} CMML_Time;
 
 
typedef struct _CMML_List CMML_List;
struct _CMML_List {
  CMML_List * prev; 
  CMML_List * next; 
  void * data;      
};
 
typedef void * (*CMML_CloneFunc) (void * data);
 
typedef void * (*CMML_FreeFunc) (void * data);
 
typedef int (*CMML_CmpFunc) (void * cmp_ctx, void * s1, void * s2);
 
 
typedef struct {
  char *xml_version;      
  char *xml_encoding;     
  int   xml_standalone;   
  int   doctype_declared; 
  char *cmml_lang;        
  char *cmml_dir;         
  char *cmml_id;          
  char *cmml_xmlns;       
  char *cmml_granulerate; 
} CMML_Preamble;
 
 
typedef struct {
  char *id;    
  char *name;  
  char *value; 
} CMML_ParamElement;
 
typedef struct {
  char *id;               
  char *lang;             
  char *dir;              
  char *granulerate;      
  char *contenttype;      
  char *src;              
  CMML_Time * start_time; 
  CMML_Time * end_time;   
  char *title;            
  CMML_List * param;      
} CMML_ImportElement;
 
typedef struct {
  char *id;             
  CMML_Time * basetime; 
  CMML_Time * utc;      
  CMML_List * import;   
} CMML_Stream;
 
 
typedef struct {
  char *id;      
  char *lang;    
  char *dir;     
  char *name;    
  char *content; 
  char *scheme;  
} CMML_MetaElement;
 
typedef struct {
  char *id;         
  char *link_class; 
  char *title;      
  char *lang;       
  char *dir;        
  char *href;       
  char *type;       
  char *rel;        
  char *rev;        
  char *media;      
} CMML_LinkElement;
 
typedef struct {
  char *head_id;    
  char *lang;       
  char *dir;        
  char *profile;    
  char *title;      
  char *title_id;   
  char *title_lang; 
  char *title_dir;  
  char *base_id;    
  char *base_href;  
  CMML_List * meta; 
  CMML_List * link; 
} CMML_Head;
 
 
typedef struct {
  char *clip_id;         
  char *clip_class;      
  char *title;           
  char *lang;            
  char *dir;             
  char *track;           
  CMML_Time *start_time; 
  CMML_Time *end_time;   
  CMML_List * meta;      
  char *anchor_id;       
  char *anchor_class;    
  char *anchor_title;    
  char *anchor_lang;     
  char *anchor_dir;      
  char *anchor_href;     
  char *anchor_text;     
  char *img_id;          
  char *img_class;       
  char *img_title;       
  char *img_lang;        
  char *img_dir;         
  char *img_src;         
  char *img_alt;         
  char *desc_id;         
  char *desc_class;      
  char *desc_title;      
  char *desc_lang;       
  char *desc_dir;        
  char *desc_text;       
} CMML_Clip;
 
typedef enum _CMML_Element_Type {
  CMML_NONE,   
  CMML_CMML,   
  CMML_STREAM, 
  CMML_IMPORT, 
  CMML_HEAD,   
  CMML_CLIP    
} CMML_Element_Type;
 
 
typedef struct {
  CMML_Element_Type type; 
  union {
    CMML_Stream * stream; 
    CMML_Head   * head;   
    CMML_Clip   * clip;   
  } e;
} CMML_Element;
 
 
typedef enum _CMML_Error_Type {
  /* general processing feedback */
  CMML_OK,           
  CMML_EOF,          
  /* fatal errors */
  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,    
  /* sloppy errors */
  CMML_FORMAT_ERROR,      
  CMML_UNKNOWN_TAG,       
  CMML_TAG_IGNORED,       
  CMML_XMLNS_REDEFINED,   
  CMML_NONSEQUENTIAL_CLIP 
} CMML_Error_Type;
 
typedef struct {
  CMML_Error_Type type; 
  long line;            
  long col;             
} CMML_Error;
 
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);
 
 
/* ----------------------  API  --------------------------------*/
 
/* --------------------------------- *
 * CMML parsing: functions in cmml.c *
 * --------------------------------- */
 
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); /* file */
 
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 element handling: cmml_element.c cmml_snprint.c *
 * ---------------------------------------------------- */
 
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);
 
 
/* ----------------------------------------------- *
 * helper functions for list handling: cmml_list.c *
 * ----------------------------------------------- */
 
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);
 
 
/* ----------------------------------------------- *
 * helper functions for time handling: cmml_time.c *
 * ----------------------------------------------- */
 
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);
 
 
 
#endif /* __CMML_H__ */