6 Content Access Functions
This chapter includes the following sections:
6.1 CAOpenContent
CAOpenContent is used to initiate content access for a file that has been opened by DAOpenDocument.
Prototype
DAERR CAOpenContent( VTHDOC hDoc; VTLPHCONTENT phContent; )
phContent
is not a file handle.
Parameters
-
hDoc: A handle that identifies the document, created by DAOpenDocument.
-
phContent: Pointer to a handle that will receive a value uniquely identifying the document to the Content Access routines. If the function fails, this value will be set to VTHDOC_INVALID.
Return Values
-
DAERR_OK: Open was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
-
DAERR_BADPARAM: One of the function parameters was invalid.
-
DAERR_EMPTYFILE: Empty file.
-
DAERR_PROTECTEDFILE: Password protected or encrypted file.
-
DAERR_SUPFILEOPENFAILS: Supplementary file open failed.
-
DAERR_FILTERNOTAVAIL: The file's type is known, but the appropriate filter is not available.
-
DAERR_FILTERLOADFAILED: An error occurred during the initialization of the appropriate filter.
6.2 CACloseContent
CACloseContent is called to terminate content access for a file.
Prototype
DAERR CACloseContent( VTHCONTENT hContent; )
Parameters
-
hContent: Content Access handle for the document. Must be a handle returned by the CAOpenContent function.
Return Values
-
DAERR_OK: Close was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
-
DAERR_BADPARAM: One of the function parameters was invalid.
6.3 CAReadFirst
This function is called to set the read pointer to the beginning of the document content and to obtain the file identification property for the document.
Prototype
DAERR CAReadFirst( VTHCONTENT hContent; PSCCCAGETCONTENT pGetContent; )
Parameters
-
hContent: Content Access handle for the document. Must be a handle returned by the CAOpenContent function.
-
pGetContent: Pointer to a structure of type SCCCAGETCONTENT (see SCCCAGETCONTENT Structure). CAReadFirst will always fill this structure with the file identification property.
Return Values
-
DAERR_OK: Read was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
-
DAERR_BADPARAM: One of the function parameters was invalid.
6.4 CAReadNext
CAReadNext is called to retrieve text and properties from a file, beginning at the location where the last content was provided.
Prototype
DAERR CAReadNext( VTHCONTENT hContent; PSCCCAGETCONTENT pGetContent; )
Parameters
-
hContent: Content Access handle for the document. Must be a handle returned by the CAOpenContent function.
-
pGetContent: Pointer to a structure of type SCCCAGETCONTENT (see SCCCAGETCONTENT Structure).
Return Values
-
DAERR_OK: Read was successful. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.
-
DAERR_EOF: Read was successful, and the end of the file was encountered.
-
DAERR_ABORT: A fatal error has occurred, read process was aborted.
6.4.1 SCCCAGETCONTENT Structure
typedef struct SCCCAGETCONTENTtag { VTDWORD dwStructSize; VTDWORD dwFlags; VTDWORD dwMaxBufSize; VTVOID * pDataBuf; VTDWORD dwType; VTDWORD dwSubType; VTDWORD dwData1; VTDWORD dwData2; VTDWORD dwData3; VTDWORD dwData4; VTDWORD dwDataBufSize; } SCCCAGETCONTENT, * PSCCCAGETCONTENT;
Each piece of content has a type and a subtype. Based on the type and subtype, the content is described by using up to four VTDWORDs and a data buffer provided by the caller. The dwStructSize, dwFlags, pDataBuf and dwMaxBufSize elements of this structure should be filled by the caller before calling CAReadNext or CAReadFirst.
-
dwStructSize: Initialized by caller to sizeof(SCCCAGETCONTENT).
-
dwFlags: Set by caller. Currently undefined, must be set to 0.
-
dwMaxBufSize: Initialized by caller to the size of the buffer pointed to by pDataBuf.
-
pDataBuf: This pointer must be set by the caller to a buffer at least 1K in size and must be properly byte-aligned (4 bytes). This buffer will be filled with content information based on dwType.
-
dwType: Returns one of the following values (For detailed descriptions of the content types, see Content Description):
-
SCCCA_ANNOTATION: Marks the location of an annotation or sub-document.
-
SCCCA_BEGINTAG: Marks the beginning of a tagged section of the document
-
SCCCA_BREAK: Signals the end of document properties
-
SCCCA_ENDTAG: Marks the end of a tagged section of the document
-
SCCCA_FILEPROPERTY: File identification information
-
SCCCA_GENERATED: Text generated from non-character data
-
SCCCA_OBJECT: Embedded object information
-
SCCCA_SHEET: The name of a sheet in a spreadsheet or presentation
-
SCCCA_STYLECHANGE: Indicates a change in style information
-
SCCCA_TEXT: Normal stream text
-
SCCCA_TREENODELOCATOR: Used by DAOpenRandomTreeRecord and DASaveRandomTreeRecord.
-
-
dwSubType Returns additional information based on
dwType
. Here are some valid subtypes:-
SCCCA_ANNOTATION: Subtype are values like SCCCA_ANNOTATION_FOOTNOTE or SCCCA_ANNOTATION_ENDNOTE. dwData1 links to the corresponding SCCCA_BEGINTAG.
-
SCCCA_HIDDEN: A valid subtype for the SCCCA_TEXT type representing hidden text.
-
SCCCA_FRAME_EX: A valid subtype for the SCCCA_BEGINTAG and SCCCA_ENDTAG types representing extended frames.
-
SCCCA_LINKEDOBJECT: A valid subtype for the SCCCA_BEGINTAG and SCCCA_ENDTAG types representing an object accessible via a link. When dwSubType equals SCCCA_LINKEDOBJECT, dwData1, dwData2, dwData3 and dwData4 will contain values that are used to locate the object.
-
SCCCA_OCE: A valid subtype for the SCCCA_STYLECHANGE type, indicating a change in the character set in the original document. dwData1 returns the new character set.
-
-
dwDatan: Return additional information based on dwType and dwSubType. Several examples are shown above.
-
dwDataBufSize: Returns the actual size of the data placed in the buffer pointed to by pDataBuf.
6.5 CAContentStatus
This function is used to determine if there were conversion problems during a conversion. It will return a structure that describes areas of a conversion that may not have high fidelity with the original document.
Prototype
DA_ENTRYSC DAERR DA_ENTRYMOD CAContentStatus(VTHCONTENT hContent, VTDWORD dwStatusType, VTLPVOID pStatus);
Parameters
-
hContent: Content handle for the document.
-
dwStatusType: Specifies which status information should be filled in pStatus.
-
SCCCA_STATUS_INFORMATION - fills in the SCCCASTATUSINFORMATION structure.
-
-
pStatus: A pointer to a SCCCASTATUSINFORMATION data structure
Return Values
SCCERR_OK: Returned if there were no problems. Otherwise, one of the other SCCERR_ values in sccerr.h is returned.
6.5.1 EXSUBDOCSTATUS Structure
The SCCCASTATUSINFORMATION is defined to be the same as EXSTATUSINFORMATION, which is defined as follows:
typedef struct EXSTATUSINFORMATIONtag { VTDWORD dwVersion; /* version of this structure */ VTBOOL bMissingMap; /* a PDF text run was missing the toUnicode table */ VTBOOL bVerticalText; /* a vertical text run was present */ VTBOOL bTextEffects; /* a run that had unsupported text effects applied. One example is Word Art*/ VTBOOL bUnsupportedCompression; /* a graphic had an unsupported compression */ VTBOOL bUnsupportedColorSpace; /* a graphic had an unsupported color space */ VTBOOL bForms; /* a sub documents had forms */ VTBOOL bRightToLeftTables; /* a table had right to left columns */ VTBOOL bEquations; /* a file had equations*/ VTBOOL bAliasedFont; /* The desired font was missing, but a font alias was used*/ VTBOOL bMissingFont; /* The desired font wasn't present on the system */ VTBOOL bSubDocFailed; /* a sub document was not converted */ VTBOOL bTypeThreeFont; /* a PDF Type 3 embedded font was encountered */ VTBOOL bUnsupportedShading; /* a PDF input file had an unsupported shading type */ VTBOOL bInvalidHTML; /* invalid HTML was encountered */ VTBOOL bVectorObjectLimit; /* The vector object limit was reached */ VTBOOL bInvalidAnnotationNotApplied; /* Annotation/Redaction wasn't displayed */ VTBOOL bInlineImageFound; /* An inline image was found and may not have been rendered */ } EXSTATUSINFORMATION;
Note:
When processing a document, Content Access never uses fonts, so bAliasedFont and bMissingFont will never report TRUE.
bVectorObjectLimit applies only to WebView Export, and bInvalidAnnotationNotApplied applies only to Image Export, PDF Export, and Web View Export.
6.6 CASeek
Move to a position in CA.
Prototype
DA_ENTRYSC DAERR DA_ENTRYMOD CASeek( VTHCONTENT hContent, PSCCDAPOS pPos )
Parameters
-
hContent: CA Content returned from CAOpenContent.
-
pPos: Pointer to be filled with our position information.
Return Values
DAERR_BADPARAM SCCERR_OK: One of the function parameters was invalid.
6.7 CATell
Get position of CA.
Prototype
DA_ENTRYSC DAERR DA_ENTRYMOD CATell ( VTHCONTENT hContent, PSCCDAPOS pPos )
Parameters
-
hContent: CA Content returned from CAOpenContent.
-
pPos: Pointer to be filled with our position information.
Return Values
DAERR_BADPARAM SCCERR_OK: One of the function parameters was invalid.