diff options
Diffstat (limited to 'public/fpdf_dataavail.h')
| -rw-r--r-- | public/fpdf_dataavail.h | 332 |
1 files changed, 127 insertions, 205 deletions
diff --git a/public/fpdf_dataavail.h b/public/fpdf_dataavail.h index fc23337840..effa68e179 100644 --- a/public/fpdf_dataavail.h +++ b/public/fpdf_dataavail.h @@ -7,7 +7,7 @@ #ifndef PUBLIC_FPDF_DATAAVAIL_H_ #define PUBLIC_FPDF_DATAAVAIL_H_ -#include <stddef.h> // For size_t. +#include <stddef.h> #include "fpdfview.h" @@ -26,250 +26,172 @@ #ifdef __cplusplus extern "C" { -#endif +#endif // __cplusplus -/** - * Interface: FX_FILEAVAIL - * Interface for checking whether the section of the file is available. - */ +// Interface for checking whether sections of the file are available. typedef struct _FX_FILEAVAIL { - /** - * Version number of the interface. Currently must be 1. - */ + // Version number of the interface. Must be 1. int version; - /** - * Method: IsDataAvail - * Report whether the specified data section is available. A section is - * available only if all bytes in the section is available. - * Interface Version: - * 1 - * Implementation Required: - * Yes - * Parameters: - * pThis - Pointer to the interface structure itself. - * offset - The offset of the data section in the file. - * size - The size of the data section - * Return Value: - * true means the specified data section is available. - * Comments: - * Called by Foxit SDK to check whether the data section is ready. - */ + // Reports if the specified data section is currently available. A section is + // available if all bytes in the section are available. + // + // Interface Version: 1 + // Implementation Required: Yes + // + // pThis - pointer to the interface structure. + // offset - the offset of the data section in the file. + // size - the size of the data section. + // + // Returns true if the specified data section at |offset| of |size| + // is available. FPDF_BOOL (*IsDataAvail)(struct _FX_FILEAVAIL* pThis, size_t offset, size_t size); } FX_FILEAVAIL; - typedef void* FPDF_AVAIL; -/** -* Function: FPDFAvail_Create -* Create a document availability provider. -* -* Parameters: -* file_avail - Pointer to file availability interface to check -* availability of file data. -* file - Pointer to a file access interface for reading data -* from file. -* Return value: -* A handle to the document availability provider. NULL for error. -* Comments: -* Application must call FPDFAvail_Destroy when done with the -* availability provider. -*/ +// Create a document availability provider. +// +// file_avail - pointer to file availability interface. +// file - pointer to a file access interface. +// +// Returns a handle to the document availability provider, or NULL on error. +// +// |FPDFAvail_Destroy| must be called when done with the availability provider. DLLEXPORT FPDF_AVAIL STDCALL FPDFAvail_Create(FX_FILEAVAIL* file_avail, FPDF_FILEACCESS* file); -/** -* Function: FPDFAvail_Destroy -* Destroy a document availibity provider. -* -* Parameters: -* avail - Handle to document availability provider returned by -* FPDFAvail_Create -* Return Value: -* None. -*/ +// Destroy the |avail| document availability provider. +// +// |avail| - handle to document availability provider to be destroyed. DLLEXPORT void STDCALL FPDFAvail_Destroy(FPDF_AVAIL avail); -/** - * Interface: FX_DOWNLOADHINTS - * Download hints interface. Used to receive hints for further - * downloading. - */ +// Download hints interface. Used to receive hints for further downloading. typedef struct _FX_DOWNLOADHINTS { - /** - * Version number of the interface. Currently must be 1. - */ + // Version number of the interface. Must be 1. int version; - /** - * Method: AddSegment - * Add a section to be downloaded. - * Interface Version: - * 1 - * Implementation Required: - * Yes - * Parameters: - * pThis - Pointer to the interface structure itself. - * offset - The offset of the hint reported to be downloaded. - * size - The size of the hint reported to be downloaded. - * Return Value: - * None. - * Comments: - * Called by Foxit SDK to report some downloading hints for download - * manager. - * The position and size of section may be not accurate, part of the - * section might be already available. - * The download manager must deal with that to maximize download - * efficiency. - */ + // Add a section to be downloaded. + // + // Interface Version: 1 + // Implementation Required: Yes + // + // pThis - pointer to the interface structure. + // offset - the offset of the hint reported to be downloaded. + // size - the size of the hint reported to be downloaded. + // + // The |offset| and |size| of the section may not be unique. Part of the + // section might be already available. The download manager must deal with + // overlapping sections. void (*AddSegment)(struct _FX_DOWNLOADHINTS* pThis, size_t offset, size_t size); } FX_DOWNLOADHINTS; -/** -* Function: FPDFAvail_IsDocAvail -* Check whether the document is ready for loading, if not, get -* download hints. -* -* Parameters: -* avail - Handle to document availability provider returned by -* FPDFAvail_Create -* hints - Pointer to a download hints interface, receiving -* generated hints -* Return value: -* PDF_DATA_ERROR: A common error is returned. It can't tell -* whehter data are availabe or not. -* PDF_DATA_NOTAVAIL: Data are not yet available. -* PDF_DATA_AVAIL: Data are available. -* Comments: -* Applications should call this function whenever new data arrived, -* and process all the generated download hints if any, until the -* function returns PDF_DATA_ERROR or PDF_DATA_AVAIL. Then -* applications can call FPDFAvail_GetDocument() to get a document -* handle. -*/ +// Checks if the document is ready for loading, if not, gets download hints. +// +// avail - handle to document availability provider. +// hints - pointer to a download hints interface. +// +// Returns one of: +// PDF_DATA_ERROR: A common error is returned. Data availability unknown. +// PDF_DATA_NOTAVAIL: Data not yet available. +// PDF_DATA_AVAIL: Data available. +// +// Applications should call this function whenever new data arrives, and process +// all the generated download hints, if any, until the function returns +// |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. +// +// Once all data is available, call |FPDFAvail_GetDocument| to get a document +// handle. DLLEXPORT int STDCALL FPDFAvail_IsDocAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints); -/** -* Function: FPDFAvail_GetDocument -* Get document from the availability provider. -* -* Parameters: -* avail - Handle to document availability provider returned by -* FPDFAvail_Create -* password - Optional password for decrypting the PDF file. -* Return value: -* Handle to the document. -* Comments: -* After FPDFAvail_IsDocAvail() returns TRUE, the application should -* call this function to -* get the document handle. To close the document, use -* FPDF_CloseDocument function. -*/ +// Get document from the availability provider. +// +// avail - handle to document availability provider. +// password - password for decrypting the PDF file. Optional. +// +// Returns a handle to the document. +// +// When |FPDFAvail_IsDocAvail| returns TRUE, call |FPDFAvail_GetDocument| to +// retrieve the document handle. DLLEXPORT FPDF_DOCUMENT STDCALL FPDFAvail_GetDocument(FPDF_AVAIL avail, FPDF_BYTESTRING password); -/** -* Function: FPDFAvail_GetFirstPageNum -* Get page number for the first available page in a linearized PDF -* -* Parameters: -* doc - A document handle returned by FPDFAvail_GetDocument -* Return Value: -* Zero-based index for the first available page. -* Comments: -* For most linearized PDFs, the first available page would be just the -* first page, however, -* some PDFs might make other page to be the first available page. -* For non-linearized PDF, this function will always return zero. -*/ +// Get the page number for the first available page in a linearized PDF. +// +// doc - document handle. +// +// Returns the zero-based index for the first available page. +// +// For most linearized PDFs, the first available page will be the first page, +// however, some PDFs might make another page the first available page. +// For non-linearized PDFs, this function will always return zero. DLLEXPORT int STDCALL FPDFAvail_GetFirstPageNum(FPDF_DOCUMENT doc); -/** -* Function: FPDFAvail_IsPageAvail -* Check whether a page is ready for loading, if not, get download -* hints. -* -* Parameters: -* avail - Handle to document availability provider returned by -* FPDFAvail_Create -* page_index - Index number of the page. 0 for the first page. -* hints - Pointer to a download hints interface, receiving -* generated hints -* Return value: -* PDF_DATA_ERROR: A common error is returned. It can't tell -* whehter data are availabe or not. -* PDF_DATA_NOTAVAIL: Data are not yet available. -* PDF_DATA_AVAIL: Data are available. -* Comments: -* This function can be called only after FPDFAvail_GetDocument is -* called. Applications should call this function whenever new data -* arrived and process all the generated download hints if any, until -* this function returns PDF_DATA_ERROR or PDF_DATA_AVAIL. Then -* applications can perform page loading. -*/ +// Check if |page_index| is ready for loading, if not, get the +// |FX_DOWNLOADHINTS|. +// +// avail - handle to document availability provider. +// page_index - index number of the page. Zero for the first page. +// hints - pointer to a download hints interface. Populated if +// |page_index| is not available. +// +// Returns one of: +// PDF_DATA_ERROR: A common error is returned. Data availability unknown. +// PDF_DATA_NOTAVAIL: Data not yet available. +// PDF_DATA_AVAIL: Data available. +// +// This function can be called only after |FPDFAvail_GetDocument| is called. +// Applications should call this function whenever new data arrives and process +// all the generated download |hints|, if any, until this function returns +// |PDF_DATA_ERROR| or |PDF_DATA_AVAIL|. Applications can then perform page +// loading. DLLEXPORT int STDCALL FPDFAvail_IsPageAvail(FPDF_AVAIL avail, int page_index, FX_DOWNLOADHINTS* hints); -/** -* Function: FPDFAvail_ISFormAvail -* Check whether Form data is ready for init, if not, get download -* hints. -* -* Parameters: -* avail - Handle to document availability provider returned by -* FPDFAvail_Create -* hints - Pointer to a download hints interface, receiving -* generated hints -* Return value: -* PDF_FORM_ERROR - A common eror, in general incorrect parameters, -* like 'hints' is nullptr. -* PDF_FORM_NOTAVAIL - data not available -* PDF_FORM_AVAIL - data available -* PDF_FORM_NOTEXIST - no form data -* Comments: -* This function can be called only after FPDFAvail_GetDocument is -* called. -* The application should call this function whenever new data arrived, -* and process all the -* generated download hints if any, until the function returns non-zero -* value. Then the -* application can perform page loading. Recommend to call -* FPDFDOC_InitFormFillEnvironment -* after the function returns non-zero value. -*/ +// Check if form data is ready for initialization, if not, get the +// |FX_DOWNLOADHINTS|. +// +// avail - handle to document availability provider. +// hints - pointer to a download hints interface. Populated if form is not +// ready for initialization. +// +// Returns one of: +// PDF_FORM_ERROR: A common eror, in general incorrect parameters. +// PDF_FORM_NOTAVAIL: Data not available. +// PDF_FORM_AVAIL: Data available. +// PDF_FORM_NOTEXIST: No form data. +// +// This function can be called only after |FPDFAvail_GetDocument| is called. +// The application should call this function whenever new data arrives and +// process all the generated download |hints|, if any, until the function +// |PDF_FORM_ERROR|, |PDF_FORM_AVAIL| or |PDF_FORM_NOTEXIST|. +// Applications can then perform page loading. It is recommend to call +// |FPDFDOC_InitFormFillEnvironment| when |PDF_FORM_AVAIL| is returned. DLLEXPORT int STDCALL FPDFAvail_IsFormAvail(FPDF_AVAIL avail, FX_DOWNLOADHINTS* hints); -/** -* Function: FPDFAvail_IsLinearized -* To check whether a document is Linearized PDF file. -* -* Parameters: -* avail - Handle to document availability provider returned by -* FPDFAvail_Create -* Return value: -* PDF_LINEARIZED is a linearize file. -* PDF_NOT_LINEARIZED is not a linearize file. -* PDF_LINEARIZATION_UNKNOWN doesn't know whether the file is a -*linearize file. -* -* Comments: -* It return PDF_LINEARIZED or PDF_NOT_LINEARIZED as soon as -* we have first 1K data. If the file's size less than 1K, it returns -* PDF_LINEARIZATION_UNKNOWN because there is not enough information to -* tell whether a PDF file is a linearized file or not. -* -*/ +// Check whether a document is a linearized PDF. +// +// avail - handle to document availability provider. +// +// Returns one of: +// PDF_LINEARIZED +// PDF_NOT_LINEARIZED +// PDF_LINEARIZATION_UNKNOWN +// +// |FPDFAvail_IsLinearized| will return |PDF_LINEARIZED| or |PDF_NOT_LINEARIZED| +// when we have 1k of data. If the files size less than 1k, it returns +// |PDF_LINEARIZATION_UNKNOWN| as there is insufficient information to determine +// if the PDF is linearlized. DLLEXPORT int STDCALL FPDFAvail_IsLinearized(FPDF_AVAIL avail); #ifdef __cplusplus -} -#endif +} // extern "C" +#endif // __cplusplus #endif // PUBLIC_FPDF_DATAAVAIL_H_ |