5 Text Access Functions

The Text Access module is required to use these functions.

This chapter includes the following sections:

Section 5.1, "TAOpenText"
Section 5.2, "TACloseText"
Section 5.3, "TAReadFirst"
Section 5.4, "TAReadNext"

5.1 TAOpenText

TAOpenText is used to initiate text access for a file that has been opened by DAOpenDocument.

Prototype

DAERR TAOpenText(
   VTHDOC     hDoc,
   VTLPHTEXT  phText )

phContent is not a file handle.

Parameters

hDoc: A handle that identifies the document, created by DAOpenDocument.
phText: Pointer to a handle that will receive a value uniquely identifying the document to the Text 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.

5.2 TACloseText

TACloseText is called to terminate text access for a file.

Prototype

DAERR TACloseText(
   VTHTEXT   hText )

Parameters

hText: Text Access handle for the document. Must be a handle returned by the TAOpenText 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.

5.3 TAReadFirst

This function is called to set the read pointer to the beginning of the document and to retrieve the first block of text.

Prototype

DAERR TAReadFirst(
   VTHTEXT    hText,
   VTLPBYTE   pTextBuf,
   VTDWORD    dwBufSize,
   VTLPDWORD  pBufCount )

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 hText, pTextBuf, dwBufSize, and pBufCount elements of this structure should be filled by the caller before calling TAReadNext or TAReadFirst.

Parameters

hText: Text Access handle for the document. Must be a handle returned by the TAOpenText function.
pTextBuf: Pointer to a buffer to receive the first block of text. NULL characters are included in the text buffer to act as fillers for text which was in the original file but is not part of the document body (revision deletions and document properties). Special characters are manufactured by the technology due to special formatting attributes. For more information, see Section 5.4, "TAReadNext."
dwBufSize: Size of the buffer pointed to by pTextBuf.
pBufCount: Pointer to a DWORD that will receive the actual size of the data copied into pTextBuf. Note that for DBCS and Unicode character sets, this will not necessarily be the character count.

Return Values

DAERR_OK: The 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.

5.4 TAReadNext

TAReadNext is called to retrieve the next block of text from the file, beginning at the location where the last call to TAReadNext or TAReadFirst ended.

Prototype

DAERR TAReadNext(
   VTHTEXT    hText,
   VTLPBYTE   pTextBuf,
   VTDWORD    dwBufSize,
   VTLPDWORD  pBufCount )

Parameters

hText: Text Access handle for the document. Must be a handle returned by the TAOpenText function.
pTextBuf: Pointer to a buffer to receive the block of text. NULL characters are included in the text buffer to act as fillers for text which was in the original file but is not part of the document body (revision deletions and document properties). Special characters are manufactured by the technology due to special formatting attributes.
dwBufSize: This is the size of the buffer pointed to by pTextBuf.
pBufCount: Pointer to a DWORD that will receive the actual size of the data copied into pTextBuf. Note that for DBCS and Unicode character sets, this will not necessarily be the character count.

Return Values

DAERR_OK: The 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.

Special Text Character Substitutions

Email Delimiter: 0x09
End of Database Record: 0x0A
End of File: 0x0D
End of Paragraph: 0x0D
End of Table Cell: 0x0D
End of Table Row: 0x0D
Hard Hyphen: 0x2D
Hard Line Break: 0x0A
Hard Page Break: 0x0C
Hard Space: 0x20
Section Separator: 0x0D
Syllable Hyphen: 0x2D
Tab: 0x09
Word Delimiter: 0x20