EBOOK-TOOLS: src/libepub/epub.h Source File

# 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 */