diff options
Diffstat (limited to 'public/fpdf_doc.h')
| -rw-r--r-- | public/fpdf_doc.h | 448 |
1 files changed, 184 insertions, 264 deletions
diff --git a/public/fpdf_doc.h b/public/fpdf_doc.h index eae7c95e49..0b78743259 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 -// 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. +// 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_ |