Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/document.h @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 // Copyright (C) 2004-2025 Artifex Software, Inc.
2 //
3 // This file is part of MuPDF.
4 //
5 // MuPDF is free software: you can redistribute it and/or modify it under the
6 // terms of the GNU Affero General Public License as published by the Free
7 // Software Foundation, either version 3 of the License, or (at your option)
8 // any later version.
9 //
10 // MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 // FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
13 // details.
14 //
15 // You should have received a copy of the GNU Affero General Public License
16 // along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
17 //
18 // Alternative licensing terms are available from the licensor.
19 // For commercial licensing, see <https://www.artifex.com/> or contact
20 // Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
21 // CA 94129, USA, for further information.
22
23 #ifndef MUPDF_FITZ_DOCUMENT_H
24 #define MUPDF_FITZ_DOCUMENT_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/types.h"
28 #include "mupdf/fitz/context.h"
29 #include "mupdf/fitz/geometry.h"
30 #include "mupdf/fitz/device.h"
31 #include "mupdf/fitz/transition.h"
32 #include "mupdf/fitz/link.h"
33 #include "mupdf/fitz/outline.h"
34 #include "mupdf/fitz/separation.h"
35 #include "mupdf/fitz/archive.h"
36
37 typedef struct fz_document_handler fz_document_handler;
38 typedef struct fz_page fz_page;
39 typedef intptr_t fz_bookmark;
40
41 typedef enum
42 {
43 FZ_MEDIA_BOX,
44 FZ_CROP_BOX,
45 FZ_BLEED_BOX,
46 FZ_TRIM_BOX,
47 FZ_ART_BOX,
48 FZ_UNKNOWN_BOX
49 } fz_box_type;
50
51 fz_box_type fz_box_type_from_string(const char *name);
52 const char *fz_string_from_box_type(fz_box_type box);
53
54 /**
55 Simple constructor for fz_locations.
56 */
57 static inline fz_location fz_make_location(int chapter, int page)
58 {
59 fz_location loc = { chapter, page };
60 return loc;
61 }
62
63 enum
64 {
65 /* 6in at 4:3 */
66 FZ_LAYOUT_KINDLE_W = 260,
67 FZ_LAYOUT_KINDLE_H = 346,
68 FZ_LAYOUT_KINDLE_EM = 9,
69
70 /* 4.25 x 6.87 in */
71 FZ_LAYOUT_US_POCKET_W = 306,
72 FZ_LAYOUT_US_POCKET_H = 495,
73 FZ_LAYOUT_US_POCKET_EM = 10,
74
75 /* 5.5 x 8.5 in */
76 FZ_LAYOUT_US_TRADE_W = 396,
77 FZ_LAYOUT_US_TRADE_H = 612,
78 FZ_LAYOUT_US_TRADE_EM = 11,
79
80 /* 110 x 178 mm */
81 FZ_LAYOUT_UK_A_FORMAT_W = 312,
82 FZ_LAYOUT_UK_A_FORMAT_H = 504,
83 FZ_LAYOUT_UK_A_FORMAT_EM = 10,
84
85 /* 129 x 198 mm */
86 FZ_LAYOUT_UK_B_FORMAT_W = 366,
87 FZ_LAYOUT_UK_B_FORMAT_H = 561,
88 FZ_LAYOUT_UK_B_FORMAT_EM = 10,
89
90 /* 135 x 216 mm */
91 FZ_LAYOUT_UK_C_FORMAT_W = 382,
92 FZ_LAYOUT_UK_C_FORMAT_H = 612,
93 FZ_LAYOUT_UK_C_FORMAT_EM = 11,
94
95 /* 148 x 210 mm */
96 FZ_LAYOUT_A5_W = 420,
97 FZ_LAYOUT_A5_H = 595,
98 FZ_LAYOUT_A5_EM = 11,
99
100 /* Default to A5 */
101 FZ_DEFAULT_LAYOUT_W = FZ_LAYOUT_A5_W,
102 FZ_DEFAULT_LAYOUT_H = FZ_LAYOUT_A5_H,
103 FZ_DEFAULT_LAYOUT_EM = FZ_LAYOUT_A5_EM,
104 };
105
106 typedef enum
107 {
108 FZ_PERMISSION_PRINT = 'p',
109 FZ_PERMISSION_COPY = 'c',
110 FZ_PERMISSION_EDIT = 'e',
111 FZ_PERMISSION_ANNOTATE = 'n',
112 FZ_PERMISSION_FORM = 'f',
113 FZ_PERMISSION_ACCESSIBILITY = 'y',
114 FZ_PERMISSION_ASSEMBLE = 'a',
115 FZ_PERMISSION_PRINT_HQ = 'h',
116 }
117 fz_permission;
118
119 /**
120 Type for a function to be called when
121 the reference count for the fz_document drops to 0. The
122 implementation should release any resources held by the
123 document. The actual document pointer will be freed by the
124 caller.
125 */
126 typedef void (fz_document_drop_fn)(fz_context *ctx, fz_document *doc);
127
128 /**
129 Type for a function to be
130 called to enquire whether the document needs a password
131 or not. See fz_needs_password for more information.
132 */
133 typedef int (fz_document_needs_password_fn)(fz_context *ctx, fz_document *doc);
134
135 /**
136 Type for a function to be
137 called to attempt to authenticate a password. See
138 fz_authenticate_password for more information.
139 */
140 typedef int (fz_document_authenticate_password_fn)(fz_context *ctx, fz_document *doc, const char *password);
141
142 /**
143 Type for a function to be
144 called to see if a document grants a certain permission. See
145 fz_document_has_permission for more information.
146 */
147 typedef int (fz_document_has_permission_fn)(fz_context *ctx, fz_document *doc, fz_permission permission);
148
149 /**
150 Type for a function to be called to
151 load the outlines for a document. See fz_document_load_outline
152 for more information.
153 */
154 typedef fz_outline *(fz_document_load_outline_fn)(fz_context *ctx, fz_document *doc);
155
156 /**
157 Type for a function to be called to obtain an outline iterator
158 for a document. See fz_document_outline_iterator for more information.
159 */
160 typedef fz_outline_iterator *(fz_document_outline_iterator_fn)(fz_context *ctx, fz_document *doc);
161
162 /**
163 Type for a function to be called to lay
164 out a document. See fz_layout_document for more information.
165 */
166 typedef void (fz_document_layout_fn)(fz_context *ctx, fz_document *doc, float w, float h, float em);
167
168 /**
169 Type for a function to be called to
170 resolve an internal link to a location (chapter/page number
171 tuple). See fz_resolve_link_dest for more information.
172 */
173 typedef fz_link_dest (fz_document_resolve_link_dest_fn)(fz_context *ctx, fz_document *doc, const char *uri);
174
175 /**
176 Type for a function to be called to
177 create an internal link to a destination (chapter/page/x/y/w/h/zoom/type
178 tuple). See fz_resolve_link_dest for more information.
179 */
180 typedef char * (fz_document_format_link_uri_fn)(fz_context *ctx, fz_document *doc, fz_link_dest dest);
181
182 /**
183 Type for a function to be called to
184 count the number of chapters in a document. See
185 fz_count_chapters for more information.
186 */
187 typedef int (fz_document_count_chapters_fn)(fz_context *ctx, fz_document *doc);
188
189 /**
190 Type for a function to be called to
191 count the number of pages in a document. See fz_count_pages for
192 more information.
193 */
194 typedef int (fz_document_count_pages_fn)(fz_context *ctx, fz_document *doc, int chapter);
195
196 /**
197 Type for a function to load a given
198 page from a document. See fz_load_page for more information.
199 */
200 typedef fz_page *(fz_document_load_page_fn)(fz_context *ctx, fz_document *doc, int chapter, int page);
201
202 /**
203 Type for a function to get the page label of a page in the document.
204 See fz_page_label for more information.
205 */
206 typedef void (fz_document_page_label_fn)(fz_context *ctx, fz_document *doc, int chapter, int page, char *buf, size_t size);
207
208 /**
209 Type for a function to query
210 a document's metadata. See fz_lookup_metadata for more
211 information.
212 */
213 typedef int (fz_document_lookup_metadata_fn)(fz_context *ctx, fz_document *doc, const char *key, char *buf, size_t size);
214
215 /**
216 Type for a function to set
217 a document's metadata. See fz_set_metadata for more
218 information.
219 */
220 typedef void (fz_document_set_metadata_fn)(fz_context *ctx, fz_document *doc, const char *key, const char *value);
221
222 /**
223 Return output intent color space if it exists
224 */
225 typedef fz_colorspace *(fz_document_output_intent_fn)(fz_context *ctx, fz_document *doc);
226
227 /**
228 Write document accelerator data
229 */
230 typedef void (fz_document_output_accelerator_fn)(fz_context *ctx, fz_document *doc, fz_output *out);
231
232 /**
233 Send document structure to device
234 */
235 typedef void (fz_document_run_structure_fn)(fz_context *ctx, fz_document *doc, fz_device *dev, fz_cookie *cookie);
236
237 /**
238 Get a handle to this document as PDF.
239
240 Returns a borrowed handle.
241 */
242 typedef fz_document *(fz_document_as_pdf_fn)(fz_context *ctx, fz_document *doc);
243
244 /**
245 Type for a function to make
246 a bookmark. See fz_make_bookmark for more information.
247 */
248 typedef fz_bookmark (fz_document_make_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_location loc);
249
250 /**
251 Type for a function to lookup a bookmark.
252 See fz_lookup_bookmark for more information.
253 */
254 typedef fz_location (fz_document_lookup_bookmark_fn)(fz_context *ctx, fz_document *doc, fz_bookmark mark);
255
256 /**
257 Type for a function to release all the
258 resources held by a page. Called automatically when the
259 reference count for that page reaches zero.
260 */
261 typedef void (fz_page_drop_page_fn)(fz_context *ctx, fz_page *page);
262
263 /**
264 Type for a function to return the
265 bounding box of a page. See fz_bound_page for more
266 information.
267 */
268 typedef fz_rect (fz_page_bound_page_fn)(fz_context *ctx, fz_page *page, fz_box_type box);
269
270 /**
271 Type for a function to run the
272 contents of a page. See fz_run_page_contents for more
273 information.
274 */
275 typedef void (fz_page_run_page_fn)(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);
276
277 /**
278 Type for a function to load the links
279 from a page. See fz_load_links for more information.
280 */
281 typedef fz_link *(fz_page_load_links_fn)(fz_context *ctx, fz_page *page);
282
283 /**
284 Type for a function to
285 obtain the details of how this page should be presented when
286 in presentation mode. See fz_page_presentation for more
287 information.
288 */
289 typedef fz_transition *(fz_page_page_presentation_fn)(fz_context *ctx, fz_page *page, fz_transition *transition, float *duration);
290
291 /**
292 Type for a function to enable/
293 disable separations on a page. See fz_control_separation for
294 more information.
295 */
296 typedef void (fz_page_control_separation_fn)(fz_context *ctx, fz_page *page, int separation, int disable);
297
298 /**
299 Type for a function to detect
300 whether a given separation is enabled or disabled on a page.
301 See FZ_SEPARATION_DISABLED for more information.
302 */
303 typedef int (fz_page_separation_disabled_fn)(fz_context *ctx, fz_page *page, int separation);
304
305 /**
306 Type for a function to retrieve
307 details of separations on a page. See fz_get_separations
308 for more information.
309 */
310 typedef fz_separations *(fz_page_separations_fn)(fz_context *ctx, fz_page *page);
311
312 /**
313 Type for a function to retrieve
314 whether or not a given page uses overprint.
315 */
316 typedef int (fz_page_uses_overprint_fn)(fz_context *ctx, fz_page *page);
317
318
319 /**
320 Type for a function to create a link on a page.
321 */
322 typedef fz_link *(fz_page_create_link_fn)(fz_context *ctx, fz_page *page, fz_rect bbox, const char *uri);
323
324 /**
325 Type for a function to delete a link on a page.
326 */
327 typedef void (fz_page_delete_link_fn)(fz_context *ctx, fz_page *page, fz_link *link);
328
329 /**
330 Function type to open a
331 document from a file.
332
333 handler: the document handler in use.
334
335 stream: fz_stream to read document data from. Must be
336 seekable for formats that require it.
337
338 accel: fz_stream to read accelerator data from. May be
339 NULL. May be ignored.
340
341 dir: 'Directory context' in which the document is loaded;
342 associated content from (like images for an html stream
343 will be loaded from this). Maybe NULL. May be ignored.
344
345 recognize_state: NULL, or a state pointer passed back from the call
346 to recognise_content_fn. Ownership does not pass in. The
347 caller remains responsible for freeing state.
348
349 Pointer to opened document. Throws exception in case of error.
350 */
351 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);
352
353 /**
354 Recognize a document type from
355 a magic string.
356
357 handler: the handler in use.
358
359 magic: string to recognise - typically a filename or mime
360 type.
361
362 Returns a number between 0 (not recognized) and 100
363 (fully recognized) based on how certain the recognizer
364 is that this is of the required type.
365 */
366 typedef int (fz_document_recognize_fn)(fz_context *ctx, const fz_document_handler *handler, const char *magic);
367
368 typedef void (fz_document_recognize_state_free_fn)(fz_context *ctx, void *state);
369
370 /**
371 Recognize a document type from stream contents.
372
373 handler: the handler in use.
374
375 stream: stream contents to recognise (may be NULL if document is
376 a directory).
377
378 dir: directory context from which stream is loaded.
379
380 recognize_state: pointer to retrieve opaque state that may be used
381 by the open routine, or NULL.
382
383 free_recognize_state: pointer to retrieve a function pointer to
384 free the opaque state, or NULL.
385
386 Note: state and free_state should either both be NULL or
387 both be non-NULL!
388
389 Returns a number between 0 (not recognized) and 100
390 (fully recognized) based on how certain the recognizer
391 is that this is of the required type.
392 */
393 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);
394
395 /**
396 Finalise a document handler.
397
398 This will be called on shutdown for a document handler to
399 release resources. This should cope with being called with NULL.
400
401 opaque: The value previously returned by the init call.
402 */
403 typedef void (fz_document_handler_fin_fn)(fz_context *ctx, const fz_document_handler *handler);
404
405
406
407 /**
408 Type for a function to be called when processing an already opened page.
409 See fz_process_opened_pages.
410 */
411 typedef void *(fz_process_opened_page_fn)(fz_context *ctx, fz_page *page, void *state);
412
413 /**
414 Register a handler for a document type.
415
416 handler: The handler to register. This must live on for the duration of the
417 use of this handler. It will be passed back to the handler for calls so
418 the caller can use it to retrieve state.
419 */
420 void fz_register_document_handler(fz_context *ctx, const fz_document_handler *handler);
421
422 /**
423 Register handlers for all the standard document types supported in
424 this build.
425 */
426 void fz_register_document_handlers(fz_context *ctx);
427
428 /**
429 Given a magic find a document handler that can handle a
430 document of this type.
431
432 magic: Can be a filename extension (including initial period) or
433 a mimetype.
434 */
435 const fz_document_handler *fz_recognize_document(fz_context *ctx, const char *magic);
436
437 /**
438 Given a filename find a document handler that can handle a
439 document of this type.
440
441 filename: The filename of the document. This will be opened and sampled
442 to check data.
443 */
444 const fz_document_handler *fz_recognize_document_content(fz_context *ctx, const char *filename);
445
446 /**
447 Given a magic find a document handler that can handle a
448 document of this type.
449
450 stream: the file stream to sample. May be NULL if the document is
451 a directory.
452
453 magic: Can be a filename extension (including initial period) or
454 a mimetype.
455 */
456 const fz_document_handler *fz_recognize_document_stream_content(fz_context *ctx, fz_stream *stream, const char *magic);
457
458 /**
459 Given a magic find a document handler that can handle a
460 document of this type.
461
462 stream: the file stream to sample. May be NULL if the document is
463 a directory.
464
465 dir: an fz_archive representing the directory from which the
466 stream was opened (or NULL).
467
468 magic: Can be a filename extension (including initial period) or
469 a mimetype.
470 */
471 const fz_document_handler *fz_recognize_document_stream_and_dir_content(fz_context *ctx, fz_stream *stream, fz_archive *dir, const char *magic);
472
473 /**
474 Open a document file and read its basic structure so pages and
475 objects can be located. MuPDF will try to repair broken
476 documents (without actually changing the file contents).
477
478 The returned fz_document is used when calling most other
479 document related functions.
480
481 filename: a path to a file as it would be given to open(2).
482 */
483 fz_document *fz_open_document(fz_context *ctx, const char *filename);
484
485 /**
486 Open a document file and read its basic structure so pages and
487 objects can be located. MuPDF will try to repair broken
488 documents (without actually changing the file contents).
489
490 The returned fz_document is used when calling most other
491 document related functions.
492
493 filename: a path to a file as it would be given to open(2).
494 */
495 fz_document *fz_open_accelerated_document(fz_context *ctx, const char *filename, const char *accel);
496
497 /**
498 Open a document using the specified stream object rather than
499 opening a file on disk.
500
501 magic: a string used to detect document type; either a file name
502 or mime-type.
503
504 stream: a stream representing the contents of the document file.
505
506 NOTE: The caller retains ownership of 'stream' - the document will take its
507 own reference if required.
508 */
509 fz_document *fz_open_document_with_stream(fz_context *ctx, const char *magic, fz_stream *stream);
510
511 /**
512 Open a document using the specified stream object rather than
513 opening a file on disk.
514
515 magic: a string used to detect document type; either a file name
516 or mime-type.
517
518 stream: a stream representing the contents of the document file.
519
520 dir: a 'directory context' for those filetypes that need it.
521
522 NOTE: The caller retains ownership of 'stream' and 'dir' - the document will
523 take its own references if required.
524 */
525 fz_document *fz_open_document_with_stream_and_dir(fz_context *ctx, const char *magic, fz_stream *stream, fz_archive *dir);
526
527 /**
528 Open a document using a buffer rather than opening a file on disk.
529 */
530 fz_document *fz_open_document_with_buffer(fz_context *ctx, const char *magic, fz_buffer *buffer);
531
532 /**
533 Open a document using the specified stream object rather than
534 opening a file on disk.
535
536 magic: a string used to detect document type; either a file name
537 or mime-type.
538
539 stream: a stream of the document contents.
540
541 accel: NULL, or a stream of the 'accelerator' contents for this document.
542
543 NOTE: The caller retains ownership of 'stream' and 'accel' - the document will
544 take its own references if required.
545 */
546 fz_document *fz_open_accelerated_document_with_stream(fz_context *ctx, const char *magic, fz_stream *stream, fz_stream *accel);
547
548 /**
549 Open a document using the specified stream object rather than
550 opening a file on disk.
551
552 magic: a string used to detect document type; either a file name
553 or mime-type.
554
555 stream: a stream of the document contents.
556
557 accel: NULL, or a stream of the 'accelerator' contents for this document.
558
559 dir: NULL, or the 'directory context' for the stream contents.
560
561 NOTE: The caller retains ownership of 'stream', 'accel' and 'dir' - the document will
562 take its own references if required.
563 */
564 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);
565
566 /**
567 Query if the document supports the saving of accelerator data.
568 */
569 int fz_document_supports_accelerator(fz_context *ctx, fz_document *doc);
570
571 /**
572 Save accelerator data for the document to a given file.
573 */
574 void fz_save_accelerator(fz_context *ctx, fz_document *doc, const char *accel);
575
576 /**
577 Output accelerator data for the document to a given output
578 stream.
579 */
580 void fz_output_accelerator(fz_context *ctx, fz_document *doc, fz_output *accel);
581
582 /**
583 New documents are typically created by calls like
584 foo_new_document(fz_context *ctx, ...). These work by
585 deriving a new document type from fz_document, for instance:
586 typedef struct { fz_document base; ...extras... } foo_document;
587 These are allocated by calling
588 fz_new_derived_document(ctx, foo_document)
589 */
590 void *fz_new_document_of_size(fz_context *ctx, int size);
591 #define fz_new_derived_document(C,M) ((M*)Memento_label(fz_new_document_of_size(C, sizeof(M)), #M))
592
593 /**
594 Increment the document reference count. The same pointer is
595 returned.
596
597 Never throws exceptions.
598 */
599 fz_document *fz_keep_document(fz_context *ctx, fz_document *doc);
600
601 /**
602 Decrement the document reference count. When the reference
603 count reaches 0, the document and all it's references are
604 freed.
605
606 Never throws exceptions.
607 */
608 void fz_drop_document(fz_context *ctx, fz_document *doc);
609
610 /**
611 Check if a document is encrypted with a
612 non-blank password.
613 */
614 int fz_needs_password(fz_context *ctx, fz_document *doc);
615
616 /**
617 Test if the given password can decrypt the document.
618
619 password: The password string to be checked. Some document
620 specifications do not specify any particular text encoding, so
621 neither do we.
622
623 Returns 0 for failure to authenticate, non-zero for success.
624
625 For PDF documents, further information can be given by examining
626 the bits in the return code.
627
628 Bit 0 => No password required
629 Bit 1 => User password authenticated
630 Bit 2 => Owner password authenticated
631 */
632 int fz_authenticate_password(fz_context *ctx, fz_document *doc, const char *password);
633
634 /**
635 Load the hierarchical document outline.
636
637 Should be freed by fz_drop_outline.
638 */
639 fz_outline *fz_load_outline(fz_context *ctx, fz_document *doc);
640
641 /**
642 Get an iterator for the document outline.
643
644 Should be freed by fz_drop_outline_iterator.
645 */
646 fz_outline_iterator *fz_new_outline_iterator(fz_context *ctx, fz_document *doc);
647
648 /**
649 Is the document reflowable.
650
651 Returns 1 to indicate reflowable documents, otherwise 0.
652 */
653 int fz_is_document_reflowable(fz_context *ctx, fz_document *doc);
654
655 /**
656 Layout reflowable document types.
657
658 w, h: Page size in points.
659 em: Default font size in points.
660 */
661 void fz_layout_document(fz_context *ctx, fz_document *doc, float w, float h, float em);
662
663 /**
664 Create a bookmark for the given page, which can be used to find
665 the same location after the document has been laid out with
666 different parameters.
667 */
668 fz_bookmark fz_make_bookmark(fz_context *ctx, fz_document *doc, fz_location loc);
669
670 /**
671 Find a bookmark and return its page number.
672 */
673 fz_location fz_lookup_bookmark(fz_context *ctx, fz_document *doc, fz_bookmark mark);
674
675 /**
676 Return the number of pages in document
677
678 May return 0 for documents with no pages.
679 */
680 int fz_count_pages(fz_context *ctx, fz_document *doc);
681
682 /**
683 Resolve an internal link to a page number, location, and possible viewing parameters.
684
685 Returns location (-1,-1) if the URI cannot be resolved.
686 */
687 fz_link_dest fz_resolve_link_dest(fz_context *ctx, fz_document *doc, const char *uri);
688
689 /**
690 Format an internal link to a page number, location, and possible viewing parameters,
691 suitable for use with fz_create_link.
692
693 Returns a newly allocated string that the caller must free.
694 */
695 char *fz_format_link_uri(fz_context *ctx, fz_document *doc, fz_link_dest dest);
696
697 /**
698 Resolve an internal link to a page number.
699
700 xp, yp: Pointer to store coordinate of destination on the page.
701
702 Returns (-1,-1) if the URI cannot be resolved.
703 */
704 fz_location fz_resolve_link(fz_context *ctx, fz_document *doc, const char *uri, float *xp, float *yp);
705
706 /**
707 Run the document structure through a device.
708
709 doc: Document in question.
710
711 dev: Device obtained from fz_new_*_device.
712
713 cookie: Communication mechanism between caller and library.
714 Intended for multi-threaded applications, while
715 single-threaded applications set cookie to NULL. The
716 caller may abort an ongoing rendering of a page. Cookie also
717 communicates progress information back to the caller. The
718 fields inside cookie are continually updated while the page is
719 rendering.
720 */
721 void fz_run_document_structure(fz_context *ctx, fz_document *doc, fz_device *dev, fz_cookie *cookie);
722
723 /**
724 Function to get the location for the last page in the document.
725 Using this can be far more efficient in some cases than calling
726 fz_count_pages and using the page number.
727 */
728 fz_location fz_last_page(fz_context *ctx, fz_document *doc);
729
730 /**
731 Function to get the location of the next page (allowing for the
732 end of chapters etc). If at the end of the document, returns the
733 current location.
734 */
735 fz_location fz_next_page(fz_context *ctx, fz_document *doc, fz_location loc);
736
737 /**
738 Function to get the location of the previous page (allowing for
739 the end of chapters etc). If already at the start of the
740 document, returns the current page.
741 */
742 fz_location fz_previous_page(fz_context *ctx, fz_document *doc, fz_location loc);
743
744 /**
745 Clamps a location into valid chapter/page range. (First clamps
746 the chapter into range, then the page into range).
747 */
748 fz_location fz_clamp_location(fz_context *ctx, fz_document *doc, fz_location loc);
749
750 /**
751 Converts from page number to chapter+page. This may cause many
752 chapters to be laid out in order to calculate the number of
753 pages within those chapters.
754 */
755 fz_location fz_location_from_page_number(fz_context *ctx, fz_document *doc, int number);
756
757 /**
758 Converts from chapter+page to page number. This may cause many
759 chapters to be laid out in order to calculate the number of
760 pages within those chapters.
761 */
762 int fz_page_number_from_location(fz_context *ctx, fz_document *doc, fz_location loc);
763
764 /**
765 Load a given page number from a document. This may be much less
766 efficient than loading by location (chapter+page) for some
767 document types.
768 */
769 fz_page *fz_load_page(fz_context *ctx, fz_document *doc, int number);
770
771 /**
772 Return the number of chapters in the document.
773 At least 1.
774 */
775 int fz_count_chapters(fz_context *ctx, fz_document *doc);
776
777 /**
778 Return the number of pages in a chapter.
779 May return 0.
780 */
781 int fz_count_chapter_pages(fz_context *ctx, fz_document *doc, int chapter);
782
783 /**
784 Load a page.
785
786 After fz_load_page is it possible to retrieve the size of the
787 page using fz_bound_page, or to render the page using
788 fz_run_page_*. Free the page by calling fz_drop_page.
789
790 chapter: chapter number, 0 is the first chapter of the document.
791 number: page number, 0 is the first page of the chapter.
792 */
793 fz_page *fz_load_chapter_page(fz_context *ctx, fz_document *doc, int chapter, int page);
794
795 /**
796 Load the list of links for a page.
797
798 Returns a linked list of all the links on the page, each with
799 its clickable region and link destination. Each link is
800 reference counted so drop and free the list of links by
801 calling fz_drop_link on the pointer return from fz_load_links.
802
803 page: Page obtained from fz_load_page.
804 */
805 fz_link *fz_load_links(fz_context *ctx, fz_page *page);
806
807 /**
808 Different document types will be implemented by deriving from
809 fz_page. This macro allocates such derived structures, and
810 initialises the base sections.
811 */
812 fz_page *fz_new_page_of_size(fz_context *ctx, int size, fz_document *doc);
813 #define fz_new_derived_page(CTX,TYPE,DOC) \
814 ((TYPE *)Memento_label(fz_new_page_of_size(CTX,sizeof(TYPE),DOC),#TYPE))
815
816 /**
817 Determine the size of a page at 72 dpi.
818 */
819 fz_rect fz_bound_page(fz_context *ctx, fz_page *page);
820 fz_rect fz_bound_page_box(fz_context *ctx, fz_page *page, fz_box_type box);
821
822 /**
823 Run a page through a device.
824
825 page: Page obtained from fz_load_page.
826
827 dev: Device obtained from fz_new_*_device.
828
829 transform: Transform to apply to page. May include for example
830 scaling and rotation, see fz_scale, fz_rotate and fz_concat.
831 Set to fz_identity if no transformation is desired.
832
833 cookie: Communication mechanism between caller and library
834 rendering the page. Intended for multi-threaded applications,
835 while single-threaded applications set cookie to NULL. The
836 caller may abort an ongoing rendering of a page. Cookie also
837 communicates progress information back to the caller. The
838 fields inside cookie are continually updated while the page is
839 rendering.
840 */
841 void fz_run_page(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);
842
843 /**
844 Run a page through a device. Just the main
845 page content, without the annotations, if any.
846
847 page: Page obtained from fz_load_page.
848
849 dev: Device obtained from fz_new_*_device.
850
851 transform: Transform to apply to page. May include for example
852 scaling and rotation, see fz_scale, fz_rotate and fz_concat.
853 Set to fz_identity if no transformation is desired.
854
855 cookie: Communication mechanism between caller and library
856 rendering the page. Intended for multi-threaded applications,
857 while single-threaded applications set cookie to NULL. The
858 caller may abort an ongoing rendering of a page. Cookie also
859 communicates progress information back to the caller. The
860 fields inside cookie are continually updated while the page is
861 rendering.
862 */
863 void fz_run_page_contents(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);
864
865 /**
866 Run the annotations on a page through a device.
867 */
868 void fz_run_page_annots(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);
869
870 /**
871 Run the widgets on a page through a device.
872 */
873 void fz_run_page_widgets(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie);
874
875 /**
876 Increment the reference count for the page. Returns the same
877 pointer.
878
879 Never throws exceptions.
880 */
881 fz_page *fz_keep_page(fz_context *ctx, fz_page *page);
882
883 /**
884 Decrements the reference count for the page. When the reference
885 count hits 0, the page and its references are freed.
886
887 Never throws exceptions.
888 */
889 void fz_drop_page(fz_context *ctx, fz_page *page);
890
891 /**
892 Get the presentation details for a given page.
893
894 transition: A pointer to a transition struct to fill out.
895
896 duration: A pointer to a place to set the page duration in
897 seconds. Will be set to 0 if no transition is specified for the
898 page.
899
900 Returns: a pointer to the transition structure, or NULL if there
901 is no transition specified for the page.
902 */
903 fz_transition *fz_page_presentation(fz_context *ctx, fz_page *page, fz_transition *transition, float *duration);
904
905 /**
906 Get page label for a given page.
907 */
908 const char *fz_page_label(fz_context *ctx, fz_page *page, char *buf, int size);
909
910 /**
911 Check permission flags on document.
912 */
913 int fz_has_permission(fz_context *ctx, fz_document *doc, fz_permission p);
914
915 /**
916 Retrieve document meta data strings.
917
918 doc: The document to query.
919
920 key: Which meta data key to retrieve...
921
922 Basic information:
923 'format' -- Document format and version.
924 'encryption' -- Description of the encryption used.
925
926 From the document information dictionary:
927 'info:Title'
928 'info:Author'
929 'info:Subject'
930 'info:Keywords'
931 'info:Creator'
932 'info:Producer'
933 'info:CreationDate'
934 'info:ModDate'
935
936 buf: The buffer to hold the results (a nul-terminated UTF-8
937 string).
938
939 size: Size of 'buf'.
940
941 Returns the number of bytes need to store the string plus terminator
942 (will be larger than 'size' if the output was truncated), or -1 if the
943 key is not recognized or found.
944 */
945 int fz_lookup_metadata(fz_context *ctx, fz_document *doc, const char *key, char *buf, size_t size);
946
947 #define FZ_META_FORMAT "format"
948 #define FZ_META_ENCRYPTION "encryption"
949
950 #define FZ_META_INFO "info:"
951 #define FZ_META_INFO_TITLE "info:Title"
952 #define FZ_META_INFO_AUTHOR "info:Author"
953 #define FZ_META_INFO_SUBJECT "info:Subject"
954 #define FZ_META_INFO_KEYWORDS "info:Keywords"
955 #define FZ_META_INFO_CREATOR "info:Creator"
956 #define FZ_META_INFO_PRODUCER "info:Producer"
957 #define FZ_META_INFO_CREATIONDATE "info:CreationDate"
958 #define FZ_META_INFO_MODIFICATIONDATE "info:ModDate"
959
960 void fz_set_metadata(fz_context *ctx, fz_document *doc, const char *key, const char *value);
961
962 /**
963 Find the output intent colorspace if the document has defined
964 one.
965
966 Returns a borrowed reference that should not be dropped, unless
967 it is kept first.
968 */
969 fz_colorspace *fz_document_output_intent(fz_context *ctx, fz_document *doc);
970
971 /**
972 Get the separations details for a page.
973 This will be NULL, unless the format specifically supports
974 separations (such as PDF files). May be NULL even
975 so, if there are no separations on a page.
976
977 Returns a reference that must be dropped.
978 */
979 fz_separations *fz_page_separations(fz_context *ctx, fz_page *page);
980
981 /**
982 Query if a given page requires overprint.
983 */
984 int fz_page_uses_overprint(fz_context *ctx, fz_page *page);
985
986 /**
987 Create a new link on a page.
988 */
989 fz_link *fz_create_link(fz_context *ctx, fz_page *page, fz_rect bbox, const char *uri);
990
991 /**
992 Delete an existing link on a page.
993 */
994 void fz_delete_link(fz_context *ctx, fz_page *page, fz_link *link);
995
996 /**
997 Iterates over all opened pages of the document, calling the
998 provided callback for each page for processing. If the callback
999 returns non-NULL then the iteration stops and that value is returned
1000 to the called of fz_process_opened_pages().
1001
1002 The state pointer provided to fz_process_opened_pages() is
1003 passed on to the callback but is owned by the caller.
1004
1005 Returns the first non-NULL value returned by the callback,
1006 or NULL if the callback returned NULL for all opened pages.
1007 */
1008 void *fz_process_opened_pages(fz_context *ctx, fz_document *doc, fz_process_opened_page_fn *process_openend_page, void *state);
1009
1010 /* Implementation details: subject to change. */
1011
1012 /**
1013 Structure definition is public so other classes can
1014 derive from it. Do not access the members directly.
1015 */
1016 struct fz_page
1017 {
1018 int refs;
1019 fz_document *doc; /* kept reference to parent document. Guaranteed non-NULL. */
1020 int chapter; /* chapter number */
1021 int number; /* page number in chapter */
1022 int incomplete; /* incomplete from progressive loading; don't cache! */
1023 int in_doc; /* page has been placed into the document */
1024 fz_page_drop_page_fn *drop_page;
1025 fz_page_bound_page_fn *bound_page;
1026 fz_page_run_page_fn *run_page_contents;
1027 fz_page_run_page_fn *run_page_annots;
1028 fz_page_run_page_fn *run_page_widgets;
1029 fz_page_load_links_fn *load_links;
1030 fz_page_page_presentation_fn *page_presentation;
1031 fz_page_control_separation_fn *control_separation;
1032 fz_page_separation_disabled_fn *separation_disabled;
1033 fz_page_separations_fn *separations;
1034 fz_page_uses_overprint_fn *overprint;
1035 fz_page_create_link_fn *create_link;
1036 fz_page_delete_link_fn *delete_link;
1037
1038 /* linked list of currently open pages. This list is maintained
1039 * by fz_load_chapter_page and fz_drop_page. All pages hold a
1040 * kept reference to the document, so the document cannot disappear
1041 * while pages exist. 'Incomplete' pages are NOT kept in this
1042 * list. */
1043 fz_page **prev, *next;
1044 };
1045
1046 /**
1047 Structure definition is public so other classes can
1048 derive from it. Callers should not access the members
1049 directly, though implementations will need initialize
1050 functions directly.
1051 */
1052 struct fz_document
1053 {
1054 int refs;
1055 fz_document_drop_fn *drop_document;
1056 fz_document_needs_password_fn *needs_password;
1057 fz_document_authenticate_password_fn *authenticate_password;
1058 fz_document_has_permission_fn *has_permission;
1059 fz_document_load_outline_fn *load_outline;
1060 fz_document_outline_iterator_fn *outline_iterator;
1061 fz_document_layout_fn *layout;
1062 fz_document_make_bookmark_fn *make_bookmark;
1063 fz_document_lookup_bookmark_fn *lookup_bookmark;
1064 fz_document_resolve_link_dest_fn *resolve_link_dest;
1065 fz_document_format_link_uri_fn *format_link_uri;
1066 fz_document_count_chapters_fn *count_chapters;
1067 fz_document_count_pages_fn *count_pages;
1068 fz_document_load_page_fn *load_page;
1069 fz_document_page_label_fn *page_label;
1070 fz_document_lookup_metadata_fn *lookup_metadata;
1071 fz_document_set_metadata_fn *set_metadata;
1072 fz_document_output_intent_fn *get_output_intent;
1073 fz_document_output_accelerator_fn *output_accelerator;
1074 fz_document_run_structure_fn *run_structure;
1075 fz_document_as_pdf_fn *as_pdf;
1076 int did_layout;
1077 int is_reflowable;
1078 int id;
1079
1080 /* Linked list of currently open pages. These are not
1081 * references, but just a linked list of open pages,
1082 * maintained by fz_load_chapter_page, and fz_drop_page.
1083 * Every page holds a kept reference to the document, so
1084 * the document cannot be destroyed while a page exists.
1085 * Incomplete pages are NOT inserted into this list, but
1086 * do still hold a real document reference. */
1087 fz_page *open;
1088 };
1089
1090 struct fz_document_handler
1091 {
1092 /* These fields are initialised by the handler when it is registered. */
1093 fz_document_recognize_fn *recognize;
1094 fz_document_open_fn *open;
1095 const char **extensions;
1096 const char **mimetypes;
1097 fz_document_recognize_content_fn *recognize_content;
1098 int wants_dir;
1099 int wants_file;
1100 fz_document_handler_fin_fn *fin;
1101 };
1102
1103 #endif