PDF-Document

#ifndef MUPDF_FITZ_DOCUMENT_H
#define MUPDF_FITZ_DOCUMENT_H

#include “mupdf/fitz/system.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”

typedef struct fz_document fz_document;
typedef struct fz_document_handler fz_document_handler;
typedef struct fz_page fz_page;
typedef intptr_t fz_bookmark;

/**
Locations within the document are referred to in terms of
chapter and page, rather than just a page number. For some
documents (such as epub documents with large numbers of pages
broken into many chapters) this can make navigation much faster
as only the required chapter needs to be decoded at a time.
文档中的位置指的是
章节和页面，而不仅仅是页码。 对于一些
文档（例如具有大量页面的 epub 文档
分成许多章节）这可以使导航更快
因为一次只需要解码所需的章节。
*/
typedef struct
{
int chapter;
int page;
} fz_location;

/**
Simple constructor for fz_locations.
fz_locations 的简单构造函数。
*/
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,

};

typedef enum
{
FZ_PERMISSION_PRINT = ‘p’,
FZ_PERMISSION_COPY = ‘c’,
FZ_PERMISSION_EDIT = ‘e’,
FZ_PERMISSION_ANNOTATE = ‘n’,
}
fz_permission;

/**
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.
键入要在何时调用的函数fz_document 的引用计数下降到 0。
实现应该释放由
文档。 实际的文档指针将被释放
呼叫者。
*/
typedef void (fz_document_drop_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.
键入一个函数
调用查询文档是否需要密码
或不。 有关更多信息，请参阅 fz_needs_password。
*/
typedef int (fz_document_needs_password_fn)(fz_context *ctx, fz_document *doc);

/**
Type for a function to be
called to attempt to authenticate a password. See
fz_authenticate_password for more information.
键入一个函数
调用以尝试验证密码。 看
fz_authenticate_password 了解更多信息。
*/
typedef int (fz_document_authenticate_password_fn)(fz_context *ctx, fz_document *doc, const char *password);

/**
Type for a function to be
called to see if a document grants a certain permission. See
fz_document_has_permission for more information.
键入一个函数
调用以查看文档是否授予特定权限。 看
fz_document_has_permission 了解更多信息。
*/
typedef int (fz_document_has_permission_fn)(fz_context *ctx, fz_document *doc, fz_permission permission);

/**
Type for a function to be called to
load the outlines for a document. See fz_document_load_outline
for more information.
键入要调用的函数
加载文档的轮廓。 见 fz_document_load_outline
想要查询更多的信息。
*/
typedef fz_outline *(fz_document_load_outline_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.
键入要调用的函数以进行铺设
出一个文件。 有关更多信息，请参阅 fz_layout_document。
*/
typedef void (fz_document_layout_fn)(fz_context *ctx, fz_document *doc, float w, float h, float em);

/**
Type for a function to be called to
resolve an internal link to a location (chapter/page number
tuple). See fz_resolve_link for more information.
键入要调用的函数
解析指向某个位置的内部链接（章节/页码
元组）。 有关更多信息，请参阅 fz_resolve_link。
*/
typedef fz_location (fz_document_resolve_link_fn)(fz_context *ctx, fz_document *doc, const char *uri, float *xp, float *yp);

/**
Type for a function to be called to
count the number of chapters in a document. See
fz_count_chapters for more information.
键入要调用的函数
计算文档中的章节数。 看
fz_count_chapters 了解更多信息。
*/
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 pages in a document. See fz_count_pages for
more information.
键入要调用的函数
计算文档中的页数。 见 fz_count_pages
更多信息。
*/
typedef int (fz_document_count_pages_fn)(fz_context *ctx, fz_document *doc, int chapter);

/**
Type for a function to load a given
page from a document. See fz_load_page for more information.
输入一个函数来加载给定的
文档中的页面。 有关更多信息，请参阅 fz_load_page。
*/
typedef fz_page *(fz_document_load_page_fn)(fz_context *ctx, fz_document *doc, int chapter, int page);

/**
Type for a function to query
a documents metadata. See fz_lookup_metadata for more
information.
键入要查询的函数
文档元数据。 查看 fz_lookup_metadata 了解更多
信息。
*/
typedef int (fz_document_lookup_metadata_fn)(fz_context *ctx, fz_document *doc, const char *key, char *buf, int size);

/**
Return output intent color space if it exists
*/
typedef fz_colorspace *(fz_document_output_intent_fn)(fz_context *ctx, fz_document *doc);

/**
Write document accelerator data
写入文档加速器数据
*/
typedef void (fz_document_output_accelerator_fn)(fz_context *ctx, fz_document *doc, fz_output *out);

/**
Type for a function to make
a bookmark. See fz_make_bookmark for more information.
键入要生成的函数
书签。 有关更多信息，请参阅 fz_make_bookmark。
*/
typedef fz_bookmark (fz_document_make_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_location loc);

/**
Type for a function to lookup a bookmark.
See fz_lookup_bookmark for more information.
键入用于查找书签的函数。
有关更多信息，请参阅 fz_lookup_bookmark。
*/
typedef fz_location (fz_document_lookup_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_bookmark mark);

/**
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 void (fz_page_drop_page_fn)(fz_context *ctx, fz_page *page);

/**
Type for a function to return the
bounding box of a page. See fz_bound_page for more
information.
输入函数以返回
页面的边界框。 查看 fz_bound_page 了解更多
信息。
*/
typedef fz_rect (fz_page_bound_page_fn)(fz_context *ctx, fz_page *page);

/**
Type for a function to run the
contents of a page. See fz_run_page_contents for more
information.
键入一个函数来运行
页面的内容。 查看 fz_run_page_contents 了解更多
信息。
*/
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 load the links
from a page. See fz_load_links for more information.
键入用于加载链接的函数
从一个页面。 有关更多信息，请参阅 fz_load_links。
*/
typedef fz_link *(fz_page_load_links_fn)(fz_context *ctx, fz_page *page);

/**
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.
键入一个函数
获取有关如何显示此页面的详细信息
在演示模式。 查看 fz_page_presentation 了解更多
信息。
*/
typedef fz_transition *(fz_page_page_presentation_fn)(fz_context *ctx, fz_page *page, fz_transition *transition, float *duration);

/**
Type for a function to enable/
disable separations on a page. See fz_control_separation for
more information.
键入要启用的功能/
禁用页面上的分色。 参见 fz_control_separation
更多信息。
*/
typedef void (fz_page_control_separation_fn)(fz_context *ctx, fz_page *page, int separation, int disable);

/**
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 int (fz_page_separation_disabled_fn)(fz_context *ctx, fz_page *page, int separation);

/**
Type for a function to retrieve
details of separations on a page. See fz_get_separations
for more information.
*/
typedef fz_separations *(fz_page_separations_fn)(fz_context *ctx, fz_page *page);

/**
Type for a function to retrieve
whether or not a given page uses overprint.
键入要检索的函数
给定页面是否使用叠印。
*/
typedef int (fz_page_uses_overprint_fn)(fz_context *ctx, fz_page *page);

/**
Type for a function to create a link on a page.
键入用于在页面上创建链接的函数。
*/
typedef fz_link *(fz_page_create_link_fn)(fz_context *ctx, fz_page *page, fz_rect bbox, const char *uri);

/**
Function type to open a document from a file.

filename: file to open

Pointer to opened document. Throws exception in case of error.
从文件打开文档的函数类型。

文件名：要打开的文件

指向已打开文档的指针。 出错时抛出异常。

*/
typedef fz_document *(fz_document_open_fn)(fz_context *ctx, const char *filename);

/**
Function type to open a
document from a file.

stream: fz_stream to read document data from. Must be
seekable for formats that require it.

Pointer to opened document. Throws exception in case of error.
函数类型打开一个
文件中的文档。

流： fz_stream 从中读取文档数据。 一定是
可查找需要它的格式。

指向已打开文档的指针。 出错时抛出异常。

*/
typedef fz_document *(fz_document_open_with_stream_fn)(fz_context *ctx, fz_stream *stream);

/**
Function type to open a document from a
file, with accelerator data.

filename: file to open

accel: accelerator file

Pointer to opened document. Throws exception in case of error.
从文件打开文档的函数类型
文件，带有加速器数据。

文件名：要打开的文件

accel：加速器文件

指向已打开文档的指针。 出错时抛出异常。

*/
typedef fz_document *(fz_document_open_accel_fn)(fz_context *ctx, const char *filename, const char *accel);

/**
Function type to open a document from a file,
with accelerator data.

stream: fz_stream to read document data from. Must be
seekable for formats that require it.

accel: fz_stream to read accelerator data from. Must be
seekable for formats that require it.

Pointer to opened document. Throws exception in case of error.
从文件打开文档的函数类型，
与加速器数据。

流： fz_stream 从中读取文档数据。 一定是
可查找需要它的格式。

accel: fz_stream 从中读取加速器数据。 一定是
可查找需要它的格式。

指向已打开文档的指针。 出错时抛出异常。

*/
typedef fz_document *(fz_document_open_accel_with_stream_fn)(fz_context *ctx, fz_stream *stream, fz_stream *accel);

/**
Recognize a document type from
a magic string.

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.

识别文档类型
一个神奇的字符串。

魔法：要识别的字符串 - 通常是文件名或 mime
类型。

返回 0（无法识别）和 100 之间的数字
（完全识别）基于识别器的确定程度
是这是必需的类型。

*/
typedef int (fz_document_recognize_fn)(fz_context *ctx, const char *magic);

/**
Register a handler for a document type.

handler: The handler to register.
为文档类型注册处理程序。

handler：要注册的处理程序。

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

/**
Register handlers
for all the standard document types supported in
this build.
注册处理程序
对于所有支持的标准文档类型
这个构建。
*/
void fz_register_document_handlers(fz_context *ctx);

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

给定一个魔术，找到一个可以处理这种类型文档的文档处理程序。 magic：可以是 mime 类型的文件扩展名（包括初始句点）。

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

/**
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).

打开一个文档文件并阅读它的基本结构，因此页面和
可以定位对象。 MuPDF 将尝试修复损坏的
文档（不实际更改文件内容）。

调用大多数其他时使用返回的 fz_document
文档相关功能。

文件名：文件的路径，因为它将被赋予 open(2)。

*/
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).

打开一个文档文件并阅读它的基本结构，因此页面和
可以定位对象。 MuPDF 将尝试修复损坏的
文档（不实际更改文件内容）。

调用大多数其他时使用返回的 fz_document
文档相关功能。

文件名：文件的路径，因为它将被赋予 open(2)

*/
fz_document *fz_open_accelerated_document(fz_context *ctx, const char *filename, const char *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.

使用指定的流对象而不是打开文档
打开磁盘上的文件。

magic：用于检测文档类型的字符串； 要么是文件名
或哑剧类型。

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

使用指定的流对象而不是打开文档
打开磁盘上的文件。

magic：用于检测文档类型的字符串； 要么是文件名
或哑剧类型。

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

/**
Query if the document supports the saving of accelerator data.
查询文档是否支持保存加速器数据。
*/
int fz_document_supports_accelerator(fz_context *ctx, fz_document *doc);

/**
Save accelerator data for the document to a given file.
将文档的加速器数据保存到给定文件。
*/
void fz_save_accelerator(fz_context *ctx, fz_document *doc, const char *accel);

/**
Output accelerator data for the document to a given output
stream.
将文档的加速器数据输出到给定的输出
溪流。
*/
void fz_output_accelerator(fz_context *ctx, fz_document *doc, fz_output *accel);

/**
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)
新文档通常是通过调用创建的
foo_new_document(fz_context *ctx, …)。 这些工作由
从 fz_document 派生一个新的文档类型，例如：
typedef struct { fz_document base; …额外… } foo_document;
这些是通过调用分配的
fz_new_derived_document(ctx, foo_document)
*/
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))

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

Never throws exceptions.
增加文档引用计数。 相同的指针是回。

从不抛出异常。

*/
fz_document *fz_keep_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.
减少文档引用计数。 当参考
计数达到 0，文档及其所有引用都是
获释。

从不抛出异常。

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

/**
Check if a document is encrypted with a
non-blank password.
检查文档是否使用非空密码。
*/
int fz_needs_password(fz_context *ctx, fz_document *doc);

/**
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
测试给定的密码是否可以解密文档。

password：要检查的密码字符串。 一些文件
规范没有指定任何特定的文本编码，所以
我们也不。

验证失败返回 0，成功返回非零。

对于 PDF 文档，可以通过检查获得更多信息
返回码中的位。

位 0 => 无需密码
位 1 => 用户密码已验证
位 2 => 所有者密码已验证

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

/**
Load the hierarchical document outline.

Should be freed by fz_drop_outline.

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

/**
Is the document reflowable.

Returns 1 to indicate reflowable documents, otherwise 0.

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

/**
Layout reflowable document types.

w, h: Page size in points.
em: Default font size in points.
布局可回流的文档类型。

w, h：以磅为单位的页面大小。
em：以磅为单位的默认字体大小。

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

/**
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.
为给定页面创建书签，可用于查找
文档布局后的相同位置
不同的参数。
*/
fz_bookmark fz_make_bookmark(fz_context *ctx, fz_document *doc, fz_location loc);

/**
Find a bookmark and return its page number.
找到一个书签并返回其页码。
*/
fz_location fz_lookup_bookmark(fz_context *ctx, fz_document *doc, fz_bookmark mark);

/**
Return the number of pages in document

May return 0 for documents with no pages.
返回文档中的页数
对于没有页面的文档，可能返回 0。

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

/**
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.
解析指向页码的内部链接。

xp, yp：在页面上存储目的地坐标的指针。

如果无法解析 URI，则返回 (-1,-1)。

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

/**
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.
获取文档最后一页位置的函数。
在某些情况下，使用它比调用更有效
fz_count_pages 并使用页码。
*/
fz_location fz_last_page(fz_context *ctx, fz_document *doc);

/**
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.
获取下一页位置的函数（允许
章节结尾等）。 如果在文档末尾，则返回
当前位置。
*/
fz_location fz_next_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.
获取上一页位置的函数（允许
章节结尾等）。 如果已经在开始
文档，返回当前页面。
*/
fz_location fz_previous_page(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).
将位置夹在有效的章节/页面范围内。 （第一夹
章节进入范围，然后页面进入范围）。
*/
fz_location fz_clamp_location(fz_context *ctx, fz_document *doc, fz_location loc);

/**
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.
从页码转换为章节+页面。 这可能会导致许多
为计算数量而布置的章节
这些章节中的页面。
*/
fz_location fz_location_from_page_number(fz_context *ctx, fz_document *doc, int number);

/**
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.
从章节+页面转换为页码。 这可能会导致许多
为计算数量而布置的章节
这些章节中的页面。
*/
int fz_page_number_from_location(fz_context *ctx, fz_document *doc, fz_location loc);

/**
Load a given page number from a document. This may be much less
efficient than loading by location (chapter+page) for some
document types.
从文档加载给定的页码。 这可能少得多
对于某些人来说，比按位置（章节+页面）加载更高效
文档类型。
*/
fz_page *fz_load_page(fz_context *ctx, fz_document *doc, int number);

/**
Return the number of chapters in the document.
At least 1.
返回文档中的章节数。
至少 1。
*/
int fz_count_chapters(fz_context *ctx, fz_document *doc);

/**
Return the number of pages in a chapter.
May return 0.
返回章节中的页数。
可能返回 0。
*/
int fz_count_chapter_pages(fz_context *ctx, fz_document *doc, int chapter);

/**
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_load_page 之后是否可以检索
使用 fz_bound_page 的页面，或者使用
fz_run_page_*。 通过调用 fz_drop_page 释放页面。

chapter：章节编号，0 为文档的第一章。
number：页码，0为章节第一页。

*/
fz_page *fz_load_chapter_page(fz_context *ctx, fz_document *doc, int chapter, int 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.

加载页面的链接列表。

返回页面上所有链接的链表，每个链接都有
它的可点击区域和链接目的地。 每个链接都是
引用计数所以删除并释放链接列表
在从 fz_load_links 返回的指针上调用 fz_drop_link。

page：从 fz_load_page 获取的页面。

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

/**
Different document types will be implemented by deriving from
fz_page. This macro allocates such derived structures, and
initialises the base sections.
不同的文档类型将通过派生来实现
fz_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))

/**
Determine the size of a page at 72 dpi.
确定 72 dpi 的页面大小。
*/
fz_rect fz_bound_page(fz_context *ctx, fz_page *page);

/**
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.
通过设备运行页面。

page：从 fz_load_page 获取的页面。

dev：从 fz_new_*_device 获得的设备。

变换：变换以应用于页面。 可能包括例如
缩放和旋转，参见 fz_scale、fz_rotate 和 fz_concat。
如果不需要转换，则设置为 fz_identity。

cookie：调用者和库之间的通信机制
呈现页面。 适用于多线程应用程序，
而单线程应用程序将 cookie 设置为 NULL。 这
调用者可能会中止正在进行的页面呈现。 饼干也
将进度信息返回给调用者。 这
cookie 中的字段在页面运行时不断更新
渲染。

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

通过设备运行页面。 只是主要
页面内容，不带注释（如果有）。

page：从 fz_load_page 获取的页面。

dev：从 fz_new_*_device 获得的设备。

变换：变换以应用于页面。 可能包括例如
缩放和旋转，参见 fz_scale、fz_rotate 和 fz_concat。
如果不需要转换，则设置为 fz_identity。

cookie：调用者和库之间的通信机制
呈现页面。 适用于多线程应用程序，
而单线程应用程序将 cookie 设置为 NULL。 这
调用者可能会中止正在进行的页面呈现。 饼干也
将进度信息返回给调用者。 这
cookie 中的字段在页面运行时不断更新
渲染。

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

/**
Run the annotations on a page through a device.
通过设备在页面上运行注释。
*/
void fz_run_page_annots(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);

/**
Run the widgets on a page through a device.
通过设备在页面上运行小部件。
*/
void fz_run_page_widgets(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);

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

Never throws exceptions.
增加页面的引用计数。 返回相同指针。
从不抛出异常。

*/
fz_page *fz_keep_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.
减少页面的引用计数。 当参考
计数命中 0，页面及其引用被释放。

从不抛出异常。
*/

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

/**
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.
获取给定页面的演示详细信息。

过渡：指向要填充的过渡结构的指针。

持续时间：指向设置页面持续时间的位置的指针
秒。 如果没有为
页。

返回： 指向转换结构的指针，如果存在则返回 NULL
没有为页面指定过渡。

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

/**
Check permission flags on document.
检查文档上的权限标志。
*/
int fz_has_permission(fz_context *ctx, fz_document *doc, fz_permission p);

/**
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.
检索文档元数据字符串。

doc：要查询的文档。

键：要检索哪个元数据键…

基本信息：
‘format’ – 文档格式和版本。
‘encryption’ – 所用加密的描述。

来自文档信息字典：
‘信息：标题’
‘信息：作者’
‘信息：主题’
‘信息：关键字’
‘信息：创作者’
‘信息：制片人’
‘信息：创建日期’
‘信息：修改日期’

buf：保存结果的缓冲区（以空字符结尾的 UTF-8
细绳）。

大小：‘buf’ 的大小。

返回需要存储的字符串加上终止符的字节数
（如果输出被截断，则将大于 ‘size’），如果输出被截断，则为 -1
无法识别或找到密钥。
*/
int fz_lookup_metadata(fz_context *ctx, fz_document *doc, const char *key, char *buf, int size);

#define FZ_META_FORMAT “format”
#define FZ_META_ENCRYPTION “encryption”

#define FZ_META_INFO_AUTHOR “info:Author”
#define FZ_META_INFO_TITLE “info:Title”
#define FZ_META_INFO_CREATOR “info:Creator”
#define FZ_META_INFO_PRODUCER “info:Producer”

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

如果文档已定义，则查找输出意图色彩空间一。

返回不应删除的借用引用，除非
它首先被保留。

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

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

获取页面的分色详细信息。
这将为 NULL，除非格式特别支持
分色（如 PDF 文件）。 甚至可能为 NULL
所以，如果页面上没有分色。

返回必须删除的引用。

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

/**
Query if a given page requires overprint.
查询给定页面是否需要叠印。
*/
int fz_page_uses_overprint(fz_context *ctx, fz_page *page);

/**
Create a new link on a page.
在页面上创建一个新链接。
*/
fz_link *fz_create_link(fz_context *ctx, fz_page *page, fz_rect bbox, const char *uri);

/* Implementation details: subject to change. */

/**
Structure definition is public so other classes can
derive from it. Do not access the members directly.
结构定义是公开的，所以其他类可以从中得出。 不要直接访问成员。
*/
struct fz_page
{
int refs;
fz_document doc; / reference to parent document /
int chapter; / chapter number /
int number; / page number in chapter /
int incomplete; / incomplete from progressive loading; don’t cache! */
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 **prev, next; / linked list of currently open pages */
};

/**
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
{
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_layout_fn *layout;
fz_document_make_bookmark_fn *make_bookmark;
fz_document_lookup_bookmark_fn *lookup_bookmark;
fz_document_resolve_link_fn *resolve_link;
fz_document_count_chapters_fn *count_chapters;
fz_document_count_pages_fn *count_pages;
fz_document_load_page_fn *load_page;
fz_document_lookup_metadata_fn *lookup_metadata;
fz_document_output_intent_fn *get_output_intent;
fz_document_output_accelerator_fn *output_accelerator;
int did_layout;
int is_reflowable;
fz_page open; / linked list of currently open pages */
};

struct fz_document_handler
{
fz_document_recognize_fn *recognize;
fz_document_open_fn *open;
fz_document_open_with_stream_fn *open_with_stream;
const char **extensions;
const char **mimetypes;
fz_document_open_accel_fn *open_accel;
fz_document_open_accel_with_stream_fn *open_accel_with_stream;
};

#endif