FindBinary

FindBinary

The FindBinary method searches file for specified binary data sequence and returns position of matching data in file.

C++

long FindBinary(
  void *BinaryData,             // buffer containing searched data
  long NumberOfElements,        // number of elements in data sequence
  long SizeOfElement,           // size of each element
  long StartingPosition = 0,    // starting position of search
  long Range = -1,              // search range
  long Options = 0              // search options
);

Parameters

BinaryData

Pointer to buffer containing data sequence to be searched for.

NumberOfElements

Number of elements in data sequence to be matched.

SizeOfElement

Size of each element in data sequence, in bytes.

StartingPosition

Starting position of search in file.
If this parameter is -1 search begins at current file position.
If this parameter is 0 and Options have IXF_FIND_REVERSE flag set, search begins from the end of file.

Range

Length of file region to be searched, in bytes.
If this parameter is -1 search is continued until end of file or beginning of file depending on search direction.

Options

Search options, specified as a combination of the following values:

IXF_FIND_REVERSE

backward search (towards beginning of file).

Return Values

If the method succeeds, the return value is the position of matching sequence in file.
The return value is IXF_FAILURE_NOTFOUND if specified data sequence has not been found.
If the method fails, the return value is failure code and error code is set. Call GetError to get error code.

Remarks

Data is searched in file starting from StartingPosition and continuing until matching sequence is found or search region has ended. File data must match entire sequence and must be positioned entirely within search region; it means that 'matching' sequence which starts within search region but ends it is not recognized as matching.

StartingPosition always specifies absolute starting position in file regardless of direction of search. The only exception is when this parameter is 0 and Options have IXF_FIND_REVERSE flag set; in such situation search begins from the end of file.

Method can be used for finding 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 searching 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 FindVariant method for finding structured data.

C++

Parameters

Return Values

Remarks

See Also