epub.h

Go to the documentation of this file.
00001 #ifndef EPUB_H
00002 #define EPUB_H 1
00003 
00004 #include <epub_shared.h>
00005 /** \struct epub is a private struct containting information about the epub file */
00006 struct epub;
00007 
00008 /** \struct eiterator is a private iterator struct */
00009 struct eiterator;
00010 struct titerator;
00011 
00012 #ifdef __cplusplus
00013 extern "C" {
00014 #endif /* C++ */
00015 
00016   /** 
00017       This function accepts an epub filename. It then parses its information and
00018       returns it as an epub struct.
00019       
00020       @param filename the name of the file to open
00021       @param debug is the debug level (0=none, 1=errors, 2=warnings, 3=info)
00022       @return epub struct with the information of the file or NULL on error
00023       
00024   */
00025   EPUB_EXPORT struct epub *epub_open(const char *filename, int debug);
00026   
00027   /**
00028      This function sets the debug level to the given level.
00029      
00030      @param filename is the name of the file to open
00031      @param debug is the debug level (0=none, 1=errors, 2=warnings, 3=info)
00032   */
00033   EPUB_EXPORT void epub_set_debug(struct epub *epub, int debug);
00034 
00035   /** 
00036       returns the file with the give filename
00037 
00038       @param epub struct of the epub file we want to read from
00039       @param filename the name of the file we want to read
00040       @param pointer to where the file data is stored
00041       @return the number of bytes read
00042   */
00043   EPUB_EXPORT int epub_get_ocf_file(struct epub *epub, const char *filename, char **data);
00044   
00045   /** 
00046       Frees the memory held by the given iterator
00047       
00048       @param it the iterator
00049   */
00050   EPUB_EXPORT void epub_free_iterator(struct eiterator *it);
00051 
00052   /** 
00053       This function closes a given epub. It also frees the epub struct.
00054       So you can use it after calling this function.
00055       
00056       @param epub the struct of the epub to close.
00057   */
00058   EPUB_EXPORT int epub_close(struct epub *epub);
00059   
00060   /** 
00061       Debugging function dumping various file information.
00062       
00063       @param epub the struct of the epub to close.
00064   */
00065   EPUB_EXPORT void epub_dump(struct epub *epub);
00066   
00067     
00068   /** 
00069       (Bad xml might cause some of it to be NULL).
00070 
00071       @param epub the struct .
00072   */
00073   EPUB_EXPORT unsigned char **epub_get_metadata(struct epub *epub, enum epub_metadata type,
00074                                                 int *size);
00075 
00076   /** 
00077       returns the file with the give filename. The file is looked
00078       for in the data directory. (Useful for getting book files). 
00079 
00080       @param epub struct of the epub file we want to read from
00081       @param filename the name of the file we want to read
00082       @param pointer to where the file data is stored
00083       @return the number of bytes read
00084   */
00085   EPUB_EXPORT int epub_get_data(struct epub *epub, const char *name, char **data);
00086 
00087   
00088   /** 
00089       Returns a book iterator of the requested type
00090       for the given epub struct.
00091       
00092       @param epub struct of the epub file
00093       @param type the iterator type
00094       @param opt other options (ignored for now)
00095       @return eiterator to the epub book
00096   */
00097   EPUB_EXPORT struct eiterator *epub_get_iterator(struct epub *epub, 
00098                                                   enum eiterator_type type, int opt);
00099 
00100   /**
00101      updates the iterator to the next element and returns a pointer 
00102      to the data. the iterator handles the freeing of the memory.
00103      
00104      @param it the iterator
00105      @return pointer to the data
00106   */
00107   EPUB_EXPORT char *epub_it_get_next(struct eiterator *it);
00108 
00109   /**
00110      Returns a pointer to the iterator's data. the iterator handles 
00111      the freeing of the memory.
00112      
00113      @param it the iterator
00114      @return pointer to the data
00115   */
00116   EPUB_EXPORT char *epub_it_get_curr(struct eiterator *it);
00117   
00118   /**
00119      Returns a pointer to the url of the iterator's current data. 
00120      the iterator handles the freeing of the memory.
00121      
00122      @param it the iterator
00123      @return pointer to the current data's url
00124   */
00125   EPUB_EXPORT char *epub_it_get_curr_url(struct eiterator *it);
00126 
00127   /** 
00128       Returns a book toc iterator of the requested type
00129       for the given epub struct.
00130       
00131       @param epub struct of the epub file
00132       @param type the iterator type
00133       @param opt other options (ignored for now)
00134       @return toc iterator to the epub book
00135   */
00136   EPUB_EXPORT struct titerator *epub_get_titerator(struct epub *epub, 
00137                                                    enum titerator_type type, int opt);
00138 
00139   
00140   /**
00141      Returns 1 if the current entry is valid and 0 otherwise. 
00142 
00143      @param tit the iterator
00144      @return 1 if the current entry is valid and 0 otherwise 
00145   */
00146   EPUB_EXPORT int epub_tit_curr_valid(struct titerator *tit);
00147   
00148   /**
00149      Returns a pointer to the depth of the toc iterator's current entry. 
00150      the iterator handles the freeing of the memory.
00151      
00152      @param tit the iterator
00153      @return pointer to the current entry's depth
00154   */
00155   EPUB_EXPORT int epub_tit_get_curr_depth(struct titerator *tit);
00156 
00157   /**
00158      Returns a pointer to the link of the toc iterator's current entry. 
00159      the iterator handles the freeing of the memory.
00160      
00161      @param tit the iterator
00162      @return the current entry's depth
00163   */
00164   EPUB_EXPORT char *epub_tit_get_curr_link(struct titerator *tit);
00165 
00166   /**
00167      Returns a pointer to the label of the toc iterator's current entry. 
00168      the iterator handles the freeing of the memory.
00169      
00170      @param tit the iterator
00171      @return pointer to the current entry's lable
00172   */
00173   EPUB_EXPORT char *epub_tit_get_curr_label(struct titerator *tit);
00174 
00175   /** 
00176       Frees the memory held by the given iterator
00177       
00178       @param tit the iterator
00179   */
00180   EPUB_EXPORT void epub_free_titerator(struct titerator *tit);
00181   
00182   /**
00183      updates the iterator to the next element.
00184      
00185      @param tit the iterator
00186      @return 1 on success and 0 otherwise
00187   */
00188   EPUB_EXPORT int epub_tit_next(struct titerator *tit);
00189 
00190   /**
00191      Cleans up after the library. Call this when you are done with the library. 
00192   */
00193   EPUB_EXPORT void epub_cleanup();
00194 
00195 #ifdef __cplusplus
00196 }
00197 #endif /* C++ */
00198 
00199 #endif /* EPUB_H */