Update to bc8dcc3ede286fbcaac3f741c379297cffff0eea
Same version as used by Chromium 57.0.2987.108
Fixes: 28051413, 34337228
Test: cts-tradefed run cts-dev -m CtsGraphicsTestCases -t android.graphics.pdf.cts
cts-tradefed run cts-dev -m Print -t android.print.pdf.cts
Change-Id: I1bf02cae444c9f08711953c4475af10db2becd58
diff --git a/public/fpdf_dataavail.h b/public/fpdf_dataavail.h
index 0f8ff7d..2413e2b 100644
--- a/public/fpdf_dataavail.h
+++ b/public/fpdf_dataavail.h
@@ -7,8 +7,9 @@
#ifndef PUBLIC_FPDF_DATAAVAIL_H_
#define PUBLIC_FPDF_DATAAVAIL_H_
-#include <stddef.h> // For size_t.
+#include <stddef.h>
+// NOLINTNEXTLINE(build/include)
#include "fpdfview.h"
#define PDF_LINEARIZATION_UNKNOWN -1
@@ -26,248 +27,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.
- */
- FPDF_BOOL (*IsDataAvail)(struct _FX_FILEAVAIL* pThis, size_t offset, size_t size);
+ // 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_