GetBinary

GetBinary

The GetBinary method reads binary data sequence from file and returns number of elements actually read. File position is moved forward by the number of bytes read.

C++

long GetBinary(
  void *BinaryBuffer,              // buffer that receives data
  long NumberOfElements,           // number of elements to read
  long SizeOfElement,              // size of each element
  long FilePosition = -1           // position of data in file
);

Parameters

BinaryBuffer: Pointer to buffer that receives data.
Buffer must be large enough to accept at most NumberOfElements * SizeOfElement bytes of data.
NumberOfElements: Number of elements in data sequence to read.
SizeOfElement: Size of each element, in bytes.
FilePosition: Position in file to read data at.
If this parameter is -1 data is read at current file position.

Return Values

If the method succeeds, the return value is the number of elements actually read.
The return value is 0 if end of file was encountered or there is not enough data in file.
If the method fails, the return value is failure code and error code is set. Call GetError to get error code.

Remarks

Method returns the number of full elements actually read, which may be less than expected if end of file is encountered prematurely. Only complete elements can be read - at least SizeOfElement bytes must be available in file for reading to get next element. If there is not enough data in file for next full element processing is finished and file is positioned after last complete element.

Method can be used for reading structured data with fields of various types. In such case entire structure should be treated as a sequence of bytes (SizeOfElement should be 1) whose length is equal to total size of the structure and is specified in NumberOfElements. File data must be, however, in machine (little-endian) byte order because there is no way to determine sizes of each field in the structure for big-endian conversion. Method can be also used for reading data of simple types that are not directly supported like Boolean, Date, Currency or Decimal; in such case size of elements must be specified to properly handle big-endian conversion.

Method is available only in C++ component because binary (user defined) data types are not allowed in COM. Visual Basic developers should use GetVariant method for reading structured data.

C++

Parameters

Return Values

Remarks

See Also