document.h

Go to the documentation of this file.

// Copyright (C) 2004-2026 Artifex Software, Inc.
//
// This file is part of MuPDF.
//
// MuPDF is free software: you can redistribute it and/or modify it under the
// terms of the GNU Affero General Public License as published by the Free
// Software Foundation, either version 3 of the License, or (at your option)
// any later version.
//
// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
// details.
//
// You should have received a copy of the GNU Affero General Public License
// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
//
// Alternative licensing terms are available from the licensor.
// For commercial licensing, see <https://www.artifex.com/> or contact
// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
// CA 94129, USA, for further information.
 
#ifndef MUPDF_FITZ_DOCUMENT_H
#define MUPDF_FITZ_DOCUMENT_H
 
#include "mupdf/fitz/system.h"
#include "mupdf/fitz/types.h"
#include "mupdf/fitz/context.h"
#include "mupdf/fitz/geometry.h"
#include "mupdf/fitz/device.h"
#include "mupdf/fitz/transition.h"
#include "mupdf/fitz/link.h"
#include "mupdf/fitz/outline.h"
#include "mupdf/fitz/separation.h"
#include "mupdf/fitz/archive.h"
 
typedef struct fz_document_handler fz_document_handler;
typedef struct fz_page fz_page;
typedef intptr_t fz_bookmark;
 
typedef enum
{
    FZ_MEDIA_BOX,
    FZ_CROP_BOX,
    FZ_BLEED_BOX,
    FZ_TRIM_BOX,
    FZ_ART_BOX,
    FZ_UNKNOWN_BOX
} fz_box_type;
 
fz_box_type fz_box_type_from_string(const char *name);
const char *fz_string_from_box_type(fz_box_type box);

static inline fz_location fz_make_location(int chapter, int page)
{
    fz_location loc = { chapter, page };
    return loc;
}
 
enum
{
    /* 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_STYLE_NEEDS_DEFAULT = -1,
    FZ_STYLE_NEEDS_UPDATE = 0,
    FZ_STYLE_APPLIED = 1,
};
 
enum
{
    FZ_LAYOUT_NEEDS_UPDATE = 0,
    FZ_LAYOUT_APPLIED = 1,
};
 
typedef enum
{
    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',
}
fz_permission;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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);

typedef int (fz_document_recognize_fn)(fz_context *ctx, const fz_document_handler *handler, const char *magic);
 
typedef void (fz_document_recognize_state_free_fn)(fz_context *ctx, void *state);

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);

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

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

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

void fz_register_document_handlers(fz_context *ctx);

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

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

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

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

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

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

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

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

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

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

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);

int fz_document_supports_accelerator(fz_context *ctx, fz_document *doc);

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

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

void *fz_new_document_of_size(fz_context *ctx, int size);
#define fz_new_derived_document(C,M) ((M*)Memento_label(fz_new_document_of_size(C, sizeof(M)), #M))

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

void fz_drop_document(fz_context *ctx, fz_document *doc);

int fz_needs_password(fz_context *ctx, fz_document *doc);

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

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

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

int fz_is_document_reflowable(fz_context *ctx, fz_document *doc);

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

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

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

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

int fz_count_pages(fz_context *ctx, fz_document *doc);

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

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

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

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

fz_location fz_last_page(fz_context *ctx, fz_document *doc);

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

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

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

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

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

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

int fz_count_chapters(fz_context *ctx, fz_document *doc);

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

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

fz_link *fz_load_links(fz_context *ctx, fz_page *page);

fz_page *fz_new_page_of_size(fz_context *ctx, int size, fz_document *doc);
#define fz_new_derived_page(CTX,TYPE,DOC) \
    ((TYPE *)Memento_label(fz_new_page_of_size(CTX,sizeof(TYPE),DOC),#TYPE))

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

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

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

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

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

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

void fz_drop_page(fz_context *ctx, fz_page *page);

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

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

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

int fz_lookup_metadata(fz_context *ctx, fz_document *doc, const char *key, char *buf, size_t size);
 
#define FZ_META_FORMAT "format"
#define FZ_META_ENCRYPTION "encryption"
 
#define FZ_META_INFO "info:"
#define FZ_META_INFO_TITLE "info:Title"
#define FZ_META_INFO_AUTHOR "info:Author"
#define FZ_META_INFO_SUBJECT "info:Subject"
#define FZ_META_INFO_KEYWORDS "info:Keywords"
#define FZ_META_INFO_CREATOR "info:Creator"
#define FZ_META_INFO_PRODUCER "info:Producer"
#define FZ_META_INFO_CREATIONDATE "info:CreationDate"
#define FZ_META_INFO_MODIFICATIONDATE "info:ModDate"
 
void fz_set_metadata(fz_context *ctx, fz_document *doc, const char *key, const char *value);

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

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

int fz_page_uses_overprint(fz_context *ctx, fz_page *page);

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

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

void *fz_process_opened_pages(fz_context *ctx, fz_document *doc, fz_process_opened_page_fn *process_openend_page, void *state);
 
/* Implementation details: subject to change. */

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;
};

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;
};
 
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;
};
 
#endif