diff options
| -rw-r--r-- | fitz/fitz.h | 101 |
1 files changed, 77 insertions, 24 deletions
diff --git a/fitz/fitz.h b/fitz/fitz.h index fc4bd570..b55ff445 100644 --- a/fitz/fitz.h +++ b/fitz/fitz.h @@ -257,10 +257,10 @@ struct fz_context_s context. locks: Supply a set of locks and functions to lock/unlock - them, intended for multi-threaded environment. Set to NULL - when using MuPDF in a single-threaded environment. The context - will keep the locks pointer, so it must not be modified or - freed during the lifetime of the context. + them, intended for multi-threaded applications. Set to NULL + when using MuPDF in a single-threaded applications. The + context will keep the locks pointer, so it must not be + modified or freed during the lifetime of the context. max_store: Maximum size in bytes of the resource store, before it will start evicting cached resources such as fonts and @@ -271,6 +271,21 @@ struct fz_context_s */ fz_context *fz_new_context(fz_alloc_context *alloc, fz_locks_context *locks, unsigned int max_store); +/* + fz_clone_context: Make a clone of an existing context. + + This function is meant to be used in multi-threaded + applications where each thread requires its own context, yet + parts of the global state, for example caching, is shared. + + ctx: Context obtained from fz_new_context to make a copy of. + ctx must have had locks and lock/functions setup when created. + The two contexts will share the memory allocator, resource + store, locks and lock/unlock functions. They will each have + their own exception stacks though. + + Does not throw exception, but may return NULL. +*/ fz_context *fz_clone_context(fz_context *ctx); fz_context *fz_clone_context_internal(fz_context *ctx); @@ -288,24 +303,26 @@ void fz_free_context(fz_context *ctx); void fz_new_aa_context(fz_context *ctx); void fz_free_aa_context(fz_context *ctx); -/* Locking functions - * - * MuPDF is kept deliberately free of any knowledge of particular threading - * systems. As such, in order for safe multi-threaded operation, we rely on - * callbacks to client provided functions. - * - * A client is expected to provide FZ_LOCK_MAX mutexes, and a function to - * lock/unlock each of them. These may be recursive mutexes, but do not have - * to be. - * - * If a client does not intend to use multiple threads, then it may pass - * NULL instead of the address of a lock structure. - * - * In order to avoid deadlocks, we have 1 simple rules internally as to how - * we use locks: We can never take lock n when we already hold any lock i, - * where 0 <= i <= n. In order to verify this, we have some debugging code - * built in, that is enabled by defining FITZ_DEBUG_LOCKING. - */ +/* + Locking functions + + MuPDF is kept deliberately free of any knowledge of particular + threading systems. As such, in order for safe multi-threaded + operation, we rely on callbacks to client provided functions. + + A client is expected to provide FZ_LOCK_MAX mutexes, and a + function to lock/unlock each of them. These may be recursive + mutexes, but do not have to be. + + If a client does not intend to use multiple threads, then it + may pass NULL instead of the address of a lock structure. + + In order to avoid deadlocks, we have 1 simple rules internally + as to how we use locks: We can never take lock n when we + already hold any lock i, where 0 <= i <= n. In order to verify + this, we have some debugging code built in, that is enabled by + defining FITZ_DEBUG_LOCKING. +*/ #if defined(MEMENTO) || defined(DEBUG) #define FITZ_DEBUG_LOCKING @@ -1800,6 +1817,23 @@ void fz_free_link_dest(fz_context *ctx, fz_link_dest *dest); typedef struct fz_outline_s fz_outline; +/* + fz_outline represent one item in a document's hierarchical + outline (also know as table of contents). + + title: Title of outline item using UTF-8 encoding. May be NULL + if the outline item has no text string. + + dest: Destination in the document to be displayed when this + outline item is activated. May be FZ_LINK_NONE if the outline + item does not have a destination. + + next: The next outline item at the same level as this outline + item. May be NULL if not more outline items exist at this level. + + down: The outline items immediate children in the hierarchy. + May be NULL if no children exist. +*/ struct fz_outline_s { char *title; @@ -1854,9 +1888,28 @@ fz_document *fz_open_document(fz_context *ctx, char *filename); */ void fz_close_document(fz_document *doc); +/* + fz_needs_password: Checks for encrypted document. + + Encrypted documents that require only an empty password are + treated as if they were not encrypted, thus requiring no + password authentication. +*/ int fz_needs_password(fz_document *doc); + +/* + fz_authenticate_password: Test if password can decrypt a + document. + + password: The password string to be checked. It is assumed + that is in a suitable text encoding, as some document + specifications do not specify any particular text encoding. +*/ int fz_authenticate_password(fz_document *doc, char *password); +/* + fz_load_outline: Load the hierarchical document outline. +*/ fz_outline *fz_load_outline(fz_document *doc); /* @@ -1902,8 +1955,8 @@ fz_rect fz_bound_page(fz_document *doc, fz_page *page); Set to fz_identity if no transformation is desired. cookie: Communication mechanism between caller and library - rendering the page. Intended for multi-threaded environments, - while single-threaded environments set cookie to NULL. The + rendering the page. Intended for multi-threaded applications, + while single-threaded applications set cookie to NULL. The caller may abort an ongoing rendering of a page. Cookie also communicates progress information back to the caller. The fields inside cookie are continually updated while the page is |