Improve return codes from pdf_authenticate_password.

Customer request to enable finer control based on which
password authenticates.

2 files changed, 21 insertions, 0 deletions

diff --git a/include/mupdf/fitz/document.h b/include/mupdf/fitz/document.h
index c66dc2ca..90b54b26 100644
--- a/include/mupdf/fitz/document.h
+++ b/include/mupdf/fitz/document.h
@@ -195,6 +195,15 @@ int fz_needs_password(fz_context *ctx, fz_document *doc);
 	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
+
 	Does not throw exceptions.
 */
 int fz_authenticate_password(fz_context *ctx, fz_document *doc, const char *password);
diff --git a/include/mupdf/pdf/document.h b/include/mupdf/pdf/document.h
index 56d16ebf..a84ee872 100644
--- a/include/mupdf/pdf/document.h
+++ b/include/mupdf/pdf/document.h
@@ -113,6 +113,18 @@ pdf_page *pdf_page_from_fz_page(fz_context *ctx, fz_page *ptr);
 pdf_annot *pdf_annot_from_fz_annot(fz_context *ctx, fz_annot *ptr);
 
 int pdf_needs_password(fz_context *ctx, pdf_document *doc);
+
+/*
+	pdf_authenticate_password: Attempt to authenticate a
+	password.
+
+	Returns 0 for failure, non-zero for success.
+
+	In the non-zero case:
+		bit 0 set => no password required
+		bit 1 set => user password authenticated
+		bit 2 set => owner password authenticated
+*/
 int pdf_authenticate_password(fz_context *ctx, pdf_document *doc, const char *pw);
 
 int pdf_has_permission(fz_context *ctx, pdf_document *doc, fz_permission p);