Add MuOfficeLib functions to safely run native MuPDF ops.

It seems likely that we'll want people to able to use the MuPDF
C API as well as the MuOfficeLib helper lib. We therefore need
a way to get fz_context and fz_document values out of MuOfficeLib.

Potential problems exist with people calling MuPDF C API functions
using an fz_context that is in use elsewhere. Similarly, if an
fz_document is in use in a background thread (for instance in a
page render), we need to ensure that it can't be used at the same
time elsewhere.

We therefore provide MuOffice{Lib,Doc,Page}_run functions that
allow this to happen safely. This largely insulates callers from the
complexities of having to clone contexts etc, it safely ensures
that exceptions cannot be propogated beyond the topmost fz_try/
fz_catch, and it ensures that appropriate locking is used.

1 files changed, 74 insertions, 0 deletions

diff --git a/include/mupdf/helpers/mu-office-lib.h b/include/mupdf/helpers/mu-office-lib.h
index 9c4cd845..1c856962 100644
--- a/include/mupdf/helpers/mu-office-lib.h
+++ b/include/mupdf/helpers/mu-office-lib.h
@@ -38,6 +38,8 @@
  */
 
 #include <stddef.h> /* For size_t */
+#include "mupdf/fitz.h" /* For fz_context/fz_document/fz_page */
+
 
 /** Error type returned from most MuOffice functions
  *
@@ -323,6 +325,24 @@ MuError MuOfficeLib_loadDocument(MuOfficeLib              *mu,
 
 
 /**
+ * Perform MuPDF native operations on a given MuOfficeLib
+ * instance.
+ *
+ * The function is called with an 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
@@ -430,6 +450,33 @@ MuError MuOfficeDoc_getPage(	MuOfficeDoc          *doc,
 
 
 /**
+ * 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.
@@ -501,6 +548,33 @@ MuError MuOfficePage_getSizeForZoom(	MuOfficePage *page,
 
 
 /**
+ * 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.
  *