Document Level Functions

The fz_document structure contains a list of functions used to implement the document level calls:

$\begin{lstlisting} typedef struct fz_document_s { int refs; fz_document_drop_f... ...p_metadata; int did_layout; int is_reflowable; } fz_document; \end{lstlisting}$

Implementations must fill in the drop_document field, with a pointer to a function called to free any resources help by the document when the reference count drops to 0. In the unlikely event that your implementation has no resources, this field can be left NULL.

$\begin{lstlisting} /* fz_document_drop_fn: Called when the reference count for ... ... void (fz_document_drop_fn)(fz_context *ctx, fz_document *doc); \end{lstlisting}$

If your document handler is capable of handling password protected documents, then you must fill in the needs_password field with a pointer to a function called to enquire whether a given document needs a password:

$\begin{lstlisting} /* fz_document_needs_password_fn: Type for a function to be ... ...document_needs_password_fn)(fz_context *ctx, fz_document *doc); \end{lstlisting}$

If your document handler is capable of handling password protected documents, then you must fill in the authenticate_password field with a pointer to a function called to attempt to authenticate a password:

$\begin{lstlisting} /* fz_document_authenticate_password_fn: Type for a function... ...d_fn)(fz_context *ctx, fz_document *doc, const char *password); \end{lstlisting}$

Certain document types encode permissions within them to say what users are allowed to do with them (printing, extracting etc). If your document handler's format has this concept, then you must fill in the has_permission field with a pointer to a function called to attempt to query such permissions:

$\begin{lstlisting} /* fz_document_has_permission_fn: Type for a function to be ... ...)(fz_context *ctx, fz_document *doc, fz_permission permission); \end{lstlisting}$

Certain document types can optionally include outline (table of contents) information within them. If your document handler's format has this concept, then you must fill in the load_outline field with a pointer to a function called to attempt to load such information if it is there:

$\begin{lstlisting} /* fz_document_load_outline_fn: Type for a function to be ca... ...z_document_load_outline_fn)(fz_context *ctx, fz_document *doc); \end{lstlisting}$

If your document format requires a layout pass before it can be viewed, then you must fill in the layout field with a pointer to a function called to perform such a layout:

$\begin{lstlisting} /* fz_document_layout_fn: Type for a function to be called t... ...fz_context *ctx, fz_document *doc, float w, float h, float em); \end{lstlisting}$

If your document requires a layout pass, you should provide functions to both make and resolve bookmarks to enable reader positions to be kept over layout changes. Accordingly the make_bookmark and lookup_bookmark fields should be filled out:

$\begin{lstlisting} /* fz_document_make_bookmark_fn: Type for a function to make... ...kmark_fn)(fz_context *ctx, fz_document *doc, fz_bookmark mark); \end{lstlisting}$

Some document formats can encode internal links that point to another page in the document. If your document supports this concept, then you must fill in the resolve_link field with a pointer to a function called to resolve a textual link to a page number, and location on that page:

$\begin{lstlisting} /* fz_document_resolve_link_fn: Type for a function to be ca... ...*ctx, fz_document *doc, const char *uri, float *xp, float *yp); \end{lstlisting}$

All document formats must fill in the count_pages field with a pointer to a function called to return the number of pages in a document:

$\begin{lstlisting} /* fz_document_count_pages_fn: Type for a function to be cal... ...fz_document_count_pages_fn)(fz_context *ctx, fz_document *doc); \end{lstlisting}$

Different document formats encode different types of metadata. We therefore have an extensible function to allow such data to be queried. If your document handler wishes to support this, then the lookup_metadata field must be filled in with a pointer to a function to perform such lookups:

$\begin{lstlisting} /* fz_document_lookup_metadata_fn: Type for a function to qu... ... *ctx, fz_document *doc, const char *key, char *buf, int size); \end{lstlisting}$

All document formats must fill in the load_page field with a pointer to a function called to return a reference to a fz_page structure:

$\begin{lstlisting} /* fz_document_load_page_fn: Type for a function to load a g... ...t_load_page_fn)(fz_context *ctx, fz_document *doc, int number); \end{lstlisting}$

To create a fz_page use the fz_new_page macro. For a document of type foo, typically a foo_page structure would be defined as below:

$\begin{lstlisting} typedef struct { fz_page super; <foo specific fields> } foo_page; \end{lstlisting}$

This would then be created using a call to fz_new_page, such as:

$\begin{lstlisting} foo_page *foo = fz_new_page(ctx, foo_page); \end{lstlisting}$

This returns an empty document structure with super populated with default values, and the foo specific fields initialized to 0. The document handler implementation then needs to fill in the page level functions.