libcmml  0.9.1
cmml.h
Go to the documentation of this file.
00001 /* Copyright (C) 2003 CSIRO Australia
00002 
00003    Redistribution and use in source and binary forms, with or without
00004    modification, are permitted provided that the following conditions
00005    are met:
00006    
00007    - Redistributions of source code must retain the above copyright
00008    notice, this list of conditions and the following disclaimer.
00009    
00010    - Redistributions in binary form must reproduce the above copyright
00011    notice, this list of conditions and the following disclaimer in the
00012    documentation and/or other materials provided with the distribution.
00013    
00014    - Neither the name of the CSIRO nor the names of its
00015    contributors may be used to endorse or promote products derived from
00016    this software without specific prior written permission.
00017    
00018    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00019    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00020    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
00021    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
00022    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00023    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00024    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00025    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00026    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00027    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029 */
00030 
00031 /* cmml.h */
00032 
00033 #ifndef __CMML_H__
00034 #define __CMML_H__
00035 
00043 #include <stdio.h>
00044 #include <expat.h>
00045 
00049 #ifndef _CMML_PRIVATE
00050 typedef void CMML;
00051 #endif
00052 
00053 /* ------------------------- TYPES --------------------------------- */
00054 /* CMML_Time and CMML_List are kept here and not in cmml_private.h   */
00055 /* because the library user may need detailed access to these fields */
00056 
00061 typedef struct {
00062   short   tm_hsec; 
00063   short   tm_sec;  
00064   short   tm_min;  
00065   short   tm_hour; 
00066   short   tm_mday; 
00067   short   tm_mon;  
00068   short   tm_year; 
00070 } CMML_UTC;
00071 
00075 typedef enum _CMML_Time_Type {
00076   CMML_SEC_TIME,   
00077   CMML_UTC_TIME    
00078 } CMML_Time_Type;
00079 
00080 
00085 typedef struct {
00086   char *tstr;          
00087   CMML_Time_Type type; 
00089   union {
00090     CMML_UTC * utc;    
00091     double sec;        
00092   } t;
00093 } CMML_Time ;
00094 
00095 
00099 typedef struct _CMML_List CMML_List;
00105 struct _CMML_List {
00106   CMML_List * prev; 
00107   CMML_List * next; 
00108   void * data;      
00109 };
00110 
00114 typedef void * (*CMML_CloneFunc) (void * data);
00115 
00119 typedef void * (*CMML_FreeFunc) (void * data);
00120 
00128 typedef int (*CMML_CmpFunc) (void * cmp_ctx, void * s1, void * s2);
00129 
00130 
00136 typedef struct {
00137   char *xml_version;      
00138   char *xml_encoding;     
00139   int   xml_standalone;   
00140   int   doctype_declared; 
00141   char *cmml_lang;        
00142   char *cmml_dir;         
00143   char *cmml_id;          
00144   char *cmml_xmlns;       
00145   char *cmml_granulerate; 
00146 } CMML_Preamble;
00147 
00148 
00153 typedef struct {
00154   char *id;    
00155   char *name;  
00156   char *value; 
00157 } CMML_ParamElement;
00158 
00162 typedef struct {
00163   char *id;               
00164   char *lang;             
00165   char *dir;              
00166   char *granulerate;      
00167   char *contenttype;      
00168   char *src;              
00169   CMML_Time * start_time; 
00170   CMML_Time * end_time;   
00171   char *title;            
00172   CMML_List * param;      
00174 } CMML_ImportElement;
00175 
00182 typedef struct {
00183   char *id;             
00184   CMML_Time * basetime; 
00185   CMML_Time * utc;      
00186   CMML_List * import;   
00187 } CMML_Stream;
00188 
00189 
00194 typedef struct {
00195   char *id;      
00196   char *lang;    
00197   char *dir;     
00198   char *name;    
00199   char *content; 
00200   char *scheme;  
00201 } CMML_MetaElement;
00202 
00207 typedef struct {
00208   char *id;      
00209   char *class;   
00210   char *title;   
00211   char *lang;    
00212   char *dir;     
00213   char *href;    
00214   char *type;    
00215   char *rel;     
00216   char *rev;     
00217   char *media;   
00218 } CMML_LinkElement;
00219 
00223 typedef struct {
00224   char *head_id;    
00225   char *lang;       
00226   char *dir;        
00227   char *profile;    
00228   char *title;      
00229   char *title_id;   
00230   char *title_lang; 
00231   char *title_dir;  
00232   char *base_id;    
00233   char *base_href;  
00234   CMML_List * meta; 
00235   CMML_List * link; 
00236 } CMML_Head;
00237 
00238 
00242 typedef struct {
00243   char *clip_id;         
00244   char *class;           
00245   char *title;           
00246   char *lang;            
00247   char *dir;             
00248   char *track;           
00249   CMML_Time *start_time; 
00250   CMML_Time *end_time;   
00251   CMML_List * meta;      
00252   char *anchor_id;       
00253   char *anchor_class;    
00254   char *anchor_title;    
00255   char *anchor_lang;     
00256   char *anchor_dir;      
00257   char *anchor_href;     
00258   char *anchor_text;     
00259   char *img_id;          
00260   char *img_class;       
00261   char *img_title;       
00262   char *img_lang;        
00263   char *img_dir;         
00264   char *img_src;         
00265   char *img_alt;         
00266   char *desc_id;         
00267   char *desc_class;      
00268   char *desc_title;      
00269   char *desc_lang;       
00270   char *desc_dir;        
00271   char *desc_text;       
00272 } CMML_Clip;
00273 
00278 typedef enum _CMML_Element_Type {
00279   CMML_NONE,   
00280   CMML_CMML,   
00281   CMML_STREAM, 
00282   CMML_IMPORT, 
00283   CMML_HEAD,   
00284   CMML_CLIP    
00285 } CMML_Element_Type;
00286 
00287 
00293 typedef struct {
00294   CMML_Element_Type type; 
00296   union {
00297     CMML_Stream * stream; 
00298     CMML_Head   * head;   
00299     CMML_Clip   * clip;   
00300   } e;
00301 } CMML_Element;
00302 
00303 
00312 typedef enum _CMML_Error_Type {
00313   /* general processing feedback */
00314   CMML_OK,           
00315   CMML_EOF,          
00316   /* fatal errors */
00317   CMML_READ_ERROR,   
00318   CMML_TIME_ERROR,   
00319   CMML_MALLOC_ERROR, 
00320   CMML_EXPAT_ERROR,  
00321   CMML_PARSE_ERROR,  
00322   CMML_NO_CMML_TAG,  
00323   CMML_NO_HEAD_TAG,  
00324   CMML_STREAM_NOT_FIRST,  
00325   CMML_HEAD_AFTER_CLIP,   
00326   CMML_DUPLICATE_STREAM,  
00327   CMML_DUPLICATE_HEAD,    
00328   /* sloppy errors */
00329   CMML_FORMAT_ERROR,      
00330   CMML_UNKNOWN_TAG,       
00331   CMML_TAG_IGNORED,       
00332   CMML_XMLNS_REDEFINED,   
00333   CMML_NONSEQUENTIAL_CLIP 
00334 } CMML_Error_Type;
00335 
00340 typedef struct {
00341   CMML_Error_Type type; 
00342   long line;            
00343   long col;             
00344 } CMML_Error;
00345 
00357 typedef int (*CMMLReadStream)  (CMML *cmml, const CMML_Stream *stream,
00358                                void * user_data);
00370 typedef int (*CMMLReadHead)   (CMML *cmml, const CMML_Head *head,
00371                                void * user_data);
00372 
00384 typedef int (*CMMLReadClip) (CMML *cmml, const CMML_Clip *clip,
00385                                void * user_data);
00386 
00387 
00388 /* ----------------------  API  --------------------------------*/
00389 
00390 /* --------------------------------- *
00391  * CMML parsing: functions in cmml.c *
00392  * --------------------------------- */
00393 
00404 CMML * cmml_open (char *XMLfilename);
00405 
00417 CMML * cmml_new (FILE * file);
00418 
00427 FILE * cmml_destroy (CMML * cmml);
00428 
00437 CMML * cmml_close (CMML * cmml);
00438 
00454 int cmml_set_read_callbacks (CMML *cmml,
00455                              CMMLReadStream read_stream,
00456                              CMMLReadHead read_head,
00457                              CMMLReadClip read_clip,
00458                              void * user_data);
00459 
00472 long cmml_read (CMML *cmml, long n); /* file */
00473 
00483 void cmml_set_sloppy (CMML *cmml, int value);
00484 
00493 CMML_Preamble * cmml_get_preamble (CMML *cmml);
00494 
00503 CMML_Stream * cmml_get_last_stream (CMML *cmml);
00504 
00513 CMML_Head   * cmml_get_last_head   (CMML *cmml);
00514 
00523 CMML_Clip * cmml_get_last_clip (CMML *cmml);
00524 
00534 CMML_Clip * cmml_get_previous_clip (CMML *cmml);
00535 
00545 CMML_Error * cmml_get_last_error (CMML * cmml);
00546 
00547 
00553 void         cmml_error_clear (CMML * cmml);
00554 
00565 int cmml_set_window (CMML * cmml, CMML_Time * start, CMML_Time * end);
00566 
00576 double cmml_skip_to_secs (CMML *cmml, double seconds);
00577 
00587 double cmml_skip_to_utc  (CMML *cmml, const char * utc);
00588 
00598 double cmml_skip_to_id   (CMML *cmml, const char * id);
00599 
00609 double cmml_skip_to_offset (CMML *cmml, const char * offset);
00610 
00611 
00612 /* ---------------------------------------------------- *
00613  * CMML element handling: cmml_element.c cmml_snprint.c *
00614  * ---------------------------------------------------- */
00615 
00627 CMML_Preamble * cmml_preamble_new (char *encoding, char *id, char *lang, char *dir, char *granulerate);
00628 
00636 CMML_Element * cmml_element_new (CMML_Element_Type type);
00637 
00643 CMML_Stream  * cmml_stream_new   (void);
00644 
00650 CMML_Head    * cmml_head_new    (void);
00651 
00660 CMML_Clip  * cmml_clip_new  (CMML_Time *start_time, CMML_Time *end_time);
00661 
00669 CMML_Error   * cmml_error_new   (CMML_Error_Type type);
00670 
00678 CMML_Preamble * cmml_preamble_clone (CMML_Preamble * src);
00679 
00687 CMML_Element * cmml_element_clone (CMML_Element * src);
00688 
00696 CMML_Stream  * cmml_stream_clone  (CMML_Stream  * src);
00697 
00705 CMML_Head    * cmml_head_clone    (CMML_Head    * src);
00706 
00714 CMML_Clip  * cmml_clip_clone  (CMML_Clip  * src);
00715 
00722 void cmml_preamble_destroy (CMML_Preamble *preamble);
00723 
00730 void cmml_element_destroy (CMML_Element *element);
00731 
00737 void cmml_stream_destroy  (CMML_Stream  *stream);
00738 
00744 void cmml_head_destroy    (CMML_Head    *head);
00745 
00751 void cmml_clip_destroy  (CMML_Clip  *clip);
00752 
00758 void cmml_error_destroy   (CMML_Error   *error);
00759 
00771 int cmml_preamble_snprint(char *buf, int n, CMML_Preamble *pre);
00772 
00785 int cmml_element_snprint        (char *buf, int n, CMML_Element *elem);
00786 
00797 int cmml_stream_snprint         (char *buf, int n, CMML_Stream  *stream);
00798 
00809 int cmml_stream_pretty_snprint  (char *buf, int n, CMML_Stream  *stream);
00810 
00821 int cmml_head_snprint           (char *buf, int n, CMML_Head    *head);
00822 
00833 int cmml_head_pretty_snprint    (char *buf, int n, CMML_Head    *head);
00834 
00845 int cmml_clip_snprint         (char *buf, int n, CMML_Clip  *clip);
00846 
00857 int cmml_clip_pretty_snprint  (char *buf, int n, CMML_Clip  *clip);
00858 
00870 int cmml_error_snprint (char *buf, int n, CMML_Error *error, CMML *cmml);
00871 
00872 
00873 /* ----------------------------------------------- *
00874  * helper functions for list handling: cmml_list.c *
00875  * ----------------------------------------------- */
00876 
00882 CMML_List * cmml_list_new        (void);
00883 
00891 CMML_List * cmml_list_clone      (CMML_List * list);
00892 
00901 CMML_List * cmml_list_clone_with (CMML_List * list, CMML_CloneFunc clone);
00902 
00910 CMML_List * cmml_list_tail       (CMML_List * list);
00911 
00920 CMML_List * cmml_list_prepend    (CMML_List * list, void * data);
00921 
00930 CMML_List * cmml_list_append     (CMML_List * list, void * data);
00931 
00942 CMML_List * cmml_list_add_before (CMML_List * list, void * data, 
00943                                   CMML_List * node);
00954 CMML_List * cmml_list_add_after  (CMML_List * list, void * data, 
00955                                   CMML_List * node);
00956 
00965 CMML_List * cmml_list_find       (CMML_List * list, void * data);
00966 
00975 CMML_List * cmml_list_remove     (CMML_List * list, CMML_List * node);
00976 
00984 int cmml_list_length             (CMML_List * list);
00985 
00993 int cmml_list_is_empty           (CMML_List * list);
00994 
01003 int cmml_list_is_singleton       (CMML_List * list);
01004 
01014 CMML_List * cmml_list_free_with   (CMML_List * list, 
01015                                    CMML_FreeFunc free_func);
01016 
01025 CMML_List * cmml_list_free       (CMML_List * list);
01026 
01027 
01028 /* ----------------------------------------------- *
01029  * helper functions for time handling: cmml_time.c *
01030  * ----------------------------------------------- */
01031 
01040 CMML_Time * cmml_time_new  (const char * s);
01041 
01049 CMML_Time * cmml_sec_new   (const char * s);
01050 
01058 CMML_Time * cmml_time_new_secs (double seconds);
01059 
01067 CMML_Time * cmml_utc_new   (const char * s);
01068 
01082 int cmml_time_interval_new (const char * s, 
01083                             CMML_Time ** t_start, CMML_Time ** t_end);
01084 
01096 CMML_Time *cmml_time_new_in_sec (const char * s, CMML_Time * ref, double base);
01097 
01108 CMML_Time *cmml_time_utc_to_sec (CMML_Time * t, CMML_Time * ref, double base);
01109 
01115 void        cmml_time_free (CMML_Time *t);
01116 
01124 CMML_Time * cmml_time_clone   (CMML_Time *t);
01125 
01133 double cmml_sec_parse (const char *s);
01134 
01143 CMML_UTC * cmml_utc_parse (const char * s);
01144 
01152 CMML_UTC * cmml_utc_clone (CMML_UTC *t);
01153 
01163 double     cmml_utc_diff  (CMML_UTC *t2, CMML_UTC *t1);
01164 
01175 int        cmml_npt_snprint (char * buf, int n, double seconds);
01176 
01187 int        cmml_utc_snprint (char *buf, int n, CMML_UTC *t);
01188 
01199 int        cmml_utc_pretty_snprint (char *buf, int n, CMML_UTC *t);
01200 
01201 
01202 
01203 #endif /* __CMML_H__ */