MuPDF X.Y.Z

fitz/document.h

Index

typedef

struct

enum

macro

function

Document

typedef fz_bookmark

typedef intptr_t fz_bookmark

enum fz_box_type

enum fz_box_type
{
        FZ_MEDIA_BOX,
        FZ_CROP_BOX,
        FZ_BLEED_BOX,
        FZ_TRIM_BOX,
        FZ_ART_BOX,
        FZ_UNKNOWN_BOX
}

function fz_box_type_from_string

fz_box_type
fz_box_type_from_string (
        const char *name
)

function fz_string_from_box_type

const char *
fz_string_from_box_type (
        fz_box_type box
)

enum fz_layout_const

enum fz_layout_const
{
        /* 6in at 4:3 */
        FZ_LAYOUT_KINDLE_W = 260,
        FZ_LAYOUT_KINDLE_H = 346,
        FZ_LAYOUT_KINDLE_EM = 9,

        /* 4.25 x 6.87 in */
        FZ_LAYOUT_US_POCKET_W = 306,
        FZ_LAYOUT_US_POCKET_H = 495,
        FZ_LAYOUT_US_POCKET_EM = 10,

        /* 5.5 x 8.5 in */
        FZ_LAYOUT_US_TRADE_W = 396,
        FZ_LAYOUT_US_TRADE_H = 612,
        FZ_LAYOUT_US_TRADE_EM = 11,

        /* 110 x 178 mm */
        FZ_LAYOUT_UK_A_FORMAT_W = 312,
        FZ_LAYOUT_UK_A_FORMAT_H = 504,
        FZ_LAYOUT_UK_A_FORMAT_EM = 10,

        /* 129 x 198 mm */
        FZ_LAYOUT_UK_B_FORMAT_W = 366,
        FZ_LAYOUT_UK_B_FORMAT_H = 561,
        FZ_LAYOUT_UK_B_FORMAT_EM = 10,

        /* 135 x 216 mm */
        FZ_LAYOUT_UK_C_FORMAT_W = 382,
        FZ_LAYOUT_UK_C_FORMAT_H = 612,
        FZ_LAYOUT_UK_C_FORMAT_EM = 11,

        /* 148 x 210 mm */
        FZ_LAYOUT_A5_W = 420,
        FZ_LAYOUT_A5_H = 595,
        FZ_LAYOUT_A5_EM = 11,

        /* Default to A5 */
        FZ_DEFAULT_LAYOUT_W = FZ_LAYOUT_A5_W,
        FZ_DEFAULT_LAYOUT_H = FZ_LAYOUT_A5_H,
        FZ_DEFAULT_LAYOUT_EM = FZ_LAYOUT_A5_EM,
}

enum fz_layout_style_const

enum fz_layout_style_const
{
        FZ_STYLE_NEEDS_DEFAULT = -1,
        FZ_STYLE_NEEDS_UPDATE = 0,
        FZ_STYLE_APPLIED = 1,
}

enum fz_layout_update_const

enum fz_layout_update_const
{
        FZ_LAYOUT_NEEDS_UPDATE = 0,
        FZ_LAYOUT_APPLIED = 1,
}

enum fz_permission

enum fz_permission
{
        FZ_PERMISSION_PRINT = 'p',
        FZ_PERMISSION_COPY = 'c',
        FZ_PERMISSION_EDIT = 'e',
        FZ_PERMISSION_ANNOTATE = 'n',
        FZ_PERMISSION_FORM = 'f',
        FZ_PERMISSION_ACCESSIBILITY = 'y',
        FZ_PERMISSION_ASSEMBLE = 'a',
        FZ_PERMISSION_PRINT_HQ = 'h',
}

typedef fz_document_drop_fn

typedef void (fz_document_drop_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called when the reference count for the fz_document drops to 0. The implementation should release any resources held by the document. The actual document pointer will be freed by the caller.

typedef fz_document_needs_password_fn

typedef int (fz_document_needs_password_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called to enquire whether the document needs a password or not. See fz_needs_password for more information.

typedef fz_document_authenticate_password_fn

typedef int (fz_document_authenticate_password_fn)(fz_context *ctx, fz_document *doc, const char *password)

Type for a function to be called to attempt to authenticate a password. See fz_authenticate_password for more information.

typedef fz_document_has_permission_fn

typedef int (fz_document_has_permission_fn)(fz_context *ctx, fz_document *doc, fz_permission permission)

Type for a function to be called to see if a document grants a certain permission. See fz_document_has_permission for more information.

typedef fz_document_load_outline_fn

typedef fz_outline *(fz_document_load_outline_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called to load the outlines for a document. See fz_document_load_outline for more information.

typedef fz_document_outline_iterator_fn

typedef fz_outline_iterator *(fz_document_outline_iterator_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called to obtain an outline iterator for a document. See fz_document_outline_iterator for more information.

typedef fz_document_style_fn

typedef void (fz_document_style_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called to to apply stylesheets to a document. See fz_style_document for more information.

typedef fz_document_layout_fn

typedef void (fz_document_layout_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called to lay out a document. See fz_layout_document for more information.

typedef fz_link_dest (fz_document_resolve_link_dest_fn)(fz_context *ctx, fz_document *doc, const char *uri)

Type for a function to be called to resolve an internal link to a location (chapter/page number tuple). See fz_resolve_link_dest for more information.

typedef char * (fz_document_format_link_uri_fn)(fz_context *ctx, fz_document *doc, fz_link_dest dest)

Type for a function to be called to create an internal link to a destination (chapter/page/x/y/w/h/zoom/type tuple). See fz_resolve_link_dest for more information.

typedef fz_document_count_chapters_fn

typedef int (fz_document_count_chapters_fn)(fz_context *ctx, fz_document *doc)

Type for a function to be called to count the number of chapters in a document. See fz_count_chapters for more information.

typedef fz_document_count_pages_fn

typedef int (fz_document_count_pages_fn)(fz_context *ctx, fz_document *doc, int chapter)

Type for a function to be called to count the number of pages in a document. See fz_count_pages for more information.

typedef fz_document_load_page_fn

typedef fz_page *(fz_document_load_page_fn)(fz_context *ctx, fz_document *doc, int chapter, int page)

Type for a function to load a given page from a document. See fz_load_page for more information.

typedef fz_document_page_label_fn

typedef void (fz_document_page_label_fn)(fz_context *ctx, fz_document *doc, int chapter, int page, char *buf, size_t size)

Type for a function to get the page label of a page in the document. See fz_page_label for more information.

typedef fz_document_lookup_metadata_fn

typedef int (fz_document_lookup_metadata_fn)(fz_context *ctx, fz_document *doc, const char *key, char *buf, size_t size)

Type for a function to query a document’s metadata. See fz_lookup_metadata for more information.

typedef fz_document_set_metadata_fn

typedef void (fz_document_set_metadata_fn)(fz_context *ctx, fz_document *doc, const char *key, const char *value)

Type for a function to set a document’s metadata. See fz_set_metadata for more information.

typedef fz_document_output_intent_fn

typedef fz_colorspace *(fz_document_output_intent_fn)(fz_context *ctx, fz_document *doc)

Return output intent color space if it exists

typedef fz_document_output_accelerator_fn

typedef void (fz_document_output_accelerator_fn)(fz_context *ctx, fz_document *doc, fz_output *out)

Write document accelerator data

typedef fz_document_run_structure_fn

typedef void (fz_document_run_structure_fn)(fz_context *ctx, fz_document *doc, fz_device *dev, fz_cookie *cookie)

Send document structure to device

typedef fz_document_as_pdf_fn

typedef fz_document *(fz_document_as_pdf_fn)(fz_context *ctx, fz_document *doc)

Get a handle to this document as PDF.

Returns a borrowed handle.

typedef fz_document_make_bookmark_fn

typedef fz_bookmark (fz_document_make_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_location loc)

Type for a function to make a bookmark. See fz_make_bookmark for more information.

typedef fz_document_lookup_bookmark_fn

typedef fz_location (fz_document_lookup_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_bookmark mark)

Type for a function to lookup a bookmark. See fz_lookup_bookmark for more information.

typedef fz_page_drop_page_fn

typedef void (fz_page_drop_page_fn)(fz_context *ctx, fz_page *page)

Type for a function to release all the resources held by a page. Called automatically when the reference count for that page reaches zero.

typedef fz_page_bound_page_fn

typedef fz_rect (fz_page_bound_page_fn)(fz_context *ctx, fz_page *page, fz_box_type box)

Type for a function to return the bounding box of a page. See fz_bound_page for more information.

typedef fz_page_run_page_fn

typedef void (fz_page_run_page_fn)(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie)

Type for a function to run the contents of a page. See fz_run_page_contents for more information.

typedef fz_page_load_links_fn

typedef fz_link *(fz_page_load_links_fn)(fz_context *ctx, fz_page *page)

Type for a function to load the links from a page. See fz_load_links for more information.

typedef fz_page_page_presentation_fn

typedef fz_transition *(fz_page_page_presentation_fn)(fz_context *ctx, fz_page *page, fz_transition *transition, float *duration)

Type for a function to obtain the details of how this page should be presented when in presentation mode. See fz_page_presentation for more information.

typedef fz_page_control_separation_fn

typedef void (fz_page_control_separation_fn)(fz_context *ctx, fz_page *page, int separation, int disable)

Type for a function to enable/ disable separations on a page. See fz_control_separation for more information.

typedef fz_page_separation_disabled_fn

typedef int (fz_page_separation_disabled_fn)(fz_context *ctx, fz_page *page, int separation)

Type for a function to detect whether a given separation is enabled or disabled on a page. See FZ_SEPARATION_DISABLED for more information.

typedef fz_page_separations_fn

typedef fz_separations *(fz_page_separations_fn)(fz_context *ctx, fz_page *page)

Type for a function to retrieve details of separations on a page. See fz_get_separations for more information.

typedef fz_page_uses_overprint_fn

typedef int (fz_page_uses_overprint_fn)(fz_context *ctx, fz_page *page)

Type for a function to retrieve whether or not a given page uses overprint.

typedef fz_page_create_link_fn

typedef fz_link *(fz_page_create_link_fn)(fz_context *ctx, fz_page *page, fz_rect bbox, const char *uri)

Type for a function to create a link on a page.

typedef fz_page_delete_link_fn

typedef void (fz_page_delete_link_fn)(fz_context *ctx, fz_page *page, fz_link *link)

Type for a function to delete a link on a page.

typedef fz_document_open_fn

typedef fz_document *(fz_document_open_fn)(fz_context *ctx, const fz_document_handler *handler, fz_stream *stream, fz_stream *accel, fz_archive *dir, void *recognize_state)

Function type to open a document from a file.

handler:
the document handler in use.
stream:
fz_stream to read document data from. Must be seekable for formats that require it.
accel:
fz_stream to read accelerator data from. May be NULL. May be ignored.
dir:
‘Directory context’ in which the document is loaded; associated content from (like images for an html stream will be loaded from this). Maybe NULL. May be ignored.
recognize_state:
NULL, or a state pointer passed back from the call to recognise_content_fn. Ownership does not pass in. The caller remains responsible for freeing state.

Pointer to opened document. Throws exception in case of error.

typedef fz_document_recognize_fn

typedef int (fz_document_recognize_fn)(fz_context *ctx, const fz_document_handler *handler, const char *magic)

Recognize a document type from a magic string.

handler:
the handler in use.
magic:
string to recognise - typically a filename or mime type.

Returns a number between 0 (not recognized) and 100 (fully recognized) based on how certain the recognizer is that this is of the required type.

typedef fz_document_recognize_state_free_fn

typedef void (fz_document_recognize_state_free_fn)(fz_context *ctx, void *state)

typedef fz_document_recognize_content_fn

typedef int (fz_document_recognize_content_fn)(fz_context *ctx, const fz_document_handler *handler, fz_stream *stream, fz_archive *dir, void **recognize_state, fz_document_recognize_state_free_fn **free_recognize_state)

Recognize a document type from stream contents.

handler:
the handler in use.
stream:
stream contents to recognise (may be NULL if document is a directory).
dir:
directory context from which stream is loaded.
recognize_state:
pointer to retrieve opaque state that may be used by the open routine, or NULL.
free_recognize_state:
pointer to retrieve a function pointer to free the opaque state, or NULL.

Note: state and free_state should either both be NULL or both be non-NULL!

Returns a number between 0 (not recognized) and 100 (fully recognized) based on how certain the recognizer is that this is of the required type.

typedef fz_document_handler_fin_fn

typedef void (fz_document_handler_fin_fn)(fz_context *ctx, const fz_document_handler *handler)

Finalise a document handler.

This will be called on shutdown for a document handler to release resources. This should cope with being called with NULL.

opaque:
The value previously returned by the init call.

typedef fz_process_opened_page_fn

typedef void *(fz_process_opened_page_fn)(fz_context *ctx, fz_page *page, void *state)

Type for a function to be called when processing an already opened page. See fz_process_opened_pages.

function fz_register_document_handler

void
fz_register_document_handler (
        fz_context *ctx,
        const fz_document_handler *handler
)

Register a handler for a document type.

handler:
The handler to register. This must live on for the duration of the use of this handler. It will be passed back to the handler for calls so the caller can use it to retrieve state.

function fz_register_document_handlers

void
fz_register_document_handlers (
        fz_context *ctx
)

Register handlers for all the standard document types supported in this build.

function fz_recognize_document

const fz_document_handler *
fz_recognize_document (
        fz_context *ctx,
        const char *magic
)

Given a magic find a document handler that can handle a document of this type.

magic:
Can be a filename extension (including initial period) or a mimetype.

function fz_recognize_document_content

const fz_document_handler *
fz_recognize_document_content (
        fz_context *ctx,
        const char *filename
)

Given a filename find a document handler that can handle a document of this type.

filename:
The filename of the document. This will be opened and sampled to check data.

function fz_recognize_document_stream_content

const fz_document_handler *
fz_recognize_document_stream_content (
        fz_context *ctx,
        fz_stream *stream,
        const char *magic
)

Given a magic find a document handler that can handle a document of this type.

stream:
the file stream to sample. May be NULL if the document is a directory.
magic:
Can be a filename extension (including initial period) or a mimetype.

function fz_recognize_document_stream_and_dir_content

const fz_document_handler *
fz_recognize_document_stream_and_dir_content (
        fz_context *ctx,
        fz_stream *stream,
        fz_archive *dir,
        const char *magic
)

Given a magic find a document handler that can handle a document of this type.

stream:
the file stream to sample. May be NULL if the document is a directory.
dir:
an fz_archive representing the directory from which the stream was opened (or NULL).
magic:
Can be a filename extension (including initial period) or a mimetype.

function fz_open_document

fz_document *
fz_open_document (
        fz_context *ctx,
        const char *filename
)

Open a document file and read its basic structure so pages and objects can be located. MuPDF will try to repair broken documents (without actually changing the file contents).

The returned fz_document is used when calling most other document related functions.

filename:
a path to a file as it would be given to open(2).

function fz_open_accelerated_document

fz_document *
fz_open_accelerated_document (
        fz_context *ctx,
        const char *filename,
        const char *accel
)

Open a document file and read its basic structure so pages and objects can be located. MuPDF will try to repair broken documents (without actually changing the file contents).

The returned fz_document is used when calling most other document related functions.

filename:
a path to a file as it would be given to open(2).

function fz_open_accelerated_document_with_dir

fz_document *
fz_open_accelerated_document_with_dir (
        fz_context *ctx,
        const char *filename,
        const char *accel,
        fz_archive *dir
)

Like fz_open_accelerated_document, but also takes an archive in which external resources may be looked for.

A reference will be taken to the archive.

function fz_open_document_with_stream

fz_document *
fz_open_document_with_stream (
        fz_context *ctx,
        const char *magic,
        fz_stream *stream
)

Open a document using the specified stream object rather than opening a file on disk.

magic:
a string used to detect document type; either a file name or mime-type.
stream:
a stream representing the contents of the document file.

NOTE: The caller retains ownership of ‘stream’ - the document will take its own reference if required.

function fz_open_document_with_stream_and_dir

fz_document *
fz_open_document_with_stream_and_dir (
        fz_context *ctx,
        const char *magic,
        fz_stream *stream,
        fz_archive *dir
)

Open a document using the specified stream object rather than opening a file on disk.

magic:
a string used to detect document type; either a file name or mime-type.
stream:
a stream representing the contents of the document file.
dir:
a ‘directory context’ for those filetypes that need it.

NOTE: The caller retains ownership of ‘stream’ and ‘dir’ - the document will take its own references if required.

function fz_open_document_with_buffer

fz_document *
fz_open_document_with_buffer (
        fz_context *ctx,
        const char *magic,
        fz_buffer *buffer
)

Open a document using a buffer rather than opening a file on disk.

function fz_open_accelerated_document_with_stream

fz_document *
fz_open_accelerated_document_with_stream (
        fz_context *ctx,
        const char *magic,
        fz_stream *stream,
        fz_stream *accel
)

Open a document using the specified stream object rather than opening a file on disk.

magic:
a string used to detect document type; either a file name or mime-type.
stream:
a stream of the document contents.
accel:
NULL, or a stream of the ‘accelerator’ contents for this document.

NOTE: The caller retains ownership of ‘stream’ and ‘accel’ - the document will take its own references if required.

function fz_open_accelerated_document_with_stream_and_dir

fz_document *
fz_open_accelerated_document_with_stream_and_dir (
        fz_context *ctx,
        const char *magic,
        fz_stream *stream,
        fz_stream *accel,
        fz_archive *dir
)

Open a document using the specified stream object rather than opening a file on disk.

magic:
a string used to detect document type; either a file name or mime-type.
stream:
a stream of the document contents.
accel:
NULL, or a stream of the ‘accelerator’ contents for this document.
dir:
NULL, or the ‘directory context’ for the stream contents.

NOTE: The caller retains ownership of ‘stream’, ‘accel’ and ‘dir’ - the document will take its own references if required.

function fz_document_supports_accelerator

int
fz_document_supports_accelerator (
        fz_context *ctx,
        fz_document *doc
)

Query if the document supports the saving of accelerator data.

function fz_save_accelerator

void
fz_save_accelerator (
        fz_context *ctx,
        fz_document *doc,
        const char *accel
)

Save accelerator data for the document to a given file.

function fz_output_accelerator

void
fz_output_accelerator (
        fz_context *ctx,
        fz_document *doc,
        fz_output *accel
)

Output accelerator data for the document to a given output stream.

function fz_new_document_of_size

void *
fz_new_document_of_size (
        fz_context *ctx,
        int size
)

New documents are typically created by calls like foo_new_document(fz_context *ctx, …). These work by deriving a new document type from fz_document, for instance: typedef struct { fz_document base; …extras… } foo_document; These are allocated by calling fz_new_derived_document(ctx, foo_document)

macro fz_new_derived_document

#define fz_new_derived_document(C,M)

function fz_keep_document

fz_document *
fz_keep_document (
        fz_context *ctx,
        fz_document *doc
)

Increment the document reference count. The same pointer is returned.

Never throws exceptions.

function fz_drop_document

void
fz_drop_document (
        fz_context *ctx,
        fz_document *doc
)

Decrement the document reference count. When the reference count reaches 0, the document and all it’s references are freed.

Never throws exceptions.

function fz_needs_password

int
fz_needs_password (
        fz_context *ctx,
        fz_document *doc
)

Check if a document is encrypted with a non-blank password.

function fz_authenticate_password

int
fz_authenticate_password (
        fz_context *ctx,
        fz_document *doc,
        const char *password
)

Test if the given password can decrypt the document.

password:
The password string to be checked. Some document specifications do not specify any particular text encoding, so neither do we.

Returns 0 for failure to authenticate, non-zero for success.

For PDF documents, further information can be given by examining the bits in the return code.

Bit 0 => No password required
Bit 1 => User password authenticated
Bit 2 => Owner password authenticated

function fz_load_outline

fz_outline *
fz_load_outline (
        fz_context *ctx,
        fz_document *doc
)

Load the hierarchical document outline.

Should be freed by fz_drop_outline.

function fz_new_outline_iterator

fz_outline_iterator *
fz_new_outline_iterator (
        fz_context *ctx,
        fz_document *doc
)

Get an iterator for the document outline.

Should be freed by fz_drop_outline_iterator.

function fz_is_document_reflowable

int
fz_is_document_reflowable (
        fz_context *ctx,
        fz_document *doc
)

Is the document reflowable.

Returns 1 to indicate reflowable documents, otherwise 0.

function fz_style_document

void
fz_style_document (
        fz_context *ctx,
        fz_document *doc,
        int publisher_css,
        const char *user_css
)

Style reflowable document types.

publisher_css:
Whether to respect the publisher’s styles or not. user_css:
Custom stylesheet to apply.

function fz_layout_document

void
fz_layout_document (
        fz_context *ctx,
        fz_document *doc,
        float w,
        float h,
        float em
)

Layout reflowable document types.

w, h:
Page size in points. em:
Default font size in points.

function fz_make_bookmark

fz_bookmark
fz_make_bookmark (
        fz_context *ctx,
        fz_document *doc,
        fz_location loc
)

Create a bookmark for the given page, which can be used to find the same location after the document has been laid out with different parameters.

function fz_lookup_bookmark

fz_location
fz_lookup_bookmark (
        fz_context *ctx,
        fz_document *doc,
        fz_bookmark mark
)

Find a bookmark and return its page number.

function fz_count_pages

int
fz_count_pages (
        fz_context *ctx,
        fz_document *doc
)

Return the number of pages in document

May return 0 for documents with no pages.

fz_link_dest
fz_resolve_link_dest (
        fz_context *ctx,
        fz_document *doc,
        const char *uri
)

Resolve an internal link to a page number, location, and possible viewing parameters.

Returns location (-1,-1) if the URI cannot be resolved.

char *
fz_format_link_uri (
        fz_context *ctx,
        fz_document *doc,
        fz_link_dest dest
)

Format an internal link to a page number, location, and possible viewing parameters, suitable for use with fz_create_link.

Returns a newly allocated string that the caller must free.

fz_location
fz_resolve_link (
        fz_context *ctx,
        fz_document *doc,
        const char *uri,
        float *xp,
        float *yp
)

Resolve an internal link to a page number.

xp, yp:
Pointer to store coordinate of destination on the page.

Returns (-1,-1) if the URI cannot be resolved.

function fz_run_document_structure

void
fz_run_document_structure (
        fz_context *ctx,
        fz_document *doc,
        fz_device *dev,
        fz_cookie *cookie
)

Run the document structure through a device.

doc:
Document in question.
dev:
Device obtained from fz_new_*_device.
cookie:
Communication mechanism between caller and library. 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 rendering.

function fz_last_page

fz_location
fz_last_page (
        fz_context *ctx,
        fz_document *doc
)

Function to get the location for the last page in the document. Using this can be far more efficient in some cases than calling fz_count_pages and using the page number.

function fz_next_page

fz_location
fz_next_page (
        fz_context *ctx,
        fz_document *doc,
        fz_location loc
)

Function to get the location of the next page (allowing for the end of chapters etc). If at the end of the document, returns the current location.

function fz_previous_page

fz_location
fz_previous_page (
        fz_context *ctx,
        fz_document *doc,
        fz_location loc
)

Function to get the location of the previous page (allowing for the end of chapters etc). If already at the start of the document, returns the current page.

function fz_clamp_location

fz_location
fz_clamp_location (
        fz_context *ctx,
        fz_document *doc,
        fz_location loc
)

Clamps a location into valid chapter/page range. (First clamps the chapter into range, then the page into range).

function fz_location_from_page_number

fz_location
fz_location_from_page_number (
        fz_context *ctx,
        fz_document *doc,
        int number
)

Converts from page number to chapter+page. This may cause many chapters to be laid out in order to calculate the number of pages within those chapters.

function fz_page_number_from_location

int
fz_page_number_from_location (
        fz_context *ctx,
        fz_document *doc,
        fz_location loc
)

Converts from chapter+page to page number. This may cause many chapters to be laid out in order to calculate the number of pages within those chapters.

function fz_load_page

fz_page *
fz_load_page (
        fz_context *ctx,
        fz_document *doc,
        int number
)

Load a given page number from a document. This may be much less efficient than loading by location (chapter+page) for some document types.

function fz_count_chapters

int
fz_count_chapters (
        fz_context *ctx,
        fz_document *doc
)

Return the number of chapters in the document. At least 1.

function fz_count_chapter_pages

int
fz_count_chapter_pages (
        fz_context *ctx,
        fz_document *doc,
        int chapter
)

Return the number of pages in a chapter. May return 0.

function fz_load_chapter_page

fz_page *
fz_load_chapter_page (
        fz_context *ctx,
        fz_document *doc,
        int chapter,
        int page
)

Load a page.

After fz_load_page is it possible to retrieve the size of the page using fz_bound_page, or to render the page using fz_run_page_*. Free the page by calling fz_drop_page.

chapter:
chapter number, 0 is the first chapter of the document. number:
page number, 0 is the first page of the chapter. 
fz_link *
fz_load_links (
        fz_context *ctx,
        fz_page *page
)

Load the list of links for a page.

Returns a linked list of all the links on the page, each with its clickable region and link destination. Each link is reference counted so drop and free the list of links by calling fz_drop_link on the pointer return from fz_load_links.

page:
Page obtained from fz_load_page.

function fz_new_page_of_size

fz_page *
fz_new_page_of_size (
        fz_context *ctx,
        int size,
        fz_document *doc
)

Different document types will be implemented by deriving from fz_page. This macro allocates such derived structures, and initialises the base sections.

macro fz_new_derived_page

#define fz_new_derived_page(CTX,TYPE,DOC)

function fz_bound_page

fz_rect
fz_bound_page (
        fz_context *ctx,
        fz_page *page
)

Determine the size of a page at 72 dpi.

function fz_bound_page_box

fz_rect
fz_bound_page_box (
        fz_context *ctx,
        fz_page *page,
        fz_box_type box
)

function fz_run_page

void
fz_run_page (
        fz_context *ctx,
        fz_page *page,
        fz_device *dev,
        fz_matrix transform,
        fz_cookie *cookie
)

Run a page through a device.

page:
Page obtained from fz_load_page.
dev:
Device obtained from fz_new_*_device.
transform:
Transform to apply to page. May include for example scaling and rotation, see fz_scale, fz_rotate and fz_concat. Set to fz_identity if no transformation is desired.
cookie:
Communication mechanism between caller and library 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 rendering.

function fz_run_page_contents

void
fz_run_page_contents (
        fz_context *ctx,
        fz_page *page,
        fz_device *dev,
        fz_matrix transform,
        fz_cookie *cookie
)

Run a page through a device. Just the main page content, without the annotations, if any.

page:
Page obtained from fz_load_page.
dev:
Device obtained from fz_new_*_device.
transform:
Transform to apply to page. May include for example scaling and rotation, see fz_scale, fz_rotate and fz_concat. Set to fz_identity if no transformation is desired.
cookie:
Communication mechanism between caller and library 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 rendering.

function fz_run_page_annots

void
fz_run_page_annots (
        fz_context *ctx,
        fz_page *page,
        fz_device *dev,
        fz_matrix transform,
        fz_cookie *cookie
)

Run the annotations on a page through a device.

function fz_run_page_widgets

void
fz_run_page_widgets (
        fz_context *ctx,
        fz_page *page,
        fz_device *dev,
        fz_matrix transform,
        fz_cookie *cookie
)

Run the widgets on a page through a device.

function fz_keep_page

fz_page *
fz_keep_page (
        fz_context *ctx,
        fz_page *page
)

Increment the reference count for the page. Returns the same pointer.

Never throws exceptions.

function fz_drop_page

void
fz_drop_page (
        fz_context *ctx,
        fz_page *page
)

Decrements the reference count for the page. When the reference count hits 0, the page and its references are freed.

Never throws exceptions.

function fz_page_presentation

fz_transition *
fz_page_presentation (
        fz_context *ctx,
        fz_page *page,
        fz_transition *transition,
        float *duration
)

Get the presentation details for a given page.

transition:
A pointer to a transition struct to fill out.
duration:
A pointer to a place to set the page duration in seconds. Will be set to 0 if no transition is specified for the page.

Returns: a pointer to the transition structure, or NULL if there is no transition specified for the page.

function fz_page_label

const char *
fz_page_label (
        fz_context *ctx,
        fz_page *page,
        char *buf,
        int size
)

Get page label for a given page.

function fz_has_permission

int
fz_has_permission (
        fz_context *ctx,
        fz_document *doc,
        fz_permission p
)

Check permission flags on document.

function fz_lookup_metadata

int
fz_lookup_metadata (
        fz_context *ctx,
        fz_document *doc,
        const char *key,
        char *buf,
        size_t size
)

Retrieve document meta data strings.

doc:
The document to query.
key:
Which meta data key to retrieve…

Basic information: ‘format’ – Document format and version. ‘encryption’ – Description of the encryption used.

From the document information dictionary: ‘info:Title’ ‘info:Author’ ‘info:Subject’ ‘info:Keywords’ ‘info:Creator’ ‘info:Producer’ ‘info:CreationDate’ ‘info:ModDate’

buf:
The buffer to hold the results (a nul-terminated UTF-8 string).
size:
Size of ‘buf’.

Returns the number of bytes need to store the string plus terminator (will be larger than ‘size’ if the output was truncated), or -1 if the key is not recognized or found.

macro FZ_META_FORMAT

#define FZ_META_FORMAT "format"

macro FZ_META_ENCRYPTION

#define FZ_META_ENCRYPTION "encryption"

macro FZ_META_INFO

#define FZ_META_INFO "info:"

macro FZ_META_INFO_TITLE

#define FZ_META_INFO_TITLE "info:Title"

macro FZ_META_INFO_AUTHOR

#define FZ_META_INFO_AUTHOR "info:Author"

macro FZ_META_INFO_SUBJECT

#define FZ_META_INFO_SUBJECT "info:Subject"

macro FZ_META_INFO_KEYWORDS

#define FZ_META_INFO_KEYWORDS "info:Keywords"

macro FZ_META_INFO_CREATOR

#define FZ_META_INFO_CREATOR "info:Creator"

macro FZ_META_INFO_PRODUCER

#define FZ_META_INFO_PRODUCER "info:Producer"

macro FZ_META_INFO_CREATIONDATE

#define FZ_META_INFO_CREATIONDATE "info:CreationDate"

macro FZ_META_INFO_MODIFICATIONDATE

#define FZ_META_INFO_MODIFICATIONDATE "info:ModDate"

function fz_set_metadata

void
fz_set_metadata (
        fz_context *ctx,
        fz_document *doc,
        const char *key,
        const char *value
)

function fz_document_output_intent

fz_colorspace *
fz_document_output_intent (
        fz_context *ctx,
        fz_document *doc
)

Find the output intent colorspace if the document has defined one.

Returns a borrowed reference that should not be dropped, unless it is kept first.

function fz_page_separations

fz_separations *
fz_page_separations (
        fz_context *ctx,
        fz_page *page
)

Get the separations details for a page. This will be NULL, unless the format specifically supports separations (such as PDF files). May be NULL even so, if there are no separations on a page.

Returns a reference that must be dropped.

function fz_page_uses_overprint

int
fz_page_uses_overprint (
        fz_context *ctx,
        fz_page *page
)

Query if a given page requires overprint.

fz_link *
fz_create_link (
        fz_context *ctx,
        fz_page *page,
        fz_rect bbox,
        const char *uri
)

Create a new link on a page.

void
fz_delete_link (
        fz_context *ctx,
        fz_page *page,
        fz_link *link
)

Delete an existing link on a page.

function fz_process_opened_pages

void *
fz_process_opened_pages (
        fz_context *ctx,
        fz_document *doc,
        fz_process_opened_page_fn *process_openend_page,
        void *state
)

Iterates over all opened pages of the document, calling the provided callback for each page for processing. If the callback returns non-NULL then the iteration stops and that value is returned to the caller of fz_process_opened_pages().

The state pointer provided to fz_process_opened_pages() is passed on to the callback but is owned by the caller.

Returns the first non-NULL value returned by the callback, or NULL if the callback returned NULL for all opened pages.

Implementation details: subject to change.

struct fz_page

struct fz_page
{
        int refs;
        fz_document *doc; /* kept reference to parent document. Guaranteed non-NULL. */
        int chapter; /* chapter number */
        int number; /* page number in chapter */
        int incomplete; /* incomplete from progressive loading; don't cache! */
        int in_doc; /* page has been placed into the document */
        fz_page_drop_page_fn *drop_page;
        fz_page_bound_page_fn *bound_page;
        fz_page_run_page_fn *run_page_contents;
        fz_page_run_page_fn *run_page_annots;
        fz_page_run_page_fn *run_page_widgets;
        fz_page_load_links_fn *load_links;
        fz_page_page_presentation_fn *page_presentation;
        fz_page_control_separation_fn *control_separation;
        fz_page_separation_disabled_fn *separation_disabled;
        fz_page_separations_fn *separations;
        fz_page_uses_overprint_fn *overprint;
        fz_page_create_link_fn *create_link;
        fz_page_delete_link_fn *delete_link;

        /* linked list of currently open pages. This list is maintained
         * by fz_load_chapter_page and fz_drop_page. All pages hold a
         * kept reference to the document, so the document cannot disappear
         * while pages exist. 'Incomplete' pages are NOT kept in this
         * list. */
        fz_page **prev, *next;
}

Structure definition is public so other classes can derive from it. Do not access the members directly.

struct fz_document

struct fz_document
{
        int refs;
        fz_document_drop_fn *drop_document;
        fz_document_needs_password_fn *needs_password;
        fz_document_authenticate_password_fn *authenticate_password;
        fz_document_has_permission_fn *has_permission;
        fz_document_load_outline_fn *load_outline;
        fz_document_outline_iterator_fn *outline_iterator;
        fz_document_style_fn *style;
        fz_document_layout_fn *layout;
        fz_document_make_bookmark_fn *make_bookmark;
        fz_document_lookup_bookmark_fn *lookup_bookmark;
        fz_document_resolve_link_dest_fn *resolve_link_dest;
        fz_document_format_link_uri_fn *format_link_uri;
        fz_document_count_chapters_fn *count_chapters;
        fz_document_count_pages_fn *count_pages;
        fz_document_load_page_fn *load_page;
        fz_document_page_label_fn *page_label;
        fz_document_lookup_metadata_fn *lookup_metadata;
        fz_document_set_metadata_fn *set_metadata;
        fz_document_output_intent_fn *get_output_intent;
        fz_document_output_accelerator_fn *output_accelerator;
        fz_document_run_structure_fn *run_structure;
        fz_document_as_pdf_fn *as_pdf;

        int is_reflowable;
        int id;

        /* Style options. When these change, both the style and layout methods will be called. */
        int did_style;
        int publisher_css;
        char *user_css;

        /* Layout size. When these change, the layout method will be called. */
        int did_layout;
        float layout_w, layout_h, layout_em;

        /* Linked list of currently open pages. These are not
         * references, but just a linked list of open pages,
         * maintained by fz_load_chapter_page, and fz_drop_page.
         * Every page holds a kept reference to the document, so
         * the document cannot be destroyed while a page exists.
         * Incomplete pages are NOT inserted into this list, but
         * do still hold a real document reference. */
        fz_page *open;
}

Structure definition is public so other classes can derive from it. Callers should not access the members directly, though implementations will need initialize functions directly.

struct fz_document_handler

struct fz_document_handler
{
        /* These fields are initialised by the handler when it is registered. */
        fz_document_recognize_fn *recognize;
        fz_document_open_fn *open;
        const char **extensions;
        const char **mimetypes;
        fz_document_recognize_content_fn *recognize_content;
        int wants_dir;
        int wants_file;
        fz_document_handler_fin_fn *fin;
}