645 lines
21 KiB
C
645 lines
21 KiB
C
/**
|
||
* Mu Office Library
|
||
*
|
||
* This helper layer provides an API for loading, and displaying
|
||
* a file. It is deliberately as identical as possible to the
|
||
* smart-office-lib.h header file in Smart Office to facilitate
|
||
* a product which can use both Smart Office and MuPDF.
|
||
*/
|
||
|
||
#ifndef MU_OFFICE_LIB_H
|
||
#define MU_OFFICE_LIB_H
|
||
|
||
/*
|
||
* General use
|
||
*
|
||
* This library uses threads but is not thread safe for the caller. All
|
||
* calls should be made from a single thread. Some calls allow the user
|
||
* to arrange for their own functions to be called back from the library;
|
||
* often the users functions will be called back from a different thread. If
|
||
* a call into the library is required in response to information from a
|
||
* callback, it is the responsibility of the user to arrange for those
|
||
* library calls to be made on the same thread as for other library calls.
|
||
* Calls back into the library from a callback are not permitted.
|
||
*
|
||
* There are two main modes of use. In interactive windowing systems, it
|
||
* is usual for the app developers code to be called on the main UI thread.
|
||
* It is from the UI thread that all library calls should be made. Such
|
||
* systems usually provide a way to post a call onto the UI thread. That
|
||
* is the best way to respond to a callback from the library.
|
||
*
|
||
* The other mode of use is for plain executables that might wish to
|
||
* (say) generate images of all the pages of a document. This can
|
||
* be achieved, without use of callbacks, using the few synchronous
|
||
* calls. E.g., MuOfficeDoc_getNumPages will wait for background document
|
||
* loading to complete before returning the total number of pages and
|
||
* MuOfficeRender_destroy will wait for background rendering to complete
|
||
* before returning.
|
||
*/
|
||
|
||
#include <stddef.h> /* For size_t */
|
||
#include "mupdf/fitz.h" /* For fz_context/fz_document/fz_page */
|
||
|
||
/** Error type returned from most MuOffice functions
|
||
*
|
||
* 0 means no error
|
||
*
|
||
* non-zero values mean an error occurred. The exact value is an indication
|
||
* of what went wrong and should be included in bug reports or support
|
||
* queries. Library users should not test this value except for 0,
|
||
* non-zero and any explicitly documented values.
|
||
*/
|
||
typedef int MuError;
|
||
|
||
/** Errors returned to MuOfficeLoadingErrorFn
|
||
*
|
||
* Other values may also be returned.
|
||
*/
|
||
typedef enum MuOfficeDocErrorType
|
||
{
|
||
MuOfficeDocErrorType_NoError = 0,
|
||
MuOfficeDocErrorType_UnsupportedDocumentType = 1,
|
||
MuOfficeDocErrorType_EmptyDocument = 2,
|
||
MuOfficeDocErrorType_UnableToLoadDocument = 4,
|
||
MuOfficeDocErrorType_UnsupportedEncryption = 5,
|
||
MuOfficeDocErrorType_Aborted = 6,
|
||
MuOfficeDocErrorType_OutOfMemory = 7,
|
||
|
||
/* FIXME: Additional ones that should be backported to
|
||
* smart-office-lib.h */
|
||
MuOfficeDocErrorType_IllegalArgument = 8,
|
||
|
||
/** A password is required to open this document.
|
||
*
|
||
* The app should provide it using MuOffice_providePassword
|
||
* or if it doesn't want to proceed call MuOfficeDoc_destroy or
|
||
* MuOfficeDoc_abortLoad.
|
||
*/
|
||
MuOfficeDocErrorType_PasswordRequest = 0x1000
|
||
} MuOfficeDocErrorType;
|
||
|
||
/**
|
||
*Structure holding the detail of the layout of a bitmap. b5g6r5 is assumed.
|
||
*/
|
||
typedef struct MuOfficeBitmap_s
|
||
{
|
||
void *memptr;
|
||
int width;
|
||
int height;
|
||
int lineSkip;
|
||
} MuOfficeBitmap;
|
||
|
||
/**
|
||
* Structure defining a point
|
||
*
|
||
* x x coord of point
|
||
* y y coord of point
|
||
*/
|
||
typedef struct MuOfficePoint_s
|
||
{
|
||
float x;
|
||
float y;
|
||
} MuOfficePoint;
|
||
|
||
/**
|
||
* Structure defining a rectangle
|
||
*
|
||
* x x coord of top left of area within the page
|
||
* y y coord of top left of area within the page
|
||
* width width of area
|
||
* height height of area
|
||
*/
|
||
typedef struct MuOfficeBox_s
|
||
{
|
||
float x;
|
||
float y;
|
||
float width;
|
||
float height;
|
||
} MuOfficeBox;
|
||
|
||
typedef enum MuOfficePointType
|
||
{
|
||
MuOfficePointType_MoveTo,
|
||
MuOfficePointType_LineTo
|
||
} MuOfficePointType;
|
||
|
||
typedef struct MuOfficePathPoint
|
||
{
|
||
float x;
|
||
float y;
|
||
MuOfficePointType type;
|
||
} MuOfficePathPoint;
|
||
|
||
/**
|
||
* Structure defining what area of a page should be rendered and to what
|
||
* area of the bitmap
|
||
*
|
||
* origin coordinates of the document origin within the bitmap
|
||
* renderArea the part of the bitmap to which to render
|
||
*/
|
||
typedef struct MuOfficeRenderArea_s
|
||
{
|
||
MuOfficePoint origin;
|
||
MuOfficeBox renderArea;
|
||
} MuOfficeRenderArea;
|
||
|
||
typedef struct MuOfficeLib_s MuOfficeLib;
|
||
typedef struct MuOfficeDoc_s MuOfficeDoc;
|
||
typedef struct MuOfficePage_s MuOfficePage;
|
||
typedef struct MuOfficeRender_s MuOfficeRender;
|
||
|
||
/**
|
||
* Allocator function used by some functions to get blocks of memory.
|
||
*
|
||
* @param cookie data pointer passed in with the allocator.
|
||
* @param size the size of the required block.
|
||
*
|
||
* @returns as for malloc. (NULL implies OutOfMemory, or size == 0).
|
||
* Otherwise a pointer to an allocated block.
|
||
*/
|
||
typedef void *(MuOfficeAllocFn)(void *cookie,
|
||
size_t size);
|
||
|
||
/**
|
||
* Callback function monitoring document loading
|
||
*
|
||
* Also called when the document is edited, either adding or
|
||
* removing pages, with the pagesLoaded value decreasing
|
||
* in the page-removal case.
|
||
*
|
||
* @param cookie the data pointer that was originally passed
|
||
* to MuOfficeLib_loadDocument.
|
||
* @param pagesLoaded the number of pages so far discovered.
|
||
* @param complete whether loading has completed. If this flag
|
||
* is set, pagesLoaded is the actual number of
|
||
* pages in the document.
|
||
*/
|
||
typedef void (MuOfficeLoadingProgressFn)(void *cookie,
|
||
int pagesLoaded,
|
||
int complete);
|
||
|
||
/**
|
||
* Callback function used to monitor errors in the process of loading
|
||
* a document.
|
||
*
|
||
* @param cookie the data pointer that was originally passed
|
||
* to MuOfficeLib_loadDocument.
|
||
* @param error the error being reported
|
||
*/
|
||
typedef void (MuOfficeLoadingErrorFn)( void *cookie,
|
||
MuOfficeDocErrorType error);
|
||
|
||
/**
|
||
* Callback function used to monitor page changes
|
||
*
|
||
* @param cookie the data pointer that was originally passed
|
||
* to MuOfficeDoc_getPage.
|
||
* @param area the area that has changed.
|
||
*/
|
||
typedef void (MuOfficePageUpdateFn)( void *cookie,
|
||
const MuOfficeBox *area);
|
||
|
||
/**
|
||
* Callback function used to monitor a background render of a
|
||
* document page. The function is called exactly once.
|
||
*
|
||
* @param cookie the data pointer that was originally passed
|
||
* to MuOfficeDoc_monitorRenderProgress.
|
||
* @param error error returned from the rendering process
|
||
*/
|
||
typedef void (MuOfficeRenderProgressFn)(void *cookie,
|
||
MuError error);
|
||
|
||
/**
|
||
* Document types
|
||
*
|
||
* Keep in sync with smart-office-lib.h
|
||
*/
|
||
typedef enum
|
||
{
|
||
MuOfficeDocType_PDF,
|
||
MuOfficeDocType_XPS,
|
||
MuOfficeDocType_IMG
|
||
} MuOfficeDocType;
|
||
|
||
/**
|
||
* The possible results of a save operation
|
||
*/
|
||
typedef enum MuOfficeSaveResult
|
||
{
|
||
MuOfficeSave_Succeeded,
|
||
MuOfficeSave_Error,
|
||
MuOfficeSave_Cancelled
|
||
}
|
||
MuOfficeSaveResult;
|
||
|
||
/**
|
||
* Callback function used to monitor save operations.
|
||
*
|
||
* @param cookie the data pointer that was originally passed to
|
||
* MuOfficeDoc_save.
|
||
* @param result the result of the save operation
|
||
*/
|
||
typedef void (MuOfficeSaveResultFn)( void *cookie,
|
||
MuOfficeSaveResult result);
|
||
|
||
/**
|
||
* Create a MuOfficeLib instance.
|
||
*
|
||
* @param pMu address of variable to
|
||
* receive the created instance
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficeLib_create(MuOfficeLib **pMu);
|
||
|
||
/**
|
||
* Destroy a MuOfficeLib instance
|
||
*
|
||
* @param mu the instance to destroy
|
||
*/
|
||
void MuOfficeLib_destroy(MuOfficeLib *mu);
|
||
|
||
/**
|
||
* Find the type of a file given its filename extension.
|
||
*
|
||
* @param path path to the file (in utf8)
|
||
*
|
||
* @return a valid MuOfficeDocType value, or MuOfficeDocType_Other
|
||
*/
|
||
MuOfficeDocType MuOfficeLib_getDocTypeFromFileExtension(const char *path);
|
||
|
||
/**
|
||
* Return a list of filename extensions supported by Mu Office library.
|
||
*
|
||
* @return comma-delimited list of extensions, without the leading ".".
|
||
* The caller should free the returned pointer..
|
||
*/
|
||
char * MuOfficeLib_getSupportedFileExtensions(void);
|
||
|
||
/**
|
||
* Load a document
|
||
*
|
||
* Call will return immediately, leaving the document loading
|
||
* in the background
|
||
*
|
||
* @param mu a MuOfficeLib instance
|
||
* @param path path to the file to load (in utf8)
|
||
* @param progressFn callback for monitoring progress
|
||
* @param errorFn callback for monitoring errors
|
||
* @param cookie a pointer to pass back to the callbacks
|
||
* @param pDoc address for return of a MuOfficeDoc object
|
||
*
|
||
* @return error indication - 0 for success
|
||
*
|
||
* The progress callback may be called several times, with increasing
|
||
* values of pagesLoaded. Unless MuOfficeDoc_destroy is called,
|
||
* before loading completes, a call with "completed" set to true
|
||
* is guaranteed.
|
||
*
|
||
* Once MuOfficeDoc_destroy is called there will be no
|
||
* further callbacks.
|
||
*
|
||
* Alternatively, in a synchronous context, MuOfficeDoc_getNumPages
|
||
* can be called to wait for loading to complete and return the total
|
||
* number of pages. In this mode of use, progressFn can be NULL.
|
||
*/
|
||
MuError MuOfficeLib_loadDocument(MuOfficeLib *mu,
|
||
const char *path,
|
||
MuOfficeLoadingProgressFn *progressFn,
|
||
MuOfficeLoadingErrorFn *errorFn,
|
||
void *cookie,
|
||
MuOfficeDoc **pDoc);
|
||
|
||
/**
|
||
* Perform MuPDF native operations on a given MuOfficeLib
|
||
* instance.
|
||
*
|
||
* The function is called with a fz_context value that can
|
||
* be safely used (i.e. the context is cloned/dropped
|
||
* appropriately around the call). The function should signal
|
||
* errors by fz_throw-ing.
|
||
*
|
||
* @param mu the MuOfficeLib instance.
|
||
* @param fn the function to call to run the operations.
|
||
* @param arg Opaque data pointer.
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficeLib_run(MuOfficeLib *mu, void (*fn)(fz_context *ctx, void *arg), void *arg);
|
||
|
||
/**
|
||
* Provide the password for a document
|
||
*
|
||
* This function should be called to provide a password with a document
|
||
* error if MuOfficeError_PasswordRequired is received.
|
||
*
|
||
* If a password is requested again, this means the password was incorrect.
|
||
*
|
||
* @param doc the document object
|
||
* @param password the password (UTF8 encoded)
|
||
* @return error indication - 0 for success
|
||
*/
|
||
int MuOfficeDoc_providePassword(MuOfficeDoc *doc, const char *password);
|
||
|
||
/**
|
||
* Return the type of an open document
|
||
*
|
||
* @param doc the document object
|
||
*
|
||
* @return the document type
|
||
*/
|
||
MuOfficeDocType MuOfficeDoc_docType(MuOfficeDoc *doc);
|
||
|
||
/**
|
||
* Return the number of pages of a document
|
||
*
|
||
* This function waits for document loading to complete before returning
|
||
* the result. It may block the calling thread for a significant period of
|
||
* time. To avoid blocking, this call should be avoided in favour of using
|
||
* the MuOfficeLib_loadDocument callbacks to monitor loading.
|
||
*
|
||
* If background loading fails, the associated error will be returned
|
||
* from this call.
|
||
*
|
||
* @param doc the document
|
||
* @param pNumPages address for return of the number of pages
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficeDoc_getNumPages(MuOfficeDoc *doc, int *pNumPages);
|
||
|
||
/**
|
||
* Determine if the document has been modified
|
||
*
|
||
* @param doc the document
|
||
*
|
||
* @return modified flag
|
||
*/
|
||
int MuOfficeDoc_hasBeenModified(MuOfficeDoc *doc);
|
||
|
||
/**
|
||
* Start a save operation
|
||
*
|
||
* @param doc the document
|
||
* @param path path of the file to which to save
|
||
* @param resultFn callback used to report completion
|
||
* @param cookie a pointer to pass to the callback
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficeDoc_save(MuOfficeDoc *doc,
|
||
const char *path,
|
||
MuOfficeSaveResultFn *resultFn,
|
||
void *cookie);
|
||
|
||
/**
|
||
* Stop a document loading. The document is not destroyed, but
|
||
* no further content will be read from the file.
|
||
*
|
||
* @param doc the MuOfficeDoc object
|
||
*/
|
||
void MuOfficeDoc_abortLoad(MuOfficeDoc *doc);
|
||
|
||
/**
|
||
* Destroy a MuOfficeDoc object. Loading of the document is shutdown
|
||
* and no further callbacks will be issued for the specified object.
|
||
*
|
||
* @param doc the MuOfficeDoc object
|
||
*/
|
||
void MuOfficeDoc_destroy(MuOfficeDoc *doc);
|
||
|
||
/**
|
||
* Get a page of a document
|
||
*
|
||
* @param doc the document object
|
||
* @param pageNumber the number of the page to load (lying in the
|
||
* range 0 to one less than the number of pages)
|
||
* @param updateFn Function to be called back when the page updates
|
||
* @param cookie Opaque value to pass for any updates
|
||
* @param pPage Address for return of the page object
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficeDoc_getPage( MuOfficeDoc *doc,
|
||
int pageNumber,
|
||
MuOfficePageUpdateFn *updateFn,
|
||
void *cookie,
|
||
MuOfficePage **pPage);
|
||
|
||
/**
|
||
* Perform MuPDF native operations on a given document.
|
||
*
|
||
* The function is called with fz_context and fz_document
|
||
* values that can be safely used (i.e. the context is
|
||
* cloned/dropped appropriately around the function, and
|
||
* locking is used to ensure that no other threads are
|
||
* simultaneously using the document). Functions can
|
||
* signal errors by fz_throw-ing.
|
||
*
|
||
* Due to the locking, it is best to ensure that as little
|
||
* time is taken here as possible (i.e. if you fetch some
|
||
* data and then spend a long time processing it, it is
|
||
* probably best to fetch the data using MuOfficeDoc_run
|
||
* and then process it outside). This avoids potentially
|
||
* blocking the UI.
|
||
*
|
||
* @param doc the document object.
|
||
* @param fn the function to call with fz_context/fz_document
|
||
* values.
|
||
* @param arg Opaque data pointer.
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficeDoc_run(MuOfficeDoc *doc, void (*fn)(fz_context *ctx, fz_document *doc, void *arg), void *arg);
|
||
|
||
/**
|
||
* Destroy a page object
|
||
*
|
||
* Note this does not delete or remove the page from the document.
|
||
* It simply destroys the page object which is merely a reference
|
||
* to the page.
|
||
*
|
||
* @param page the page object
|
||
*/
|
||
void MuOfficePage_destroy(MuOfficePage *page);
|
||
|
||
/**
|
||
* Get the size of a page in pixels
|
||
*
|
||
* This returns the size of the page in pixels. Pages can be rendered
|
||
* with a zoom factor. The returned value is the size of bitmap
|
||
* appropriate for rendering with a zoom of 1.0 and corresponds to
|
||
* 90 dpi. The returned values are not necessarily whole numbers.
|
||
*
|
||
* @param page the page object
|
||
* @param pWidth address for return of the width
|
||
* @param pHeight address for return of the height
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficePage_getSize( MuOfficePage *page,
|
||
float *pWidth,
|
||
float *pHeight);
|
||
|
||
/**
|
||
* Return the zoom factors necessary to render at to a given
|
||
* size in pixels. (deprecated)
|
||
*
|
||
* @param page the page object
|
||
* @param width the desired width
|
||
* @param height the desired height
|
||
* @param pXZoom Address for return of zoom necessary to fit width
|
||
* @param pYZoom Address for return of zoom necessary to fit height
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficePage_calculateZoom( MuOfficePage *page,
|
||
int width,
|
||
int height,
|
||
float *pXZoom,
|
||
float *pYZoom);
|
||
|
||
/**
|
||
* Get the size of a page in pixels for a specified zoom factor
|
||
* (deprecated)
|
||
*
|
||
* This returns the size of bitmap that should be used to display
|
||
* the entire page at the given zoom factor. A zoom of 1.0
|
||
* corresponds to 90 dpi.
|
||
*
|
||
* @param page the page object
|
||
* @param zoom the zoom factor
|
||
* @param pWidth address for return of the width
|
||
* @param pHeight address for return of the height
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficePage_getSizeForZoom( MuOfficePage *page,
|
||
float zoom,
|
||
int *pWidth,
|
||
int *pHeight);
|
||
|
||
/**
|
||
* Perform MuPDF native operations on a given page.
|
||
*
|
||
* The function is called with fz_context and fz_page
|
||
* values that can be safely used (i.e. the context is
|
||
* cloned/dropped appropriately around the function, and
|
||
* locking is used to ensure that no other threads are
|
||
* simultaneously using the document). Functions can
|
||
* signal errors by fz_throw-ing.
|
||
*
|
||
* Due to the locking, it is best to ensure that as little
|
||
* time is taken here as possible (i.e. if you fetch some
|
||
* data and then spend a long time processing it, it is
|
||
* probably best to fetch the data using MuOfficePage_run
|
||
* and then process it outside). This avoids potentially
|
||
* blocking the UI.
|
||
*
|
||
* @param page the page object.
|
||
* @param fn the function to call with fz_context/fz_document
|
||
* values.
|
||
* @param arg Opaque data pointer.
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficePage_run(MuOfficePage *page, void (*fn)(fz_context *ctx, fz_page *page, void *arg), void *arg);
|
||
|
||
/**
|
||
* Schedule the rendering of an area of document page to
|
||
* an area of a bitmap.
|
||
*
|
||
* The alignment between page and bitmap is defined by specifying
|
||
* document's origin within the bitmap, possibly either positive or
|
||
* negative. A render object is returned via which the process can
|
||
* be monitored or terminated.
|
||
*
|
||
* The progress function is called exactly once per render in either
|
||
* the success or failure case.
|
||
*
|
||
* Note that, since a render object represents a running thread that
|
||
* needs access to the page, document, and library objects, it is important
|
||
* to call MuOfficeRender_destroy, not only before using or deallocating
|
||
* the bitmap, but also before calling MuOfficePage_destroy, etc..
|
||
*
|
||
* @param page the page to render
|
||
* @param zoom the zoom factor
|
||
* @param bitmap the bitmap
|
||
* @param area area to render
|
||
* @param progressFn the progress callback function
|
||
* @param cookie a pointer to pass to the callback function
|
||
* @param pRender Address for return of the render object
|
||
*
|
||
* @return error indication - 0 for success
|
||
*/
|
||
MuError MuOfficePage_render( MuOfficePage *page,
|
||
float zoom,
|
||
const MuOfficeBitmap *bitmap,
|
||
const MuOfficeRenderArea *area,
|
||
MuOfficeRenderProgressFn *progressFn,
|
||
void *cookie,
|
||
MuOfficeRender **pRender);
|
||
|
||
/**
|
||
* Destroy a render
|
||
*
|
||
* This call destroys a MuOfficeRender object, aborting any current
|
||
* render.
|
||
*
|
||
* This call is intended to support an app dealing with a user quickly
|
||
* flicking through document pages. A render may be scheduled but, before
|
||
* completion, be found not to be needed. In that case the bitmap will
|
||
* need to be reused, which requires any existing render to be aborted.
|
||
* The call to MuOfficeRender_destroy will cut short the render and
|
||
* allow the bitmap to be reused immediately.
|
||
*
|
||
* @note If an active render thread is destroyed, it will be aborted.
|
||
* While fast, this is not an instant operation. For maximum
|
||
* responsiveness, it is best to 'abort' as soon as you realise you
|
||
* don't need the render, and to destroy when you get the callback.
|
||
*
|
||
* @param render The render object
|
||
*/
|
||
void MuOfficeRender_destroy(MuOfficeRender *render);
|
||
|
||
/**
|
||
* Abort a render
|
||
*
|
||
* This call aborts any rendering currently underway. The 'render
|
||
* complete' callback (if any) given when the render was created will
|
||
* still be called. If a render has completed, this call will have no
|
||
* effect.
|
||
*
|
||
* This call will not block to wait for the render thread to stop, but
|
||
* will cause it to stop as soon as it can in the background.
|
||
*
|
||
* @note It is important not to start any new render to the same bitmap
|
||
* until the callback comes in (or until waitUntilComplete returns), as
|
||
* otherwise you can have multiple renders drawing to the same bitmap
|
||
* with unpredictable consequences.
|
||
*
|
||
* @param render The render object to abort
|
||
*/
|
||
void MuOfficeRender_abort(MuOfficeRender *render);
|
||
|
||
/**
|
||
* Wait for a render to complete.
|
||
*
|
||
* This call will not return until rendering is complete, so on return
|
||
* the bitmap will contain the page image (assuming the render didn't
|
||
* run into an error condition) and will not be used further by any
|
||
* background processing. Any error during rendering will be returned
|
||
* from this function.
|
||
*
|
||
* This call may block the calling thread for a significant period of
|
||
* time. To avoid blocking, supply a progress-monitoring callback
|
||
* function to MuOfficePage_render.
|
||
*
|
||
* @param render The render object to destroy
|
||
* @return render error condition - 0 for no error.
|
||
*/
|
||
MuError MuOfficeRender_waitUntilComplete(MuOfficeRender *render);
|
||
|
||
#endif /* SMART_OFFICE_LIB_H */
|