GetText

C++

long GetText(
  LPSTR TextBuffer,                  // buffer that receives data
  long NumberOfCharacters = -1,      // number of characters to read
  long FilePosition = -1,            // position of data in file
  long Format = 0                    // text format
);

long GetText(
  LPWSTR TextBuffer,                 // buffer that receives data
  long NumberOfCharacters = -1,      // number of characters to read
  long FilePosition = -1,            // position of data in file
  long Format = 0                    // text format
);

BASIC

GetText(
  TextBuffer As Variant,             // variant that receives data
  NumberOfCharacters As Long = -1,   // number of characters to read
  FilePosition As Long = -1,         // position of data in file
  Format As TextFormat = 0           // text format
) As Long

Parameters

TextBuffer

C++

Pointer to buffer that receives data.
Buffer must be large enough to accept at most NumberOfCharacters + 1 characters.
If NumberOfCharacters is -1 buffer must accept entire text regardless of its size.

BASIC

Variant that receives data.
Variant must be of String data type; it must not be an array.
Variant can be uninitialized; in such case it is converted to String.

NumberOfCharacters

Maximum number of characters that can be returned to the user.
If this parameter is -1 entire text is read and its length is determined by either length prefix or terminating character.
This parameter cannot be -1 if IXF_TEXT_STRING flag is set in Format.

FilePosition

Position in file to read data at.
If this parameter is -1 data is read at current file position.

Format

Text formatting options, specified as a combination of the following values:

IXF_TEXT_NULLTERM	text is NULL terminated,
IXF_TEXT_CRLFTERM	text is CR/LF terminated,
IXF_TEXT_STRING	text is a raw character sequence (see Remarks); cannot be combined with other flags.

Return Values

Remarks

IXFile represents text as length-prefixed by default. Actual text data in file is preceded with a long number specifying length of the text in characters. If text is formatted as length-prefixed its length is read first and then the exact number of characters. Only complete text can be read - at least 4 bytes must be available in file for length prefix, which can be zero (empty text).

If text is formatted as NULL- or CR/LF-terminated, characters are read from file until terminating character is found. CR/LF-terminated text can be terminated with either CR, LF or CR/LF pair. End of file also correctly terminates text even if terminating character was not found.

If Format have IXF_TEXT_STRING flag set, text is read as a raw sequence of characters of specified length, without regard to termination or length prefix. This option should be used with care because there is no control of what data is read. Length of text must be known in advance to avoid reading non-textual data.

Unicode version of the method should not be confused with Unicode system calls or Unicode text data. All versions of the method can be used on Unicode and non-Unicode systems depending on your needs; text is always read as a single byte character sequence. Conversion between ANSI and Unicode is performed internally according to current codepage which can be changed with SetCodePage method. See Unicode Support for more information on Unicode system calls, Unicode methods and Unicode text data.

BASIC

See Also