Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/helpers/mu-office-lib.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-2021 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 /**
24 * Mu Office Library
25 *
26 * This helper layer provides an API for loading, and displaying
27 * a file. It is deliberately as identical as possible to the
28 * smart-office-lib.h header file in Smart Office to facilitate
29 * a product which can use both Smart Office and MuPDF.
30 */
31
32 #ifndef MU_OFFICE_LIB_H
33 #define MU_OFFICE_LIB_H
34
35 /*
36 * General use
37 *
38 * This library uses threads but is not thread safe for the caller. All
39 * calls should be made from a single thread. Some calls allow the user
40 * to arrange for their own functions to be called back from the library;
41 * often the users functions will be called back from a different thread. If
42 * a call into the library is required in response to information from a
43 * callback, it is the responsibility of the user to arrange for those
44 * library calls to be made on the same thread as for other library calls.
45 * Calls back into the library from a callback are not permitted.
46 *
47 * There are two main modes of use. In interactive windowing systems, it
48 * is usual for the app developers code to be called on the main UI thread.
49 * It is from the UI thread that all library calls should be made. Such
50 * systems usually provide a way to post a call onto the UI thread. That
51 * is the best way to respond to a callback from the library.
52 *
53 * The other mode of use is for plain executables that might wish to
54 * (say) generate images of all the pages of a document. This can
55 * be achieved, without use of callbacks, using the few synchronous
56 * calls. E.g., MuOfficeDoc_getNumPages will wait for background document
57 * loading to complete before returning the total number of pages and
58 * MuOfficeRender_destroy will wait for background rendering to complete
59 * before returning.
60 */
61
62 #include <stddef.h> /* For size_t */
63 #include "mupdf/fitz.h" /* For fz_context/fz_document/fz_page */
64
65 /** Error type returned from most MuOffice functions
66 *
67 * 0 means no error
68 *
69 * non-zero values mean an error occurred. The exact value is an indication
70 * of what went wrong and should be included in bug reports or support
71 * queries. Library users should not test this value except for 0,
72 * non-zero and any explicitly documented values.
73 */
74 typedef int MuError;
75
76 /** Errors returned to MuOfficeLoadingErrorFn
77 *
78 * Other values may also be returned.
79 */
80 typedef enum MuOfficeDocErrorType
81 {
82 MuOfficeDocErrorType_NoError = 0,
83 MuOfficeDocErrorType_UnsupportedDocumentType = 1,
84 MuOfficeDocErrorType_EmptyDocument = 2,
85 MuOfficeDocErrorType_UnableToLoadDocument = 4,
86 MuOfficeDocErrorType_UnsupportedEncryption = 5,
87 MuOfficeDocErrorType_Aborted = 6,
88 MuOfficeDocErrorType_OutOfMemory = 7,
89
90 /* FIXME: Additional ones that should be backported to
91 * smart-office-lib.h */
92 MuOfficeDocErrorType_IllegalArgument = 8,
93
94 /** A password is required to open this document.
95 *
96 * The app should provide it using MuOffice_providePassword
97 * or if it doesn't want to proceed call MuOfficeDoc_destroy or
98 * MuOfficeDoc_abortLoad.
99 */
100 MuOfficeDocErrorType_PasswordRequest = 0x1000
101 } MuOfficeDocErrorType;
102
103 /**
104 *Structure holding the detail of the layout of a bitmap. b5g6r5 is assumed.
105 */
106 typedef struct
107 {
108 void *memptr;
109 int width;
110 int height;
111 int lineSkip;
112 } MuOfficeBitmap;
113
114 /**
115 * Structure defining a point
116 *
117 * x x coord of point
118 * y y coord of point
119 */
120 typedef struct
121 {
122 float x;
123 float y;
124 } MuOfficePoint;
125
126 /**
127 * Structure defining a rectangle
128 *
129 * x x coord of top left of area within the page
130 * y y coord of top left of area within the page
131 * width width of area
132 * height height of area
133 */
134 typedef struct
135 {
136 float x;
137 float y;
138 float width;
139 float height;
140 } MuOfficeBox;
141
142 typedef enum MuOfficePointType
143 {
144 MuOfficePointType_MoveTo,
145 MuOfficePointType_LineTo
146 } MuOfficePointType;
147
148 typedef struct
149 {
150 float x;
151 float y;
152 MuOfficePointType type;
153 } MuOfficePathPoint;
154
155 /**
156 * Structure defining what area of a page should be rendered and to what
157 * area of the bitmap
158 *
159 * origin coordinates of the document origin within the bitmap
160 * renderArea the part of the bitmap to which to render
161 */
162 typedef struct
163 {
164 MuOfficePoint origin;
165 MuOfficeBox renderArea;
166 } MuOfficeRenderArea;
167
168 typedef struct MuOfficeLib MuOfficeLib;
169 typedef struct MuOfficeDoc MuOfficeDoc;
170 typedef struct MuOfficePage MuOfficePage;
171 typedef struct MuOfficeRender MuOfficeRender;
172
173 /**
174 * Allocator function used by some functions to get blocks of memory.
175 *
176 * @param cookie data pointer passed in with the allocator.
177 * @param size the size of the required block.
178 *
179 * @returns as for malloc. (NULL implies OutOfMemory, or size == 0).
180 * Otherwise a pointer to an allocated block.
181 */
182 typedef void *(MuOfficeAllocFn)(void *cookie,
183 size_t size);
184
185 /**
186 * Callback function monitoring document loading
187 *
188 * Also called when the document is edited, either adding or
189 * removing pages, with the pagesLoaded value decreasing
190 * in the page-removal case.
191 *
192 * @param cookie the data pointer that was originally passed
193 * to MuOfficeLib_loadDocument.
194 * @param pagesLoaded the number of pages so far discovered.
195 * @param complete whether loading has completed. If this flag
196 * is set, pagesLoaded is the actual number of
197 * pages in the document.
198 */
199 typedef void (MuOfficeLoadingProgressFn)(void *cookie,
200 int pagesLoaded,
201 int complete);
202
203 /**
204 * Callback function used to monitor errors in the process of loading
205 * a document.
206 *
207 * @param cookie the data pointer that was originally passed
208 * to MuOfficeLib_loadDocument.
209 * @param error the error being reported
210 */
211 typedef void (MuOfficeLoadingErrorFn)( void *cookie,
212 MuOfficeDocErrorType error);
213
214 /**
215 * Callback function used to monitor page changes
216 *
217 * @param cookie the data pointer that was originally passed
218 * to MuOfficeDoc_getPage.
219 * @param area the area that has changed.
220 */
221 typedef void (MuOfficePageUpdateFn)( void *cookie,
222 const MuOfficeBox *area);
223
224 /**
225 * Callback function used to monitor a background render of a
226 * document page. The function is called exactly once.
227 *
228 * @param cookie the data pointer that was originally passed
229 * to MuOfficeDoc_monitorRenderProgress.
230 * @param error error returned from the rendering process
231 */
232 typedef void (MuOfficeRenderProgressFn)(void *cookie,
233 MuError error);
234
235 /**
236 * Document types
237 *
238 * Keep in sync with smart-office-lib.h
239 */
240 typedef enum
241 {
242 MuOfficeDocType_PDF,
243 MuOfficeDocType_XPS,
244 MuOfficeDocType_IMG
245 } MuOfficeDocType;
246
247 /**
248 * The possible results of a save operation
249 */
250 typedef enum MuOfficeSaveResult
251 {
252 MuOfficeSave_Succeeded,
253 MuOfficeSave_Error,
254 MuOfficeSave_Cancelled
255 }
256 MuOfficeSaveResult;
257
258 /**
259 * Callback function used to monitor save operations.
260 *
261 * @param cookie the data pointer that was originally passed to
262 * MuOfficeDoc_save.
263 * @param result the result of the save operation
264 */
265 typedef void (MuOfficeSaveResultFn)( void *cookie,
266 MuOfficeSaveResult result);
267
268 /**
269 * Create a MuOfficeLib instance.
270 *
271 * @param pMu address of variable to
272 * receive the created instance
273 *
274 * @return error indication - 0 for success
275 */
276 MuError MuOfficeLib_create(MuOfficeLib **pMu);
277
278 /**
279 * Destroy a MuOfficeLib instance
280 *
281 * @param mu the instance to destroy
282 */
283 void MuOfficeLib_destroy(MuOfficeLib *mu);
284
285 /**
286 * Find the type of a file given its filename extension.
287 *
288 * @param path path to the file (in utf8)
289 *
290 * @return a valid MuOfficeDocType value, or MuOfficeDocType_Other
291 */
292 MuOfficeDocType MuOfficeLib_getDocTypeFromFileExtension(const char *path);
293
294 /**
295 * Return a list of filename extensions supported by Mu Office library.
296 *
297 * @return comma-delimited list of extensions, without the leading ".".
298 * The caller should free the returned pointer..
299 */
300 char * MuOfficeLib_getSupportedFileExtensions(void);
301
302 /**
303 * Load a document
304 *
305 * Call will return immediately, leaving the document loading
306 * in the background
307 *
308 * @param mu a MuOfficeLib instance
309 * @param path path to the file to load (in utf8)
310 * @param progressFn callback for monitoring progress
311 * @param errorFn callback for monitoring errors
312 * @param cookie a pointer to pass back to the callbacks
313 * @param pDoc address for return of a MuOfficeDoc object
314 *
315 * @return error indication - 0 for success
316 *
317 * The progress callback may be called several times, with increasing
318 * values of pagesLoaded. Unless MuOfficeDoc_destroy is called,
319 * before loading completes, a call with "completed" set to true
320 * is guaranteed.
321 *
322 * Once MuOfficeDoc_destroy is called there will be no
323 * further callbacks.
324 *
325 * Alternatively, in a synchronous context, MuOfficeDoc_getNumPages
326 * can be called to wait for loading to complete and return the total
327 * number of pages. In this mode of use, progressFn can be NULL. 
328 */
329 MuError MuOfficeLib_loadDocument(MuOfficeLib *mu,
330 const char *path,
331 MuOfficeLoadingProgressFn *progressFn,
332 MuOfficeLoadingErrorFn *errorFn,
333 void *cookie,
334 MuOfficeDoc **pDoc);
335
336 /**
337 * Perform MuPDF native operations on a given MuOfficeLib
338 * instance.
339 *
340 * The function is called with a fz_context value that can
341 * be safely used (i.e. the context is cloned/dropped
342 * appropriately around the call). The function should signal
343 * errors by fz_throw-ing.
344 *
345 * @param mu the MuOfficeLib instance.
346 * @param fn the function to call to run the operations.
347 * @param arg Opaque data pointer.
348 *
349 * @return error indication - 0 for success
350 */
351 MuError MuOfficeLib_run(MuOfficeLib *mu, void (*fn)(fz_context *ctx, void *arg), void *arg);
352
353 /**
354 * Provide the password for a document
355 *
356 * This function should be called to provide a password with a document
357 * error if MuOfficeError_PasswordRequired is received.
358 *
359 * If a password is requested again, this means the password was incorrect.
360 *
361 * @param doc the document object
362 * @param password the password (UTF8 encoded)
363 * @return error indication - 0 for success
364 */
365 int MuOfficeDoc_providePassword(MuOfficeDoc *doc, const char *password);
366
367 /**
368 * Return the type of an open document
369 *
370 * @param doc the document object
371 *
372 * @return the document type
373 */
374 MuOfficeDocType MuOfficeDoc_docType(MuOfficeDoc *doc);
375
376 /**
377 * Return the number of pages of a document
378 *
379 * This function waits for document loading to complete before returning
380 * the result. It may block the calling thread for a significant period of
381 * time. To avoid blocking, this call should be avoided in favour of using
382 * the MuOfficeLib_loadDocument callbacks to monitor loading.
383 *
384 * If background loading fails, the associated error will be returned
385 * from this call.
386 *
387 * @param doc the document
388 * @param pNumPages address for return of the number of pages
389 *
390 * @return error indication - 0 for success
391 */
392 MuError MuOfficeDoc_getNumPages(MuOfficeDoc *doc, int *pNumPages);
393
394 /**
395 * Determine if the document has been modified
396 *
397 * @param doc the document
398 *
399 * @return modified flag
400 */
401 int MuOfficeDoc_hasBeenModified(MuOfficeDoc *doc);
402
403 /**
404 * Start a save operation
405 *
406 * @param doc the document
407 * @param path path of the file to which to save
408 * @param resultFn callback used to report completion
409 * @param cookie a pointer to pass to the callback
410 *
411 * @return error indication - 0 for success
412 */
413 MuError MuOfficeDoc_save(MuOfficeDoc *doc,
414 const char *path,
415 MuOfficeSaveResultFn *resultFn,
416 void *cookie);
417
418 /**
419 * Stop a document loading. The document is not destroyed, but
420 * no further content will be read from the file.
421 *
422 * @param doc the MuOfficeDoc object
423 */
424 void MuOfficeDoc_abortLoad(MuOfficeDoc *doc);
425
426 /**
427 * Destroy a MuOfficeDoc object. Loading of the document is shutdown
428 * and no further callbacks will be issued for the specified object.
429 *
430 * @param doc the MuOfficeDoc object
431 */
432 void MuOfficeDoc_destroy(MuOfficeDoc *doc);
433
434 /**
435 * Get a page of a document
436 *
437 * @param doc the document object
438 * @param pageNumber the number of the page to load (lying in the
439 * range 0 to one less than the number of pages)
440 * @param updateFn Function to be called back when the page updates
441 * @param cookie Opaque value to pass for any updates
442 * @param pPage Address for return of the page object
443 *
444 * @return error indication - 0 for success
445 */
446 MuError MuOfficeDoc_getPage( MuOfficeDoc *doc,
447 int pageNumber,
448 MuOfficePageUpdateFn *updateFn,
449 void *cookie,
450 MuOfficePage **pPage);
451
452 /**
453 * Perform MuPDF native operations on a given document.
454 *
455 * The function is called with fz_context and fz_document
456 * values that can be safely used (i.e. the context is
457 * cloned/dropped appropriately around the function, and
458 * locking is used to ensure that no other threads are
459 * simultaneously using the document). Functions can
460 * signal errors by fz_throw-ing.
461 *
462 * Due to the locking, it is best to ensure that as little
463 * time is taken here as possible (i.e. if you fetch some
464 * data and then spend a long time processing it, it is
465 * probably best to fetch the data using MuOfficeDoc_run
466 * and then process it outside). This avoids potentially
467 * blocking the UI.
468 *
469 * @param doc the document object.
470 * @param fn the function to call with fz_context/fz_document
471 * values.
472 * @param arg Opaque data pointer.
473 *
474 * @return error indication - 0 for success
475 */
476 MuError MuOfficeDoc_run(MuOfficeDoc *doc, void (*fn)(fz_context *ctx, fz_document *doc, void *arg), void *arg);
477
478 /**
479 * Destroy a page object
480 *
481 * Note this does not delete or remove the page from the document.
482 * It simply destroys the page object which is merely a reference
483 * to the page.
484 *
485 * @param page the page object
486 */
487 void MuOfficePage_destroy(MuOfficePage *page);
488
489 /**
490 * Get the size of a page in pixels
491 *
492 * This returns the size of the page in pixels. Pages can be rendered
493 * with a zoom factor. The returned value is the size of bitmap
494 * appropriate for rendering with a zoom of 1.0 and corresponds to
495 * 90 dpi. The returned values are not necessarily whole numbers.
496 *
497 * @param page the page object
498 * @param pWidth address for return of the width
499 * @param pHeight address for return of the height
500 *
501 * @return error indication - 0 for success
502 */
503 MuError MuOfficePage_getSize( MuOfficePage *page,
504 float *pWidth,
505 float *pHeight);
506
507 /**
508 * Return the zoom factors necessary to render at to a given
509 * size in pixels. (deprecated)
510 *
511 * @param page the page object
512 * @param width the desired width
513 * @param height the desired height
514 * @param pXZoom Address for return of zoom necessary to fit width
515 * @param pYZoom Address for return of zoom necessary to fit height
516 *
517 * @return error indication - 0 for success
518 */
519 MuError MuOfficePage_calculateZoom( MuOfficePage *page,
520 int width,
521 int height,
522 float *pXZoom,
523 float *pYZoom);
524
525 /**
526 * Get the size of a page in pixels for a specified zoom factor
527 * (deprecated)
528 *
529 * This returns the size of bitmap that should be used to display
530 * the entire page at the given zoom factor. A zoom of 1.0
531 * corresponds to 90 dpi.
532 *
533 * @param page the page object
534 * @param zoom the zoom factor
535 * @param pWidth address for return of the width
536 * @param pHeight address for return of the height
537 *
538 * @return error indication - 0 for success
539 */
540 MuError MuOfficePage_getSizeForZoom( MuOfficePage *page,
541 float zoom,
542 int *pWidth,
543 int *pHeight);
544
545 /**
546 * Perform MuPDF native operations on a given page.
547 *
548 * The function is called with fz_context and fz_page
549 * values that can be safely used (i.e. the context is
550 * cloned/dropped appropriately around the function, and
551 * locking is used to ensure that no other threads are
552 * simultaneously using the document). Functions can
553 * signal errors by fz_throw-ing.
554 *
555 * Due to the locking, it is best to ensure that as little
556 * time is taken here as possible (i.e. if you fetch some
557 * data and then spend a long time processing it, it is
558 * probably best to fetch the data using MuOfficePage_run
559 * and then process it outside). This avoids potentially
560 * blocking the UI.
561 *
562 * @param page the page object.
563 * @param fn the function to call with fz_context/fz_document
564 * values.
565 * @param arg Opaque data pointer.
566 *
567 * @return error indication - 0 for success
568 */
569 MuError MuOfficePage_run(MuOfficePage *page, void (*fn)(fz_context *ctx, fz_page *page, void *arg), void *arg);
570
571 /**
572 * Schedule the rendering of an area of document page to
573 * an area of a bitmap.
574 *
575 * The alignment between page and bitmap is defined by specifying
576 * document's origin within the bitmap, possibly either positive or
577 * negative. A render object is returned via which the process can
578 * be monitored or terminated.
579 *
580 * The progress function is called exactly once per render in either
581 * the success or failure case.
582 *
583 * Note that, since a render object represents a running thread that
584 * needs access to the page, document, and library objects, it is important
585 * to call MuOfficeRender_destroy, not only before using or deallocating
586 * the bitmap, but also before calling MuOfficePage_destroy, etc..
587 *
588 * @param page the page to render
589 * @param zoom the zoom factor
590 * @param bitmap the bitmap
591 * @param area area to render
592 * @param progressFn the progress callback function
593 * @param cookie a pointer to pass to the callback function
594 * @param pRender Address for return of the render object
595 *
596 * @return error indication - 0 for success
597 */
598 MuError MuOfficePage_render( MuOfficePage *page,
599 float zoom,
600 const MuOfficeBitmap *bitmap,
601 const MuOfficeRenderArea *area,
602 MuOfficeRenderProgressFn *progressFn,
603 void *cookie,
604 MuOfficeRender **pRender);
605
606 /**
607 * Destroy a render
608 *
609 * This call destroys a MuOfficeRender object, aborting any current
610 * render.
611 *
612 * This call is intended to support an app dealing with a user quickly
613 * flicking through document pages. A render may be scheduled but, before
614 * completion, be found not to be needed. In that case the bitmap will
615 * need to be reused, which requires any existing render to be aborted.
616 * The call to MuOfficeRender_destroy will cut short the render and
617 * allow the bitmap to be reused immediately.
618 *
619 * @note If an active render thread is destroyed, it will be aborted.
620 * While fast, this is not an instant operation. For maximum
621 * responsiveness, it is best to 'abort' as soon as you realise you
622 * don't need the render, and to destroy when you get the callback.
623 *
624 * @param render The render object
625 */
626 void MuOfficeRender_destroy(MuOfficeRender *render);
627
628 /**
629 * Abort a render
630 *
631 * This call aborts any rendering currently underway. The 'render
632 * complete' callback (if any) given when the render was created will
633 * still be called. If a render has completed, this call will have no
634 * effect.
635 *
636 * This call will not block to wait for the render thread to stop, but
637 * will cause it to stop as soon as it can in the background.
638 *
639 * @note It is important not to start any new render to the same bitmap
640 * until the callback comes in (or until waitUntilComplete returns), as
641 * otherwise you can have multiple renders drawing to the same bitmap
642 * with unpredictable consequences.
643 *
644 * @param render The render object to abort
645 */
646 void MuOfficeRender_abort(MuOfficeRender *render);
647
648 /**
649 * Wait for a render to complete.
650 *
651 * This call will not return until rendering is complete, so on return
652 * the bitmap will contain the page image (assuming the render didn't
653 * run into an error condition) and will not be used further by any
654 * background processing. Any error during rendering will be returned
655 * from this function.
656 *
657 * This call may block the calling thread for a significant period of
658 * time. To avoid blocking, supply a progress-monitoring callback
659 * function to MuOfficePage_render.
660 *
661 * @param render The render object to destroy
662 * @return render error condition - 0 for no error.
663 */
664 MuError MuOfficeRender_waitUntilComplete(MuOfficeRender *render);
665
666 #endif /* SMART_OFFICE_LIB_H */