Index: public/fpdf_doc.h |
diff --git a/public/fpdf_doc.h b/public/fpdf_doc.h |
index eae7c95e4962d506adf036767a95900c9fe5c897..0b7874325931c8b1e0b8a8abe96b313677f1fe41 100644 |
--- a/public/fpdf_doc.h |
+++ b/public/fpdf_doc.h |
@@ -9,357 +9,277 @@ |
#include "fpdfview.h" |
-// Exported Functions |
#ifdef __cplusplus |
extern "C" { |
-#endif |
+#endif // __cplusplus |
-// Function: FPDFBookmark_GetFirstChild |
-// Get the first child of a bookmark item, or the first top level |
-// bookmark item. |
-// Parameters: |
-// document - Handle to the document. Returned by |
-// FPDF_LoadDocument or FPDF_LoadMemDocument. |
-// bookmark - Handle to the current bookmark. Can be NULL if you |
-// want to get the first top level item. |
-// Return value: |
-// Handle to the first child or top level bookmark item. NULL if no |
-// child or top level bookmark found. |
+// Unsupported action type. |
+#define PDFACTION_UNSUPPORTED 0 |
+// Go to a destination within current document. |
+#define PDFACTION_GOTO 1 |
+// Go to a destination within another document. |
+#define PDFACTION_REMOTEGOTO 2 |
+// URI, including web pages and other Internet resources. |
+#define PDFACTION_URI 3 |
+// Launch an application or open a file. |
+#define PDFACTION_LAUNCH 4 |
+ |
+typedef struct _FS_QUADPOINTSF { |
+ FS_FLOAT x1; |
+ FS_FLOAT y1; |
+ FS_FLOAT x2; |
+ FS_FLOAT y2; |
+ FS_FLOAT x3; |
+ FS_FLOAT y3; |
+ FS_FLOAT x4; |
+ FS_FLOAT y4; |
+} FS_QUADPOINTSF; |
+ |
+// Get the first child of |bookmark|, or the first top-level bookmark item. |
+// |
+// document - handle to the document. |
+// bookmark - handle to the current bookmark. Pass NULL for the first top |
+// level item. |
// |
+// Returns a handle to the first child of |bookmark| or the first top-level |
+// bookmark item. NULL if no child or top-level bookmark found. |
DLLEXPORT FPDF_BOOKMARK STDCALL |
FPDFBookmark_GetFirstChild(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark); |
-// Function: FPDFBookmark_GetNextSibling |
-// Get next bookmark item at the same level. |
-// Parameters: |
-// document - Handle to the document. Returned by |
-// FPDF_LoadDocument or FPDF_LoadMemDocument. |
-// bookmark - Handle to the current bookmark. Cannot be NULL. |
-// Return value: |
-// Handle to the next bookmark item at the same level. NULL if this is |
-// the last bookmark at this level. |
+// Get the next sibling of |bookmark|. |
// |
+// document - handle to the document. |
+// bookmark - handle to the current bookmark. |
+// |
+// Returns a handle to the next sibling of |bookmark|, or NULL if this is the |
+// last bookmark at this level. |
DLLEXPORT FPDF_BOOKMARK STDCALL |
FPDFBookmark_GetNextSibling(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark); |
-// Function: FPDFBookmark_GetTitle |
-// Get title of a bookmark. |
-// Parameters: |
-// bookmark - Handle to the bookmark. |
-// buffer - Buffer for the title. Can be NULL. |
-// buflen - The length of the buffer in bytes. Can be 0. |
-// Return value: |
-// Number of bytes the title consumes, including trailing zeros. |
-// Comments: |
-// Regardless of the platform, the title is always in UTF-16LE |
-// encoding. That means the buffer |
-// can be treated as an array of WORD (on Intel and compatible CPUs), |
-// each WORD representing the Unicode of |
-// a character(some special Unicode may take 2 WORDs).The string is |
-// followed by two bytes of zero |
-// indicating the end of the string. |
-// |
-// The return value always indicates the number of bytes required for |
-// the buffer, even if no buffer is specified |
-// or the buffer size is less then required. In these cases, the buffer |
-// will not be modified. |
+// Get the title of |bookmark|. |
+// |
+// bookmark - handle to the bookmark. |
+// buffer - buffer for the title. May be NULL. |
+// buflen - the length of the buffer in bytes. May be 0. |
// |
+// Returns the number of bytes in the title, including the terminating NUL |
+// character. The number of bytes is returned regardless of the |buffer| and |
+// |buflen| parameters. |
+// |
+// Regardless of the platform, the |buffer| is always in UTF-16LE encoding. The |
+// string is terminated by a UTF16 NUL character. If |buflen| is less then the |
+// required length, or |buffer| is NULL, |buffer| will not be modified. |
DLLEXPORT unsigned long STDCALL FPDFBookmark_GetTitle(FPDF_BOOKMARK bookmark, |
void* buffer, |
unsigned long buflen); |
-// Function: FPDFBookmark_Find |
-// Find a bookmark in the document, using the bookmark title. |
-// Parameters: |
-// document - Handle to the document. Returned by |
-// FPDF_LoadDocument or FPDF_LoadMemDocument. |
-// title - The UTF-16LE encoded Unicode string for the bookmark |
-// title to be searched. Can't be NULL. |
-// Return value: |
-// Handle to the found bookmark item. NULL if the title can't be found. |
-// Comments: |
-// It always returns the first found bookmark if more than one |
-// bookmarks have the same title. |
+// Find the bookmark with |title| in |document|. |
+// |
+// document - handle to the document. |
+// title - the UTF-16LE encoded Unicode title for which to search. |
// |
+// Returns the handle to the bookmark, or NULL if |title| can't be found. |
+// |
+// |FPDFBookmark_Find| will always return the first bookmark found even if |
+// multiple bookmarks have the same |title|. |
DLLEXPORT FPDF_BOOKMARK STDCALL FPDFBookmark_Find(FPDF_DOCUMENT document, |
FPDF_WIDESTRING title); |
-// Function: FPDFBookmark_GetDest |
-// Get the destination associated with a bookmark item. |
-// Parameters: |
-// document - Handle to the document. |
-// bookmark - Handle to the bookmark. |
-// Return value: |
-// Handle to the destination data. NULL if no destination is associated |
-// with this bookmark. |
+// Get the destination associated with |bookmark|. |
+// |
+// document - handle to the document. |
+// bookmark - handle to the bookmark. |
// |
+// Returns the handle to the destination data, NULL if no destination is |
+// associated with |bookmark|. |
DLLEXPORT FPDF_DEST STDCALL FPDFBookmark_GetDest(FPDF_DOCUMENT document, |
FPDF_BOOKMARK bookmark); |
-// Function: FPDFBookmark_GetAction |
-// Get the action associated with a bookmark item. |
-// Parameters: |
-// bookmark - Handle to the bookmark. |
-// Return value: |
-// Handle to the action data. NULL if no action is associated with this |
-// bookmark. In this case, the |
-// application should try FPDFBookmark_GetDest. |
+// Get the action associated with |bookmark|. |
+// |
+// bookmark - handle to the bookmark. |
// |
+// Returns the handle to the action data, or NULL if no action is associated |
+// with |bookmark|. When NULL is returned, |FPDFBookmark_GetDest| should be |
+// called to get the |bookmark| destination data. |
DLLEXPORT FPDF_ACTION STDCALL FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark); |
-#define PDFACTION_UNSUPPORTED 0 // Unsupported action type. |
-#define PDFACTION_GOTO 1 // Go to a destination within current document. |
-#define PDFACTION_REMOTEGOTO 2 // Go to a destination within another document. |
-#define PDFACTION_URI 3 // Universal Resource Identifier, including web |
- // pages and other Internet based resources. |
-#define PDFACTION_LAUNCH 4 // Launch an application or open a file. |
- |
-// Function: FPDFAction_GetType |
-// Get type of an action. |
-// Parameters: |
-// action - Handle to the action. |
-// Return value: |
-// A type number as defined above. |
+// Get the type of |action|. |
+// |
+// action - handle to the action. |
// |
+// Returns one of: |
+// PDFACTION_UNSUPPORTED |
+// PDFACTION_GOTO |
+// PDFACTION_REMOTEGOTO |
+// PDFACTION_URI |
+// PDFACTION_LAUNCH |
DLLEXPORT unsigned long STDCALL FPDFAction_GetType(FPDF_ACTION action); |
-// Function: FPDFAction_GetDest |
-// Get destination of an action. |
-// Parameters: |
-// document - Handle to the document. |
-// action - Handle to the action. It must be a GOTO or |
-// REMOTEGOTO action. |
-// Return value: |
-// Handle to the destination data. |
-// Comments: |
-// In case of remote goto action, the application should first use |
-// FPDFAction_GetFilePath to |
-// get file path, then load that particular document, and use its |
-// document handle to call this |
-// function. |
+// Get the destination of |action|. |
+// |
+// document - handle to the document. |
+// action - handle to the action. |action| must be a |PDFACTION_GOTO| or |
+// |PDFACTION_REMOTEGOTO|. |
// |
+// Returns a handle to the destination data. |
+// |
+// In the case of |PDFACTION_REMOTEGOTO|, you should first call |
+// |FPDFAction_GetFilePath| then load that document, the document handle from |
+// that document should pass as |document| to |FPDFAction_GetDest|. |
DLLEXPORT FPDF_DEST STDCALL FPDFAction_GetDest(FPDF_DOCUMENT document, |
FPDF_ACTION action); |
-// Function: FPDFAction_GetFilePath |
-// Get file path of a remote goto action. |
-// Parameters: |
-// action - Handle to the action. Must be a REMOTEGOTO or |
-// LAUNCH action. |
-// buffer - A buffer for output the path string. Can be NULL. |
-// buflen - The length of the buffer, number of bytes. Can be 0. |
-// Return value: |
-// Number of bytes the file path consumes, including trailing zero. |
-// |
-// Comments: |
-// The file path is UTF-8 encoded. The return value is the number of |
Lei Zhang
2017/06/09 01:49:28
UTF-8
|
-// bytes required for the buffer, even when there is no buffer |
-// specified, or the buffer size is less then required. In this case, |
-// the buffer will not be modified. |
+// Get file path of a |PDFACTION_REMOTEGOTO| |action|. |
+// |
+// action - handle to the action. |action| must be a |PDFACTION_LAUNCH| or |
+// |PDFACTION_REMOTEGOTO| |
+// buffer - a buffer for output the path string. May be NULL. |
+// buflen - the length of the buffer, in bytes. May be 0. |
+// |
+// Returns the number of bytes in the file path, including the trailing UTF16 |
+// NUL character. |
// |
+// Regardless of the platform, the |buffer| is always in UTF-16LE encoding. |
Lei Zhang
2017/06/09 01:49:28
UTF-16LE?
|
+// If |buflen| is less then the returned length, or |buffer| is NULL, |buffer| |
+// will not be modified. |
DLLEXPORT unsigned long STDCALL |
FPDFAction_GetFilePath(FPDF_ACTION action, void* buffer, unsigned long buflen); |
-// Function: FPDFAction_GetURIPath |
-// Get URI path of a URI action. |
-// Parameters: |
-// document - Handle to the document. |
-// action - Handle to the action. Must be a URI action. |
-// buffer - A buffer for output the path string. Can be NULL. |
-// buflen - The length of the buffer, number of bytes. Can be 0. |
-// Return value: |
-// Number of bytes the URI path consumes, including trailing zeros. |
-// Comments: |
-// The URI path is always encoded in 7-bit ASCII. |
-// |
-// The return value is the number of bytes required for the buffer, |
-// even when there is no buffer specified, or the buffer size is less |
-// then required. In this case, the buffer will not be modified. |
+// Get the URI path of a |PDFACTION_URI| |action|. |
// |
+// document - handle to the document. |
+// action - handle to the action. Must be a |PDFACTION_URI|. |
+// buffer - a buffer for the path string. May be NULL. |
+// buflen - the length of the buffer, in bytes. May be 0. |
+// |
+// Returns the number of bytes in the URI path, including trailing zeros. |
+// |
+// The |buffer| is always encoded in 7-bit ASCII. If |buflen| is less then the |
+// returned length, or |buffer| is NULL, |buffer| will not be modified. |
DLLEXPORT unsigned long STDCALL FPDFAction_GetURIPath(FPDF_DOCUMENT document, |
FPDF_ACTION action, |
void* buffer, |
unsigned long buflen); |
-// Function: FPDFDest_GetPageIndex |
-// Get page index of a destination. |
-// Parameters: |
-// document - Handle to the document. |
-// dest - Handle to the destination. |
-// Return value: |
-// The page index. Starting from 0 for the first page. |
+// Get the page index of |dest|. |
// |
+// document - handle to the document. |
+// dest - handle to the destination. |
+// |
+// Returns the page index containing |dest|. Page indices start from 0. |
DLLEXPORT unsigned long STDCALL FPDFDest_GetPageIndex(FPDF_DOCUMENT document, |
FPDF_DEST dest); |
-// Function: FPDFLink_GetLinkAtPoint |
-// Find a link at specified point on a document page. |
-// Parameters: |
-// page - Handle to the document page. |
-// x - The x coordinate of the point, specified in page |
-// coordinate system. |
-// y - The y coordinate of the point, specified in page |
-// coordinate system. |
-// Return value: |
-// Handle to the link. NULL if no link found at that point. |
-// Comments: |
-// The point coordinates are specified in page coordinate system. You can |
-// convert coordinates from screen system to page system using |
-// FPDF_DeviceToPage(). |
+// Find a link at point (|x|,|y|) on |page|. |
+// |
+// page - handle to the document page. |
+// x - the x coordinate, in the page coordinate system. |
+// y - the y coordinate, in the page coordinate system. |
// |
+// Returns a handle to the link, or NULL if no link found at the given point. |
+// |
+// You can convert coordinates from screen coordinates to page coordinates using |
+// |FPDF_DeviceToPage|. |
DLLEXPORT FPDF_LINK STDCALL FPDFLink_GetLinkAtPoint(FPDF_PAGE page, |
double x, |
double y); |
-// Function: FPDFLink_GetLinkZOrderAtPoint |
-// Find the z-order of a link at specified point on a document page. |
-// Parameters: |
-// page - Handle to the document page. |
-// x - The x coordinate of the point, specified in page |
-// coordinate system. |
-// y - The y coordinate of the point, specified in page |
-// coordinate system. |
-// Return value: |
-// Z-order of the link, or -1 if no link found at that point. |
-// Higher numbers are closer to the front. |
-// Comments: |
-// The point coordinates are specified in page coordinate system. You can |
-// convert coordinates from screen system to page system using |
-// FPDF_DeviceToPage(). |
+// Find the Z-order of link at point (|x|,|y|) on |page|. |
+// |
+// page - handle to the document page. |
+// x - the x coordinate, in the page coordinate system. |
+// y - the y coordinate, in the page coordinate system. |
+// |
+// Returns the Z-order of the link, or -1 if no link found at the given point. |
+// Larger Z-order numbers are closer to the front. |
// |
+// You can convert coordinates from screen coordinates to page coordinates using |
+// |FPDF_DeviceToPage|. |
DLLEXPORT int STDCALL |
FPDFLink_GetLinkZOrderAtPoint(FPDF_PAGE page, double x, double y); |
-// Function: FPDFLink_GetDest |
-// Get destination info of a link. |
-// Parameters: |
-// document - Handle to the document. |
-// link - Handle to the link. Returned by |
-// FPDFLink_GetLinkAtPoint. |
-// Return value: |
-// Handle to the destination. NULL if there is no destination |
-// associated with the link, in this case |
-// the application should try FPDFLink_GetAction. |
+// Get destination info for |link|. |
// |
+// document - handle to the document. |
+// link - handle to the link. |
+// |
+// Returns a handle to the destination, or NULL if there is no destination |
+// associated with the link. In this case, you should call |FPDFLink_GetAction| |
+// to retrieve the action associated with |link|. |
DLLEXPORT FPDF_DEST STDCALL FPDFLink_GetDest(FPDF_DOCUMENT document, |
FPDF_LINK link); |
-// Function: FPDFLink_GetAction |
-// Get action info of a link. |
-// Parameters: |
-// link - Handle to the link. |
-// Return value: |
-// Handle to the action. NULL if there is no action associated with the |
-// link. |
+// Get action info for |link|. |
+// |
+// link - handle to the link. |
// |
+// Returns a handle to the action associated to |link|, or NULL if no action. |
DLLEXPORT FPDF_ACTION STDCALL FPDFLink_GetAction(FPDF_LINK link); |
-// Function: FPDFLink_Enumerate |
-// This function would enumerate all the link annotations in a single |
-// PDF page. |
-// Parameters: |
-// page[in] - Handle to the page. |
-// startPos[in,out] - The start position to enumerate the link |
-// annotations, which should be specified to start from |
-// - 0 for the first call, and would receive the |
-// next position for enumerating to start from. |
-// linkAnnot[out] - Receive the link handle. |
-// Return value: |
-// TRUE if succceed, else False; |
+// Enumerates all the link annotations in |page|. |
+// |
+// page - handle to the page. |
+// startPos - the start position, should initially be 0 and is updated with |
+// the next start position on return. |
+// linkAnnot - the link handle for |startPos|. |
// |
+// Returns TRUE on success. |
DLLEXPORT FPDF_BOOL STDCALL FPDFLink_Enumerate(FPDF_PAGE page, |
int* startPos, |
FPDF_LINK* linkAnnot); |
-// Function: FPDFLink_GetAnnotRect |
-// Get the annotation rectangle. (Specified by the |Rect| entry of |
-// annotation dictionary). |
-// Parameters: |
-// linkAnnot[in] - Handle to the link annotation. |
-// rect[out] - The annotation rect. |
-// Return value: |
-// TRUE if succceed, else False; |
+// Get the rectangle for |linkAnnot|. |
// |
+// linkAnnot - handle to the link annotation. |
+// rect - the annotation rectangle. |
+// |
+// Returns true on success. |
DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetAnnotRect(FPDF_LINK linkAnnot, |
FS_RECTF* rect); |
-// Function: FPDFLink_CountQuadPoints |
-// Get the count of quadrilateral points to the link annotation. |
-// Parameters: |
-// linkAnnot[in] - Handle to the link annotation. |
-// Return value: |
-// The count of quadrilateral points. |
+// Get the count of quadrilateral points to the |linkAnnot|. |
+// |
+// linkAnnot - handle to the link annotation. |
// |
+// Returns the count of quadrilateral points. |
DLLEXPORT int STDCALL FPDFLink_CountQuadPoints(FPDF_LINK linkAnnot); |
-/* _FS_DEF_STRUCTURE_QUADPOINTSF_ */ |
-#ifndef _FS_DEF_STRUCTURE_QUADPOINTSF_ |
-#define _FS_DEF_STRUCTURE_QUADPOINTSF_ |
-typedef struct _FS_QUADPOINTSF { |
- FS_FLOAT x1; |
- FS_FLOAT y1; |
- FS_FLOAT x2; |
- FS_FLOAT y2; |
- FS_FLOAT x3; |
- FS_FLOAT y3; |
- FS_FLOAT x4; |
- FS_FLOAT y4; |
-} FS_QUADPOINTSF; |
-#endif /* _FS_DEF_STRUCTURE_QUADPOINTSF_ */ |
- |
-// Function: FPDFLink_GetQuadPoints |
-// Get the quadrilateral points for the specified index in the link |
-// annotation. |
-// Parameters: |
-// linkAnnot[in] - Handle to the link annotation. |
-// quadIndex[in] - The specified quad points index. |
-// quadPoints[out] - Receive the quadrilateral points. |
-// Return value: |
-// True if succeed, else False. |
+// Get the quadrilateral points for the specified |quadIndex| in |linkAnnot|. |
// |
+// linkAnnot - handle to the link annotation. |
+// quadIndex - the specified quad point index. |
+// quadPoints - receives the quadrilateral points. |
+// |
+// Returns true on success. |
DLLEXPORT FPDF_BOOL STDCALL FPDFLink_GetQuadPoints(FPDF_LINK linkAnnot, |
int quadIndex, |
FS_QUADPOINTSF* quadPoints); |
-// Function: FPDF_GetMetaText |
-// Get a text from meta data of the document. Result is encoded in |
-// UTF-16LE. |
-// Parameters: |
-// doc - Handle to a document |
-// tag - The tag for the meta data. Currently, It can be |
-// "Title", "Author", |
-// "Subject", "Keywords", "Creator", "Producer", |
-// "CreationDate", or "ModDate". |
-// For detailed explanation of these tags and their |
-// respective values, |
-// please refer to PDF Reference 1.6, section 10.2.1, |
-// "Document Information Dictionary". |
-// buffer - A buffer for output the title. Can be NULL. |
-// buflen - The length of the buffer, number of bytes. Can be 0. |
-// Return value: |
-// Number of bytes the title consumes, including trailing zeros. |
-// Comments: |
-// No matter on what platform, the title is always output in UTF-16LE |
-// encoding, which means the buffer |
-// can be regarded as an array of WORD (on Intel and compatible CPUs), |
-// each WORD represent the Unicode of |
-// a character (some special Unicode may take 2 WORDs). The string is |
-// followed by two bytes of zero |
-// indicating end of the string. |
-// |
-// The return value always indicated number of bytes required for the |
-// buffer, even when there is |
-// no buffer specified, or the buffer size is less then required. In |
-// this case, the buffer will not |
-// be modified. |
+// Get meta-data |tag| content from |document|. |
+// |
+// doc - handle to the document |
+// tag - the tag to retrieve. The tag can be one of: |
+// Title, Author, Subject, Keywords, Creator, Producer, |
+// CreationDate, or ModDate. |
+// For detailed explanations of these tags and their respective |
+// values, please refer to PDF Reference 1.6, section 10.2.1, |
+// 'Document Information Dictionary'. |
+// buffer - a buffer for the title. May be NULL. |
+// buflen - the length of the buffer, in bytes. May be 0. |
+// |
+// Returns the number of bytes in the title, including trailing zeros. |
// |
+// The |buffer| is always encoded in UTF-16LE. The |buffer| is followed by two |
+// bytes of zeros indicating the end of the string. If |buflen| is less then |
+// the returned length, or |buffer| is NULL, |buffer| will not be modified. |
DLLEXPORT unsigned long STDCALL FPDF_GetMetaText(FPDF_DOCUMENT doc, |
FPDF_BYTESTRING tag, |
void* buffer, |
unsigned long buflen); |
#ifdef __cplusplus |
-} |
-#endif |
+} // extern "C" |
+#endif // __cplusplus |
#endif // PUBLIC_FPDF_DOC_H_ |