Storages & Files SFFilter object
See also object creation information - ClassID/ProgID 

SFFilter object is the bridge between the SFRecord (and its fields) and the physical media - the stream/file. It defines the format of the fields and how they are written and read to/from the stream. By default SFRecord creates the default filter if nothing else is specified and it can be accessed through the SFRecord.Filter property. Therefore it is quite possible you will never need to create SFFilter explicitly, but however some of its settings are important and you will need to control them in order to be able to read/write certain file formats. 

The properties of the SFFilter object useful if working through a SFRecord object are: codePage, unicodeText and StreamBegin. You do not need to access any other method or property when working with records.

Advanced usage

The communication with the stream is implemented through a memory buffer. In other words all the variables, records or fields are written first to the buffer and are committed to the stream only when the Write method is called. The SFRecrod object automatically handles this transparently for the application. You need to be aware of the buffer/stream nature only if you are going to perform advanced operation using the filter directly. 

It is possible to read/write typed values from/to a stream without a SFRecord object - directly through a filter. This technique can be very convenient for advanced developers implementing persistence functionality or in cases when the stream does not contain well defined records and you can guess the type and size of the next value only sequentially. This is advanced technique and there is no need to read any details on it unless you do not need such a functionality.  

SFFilter members
buffSize Sets/gets the buffer size. Buffer size is the amount of bytes read/written from/to the stream in one Read/Write operation.
bufferPos Get/Set the position in the buffer. Next Put, Get, PutVar, GetVar operation will occur at this position
codePage Code page for UNICODE <-> ANSI conversions. Ignored in UNICODE mode.
unicodeText Sets/Gets the UNICODE flag. If set to true all the strings are UNICODE if set to ANSI they are ANSI and are translated using the code page provided by the codePage property.
StreamBegin The zero position of the stream in bytes from the physical beginning of the stream. Any subsequent Seek operations over the filter object will assume this position as stream beginning.
CalcBuffer Calculates the buffer size over the data contained by the passed record (SFRecord). Automatically called by the SFRecord Bind and ReBind methods.
Buffer Returns the buffer as binary (VT_UI1 | VT_ARRAY). The format is the same used by all the objects that support binary data (compatible with binary methods of objects in ASP. ADO and so on).
Reset Resets the buffer - position and content.
Put Writes a SFRecord or SFFiled to the buffer from the current buffer position.
Get Reads a SFRecrod or SFField from the buffer (from the current buffer position).
PutVar Writes a value to the buffer - at the current buffer position.
GetVar Reads a value from the current buffer position.
Read Reads the buffer from a stream.
Write Writes the buffer to the stream.
Seek Moves the current position in the stream in buffSize units. (buffSize specifies the unit size in bytes).
GetSize/SetSize Calculates/Sets the size of a stream in buffSize units. E.g. how many records exist in the entire stream (from the beginning as defined by the StreamBegin property).
ByteOrder/UnicodeByteOrder Get/set the byte ordering flags for numeric or UNICODE text conversions.


The buffer/stream architecture allows the units read/written from/to the stream to differ from the actual size of the values read/written. E.g. unused fields can be skipped in a safe manner.

Note that the SFFilter is the low level of the binary stream access API. It is very simple to use SFRecord which will automatically drive the filter for you. But record based access is appropriate only for files (file formats) that consist of strictly defined records. Therefore low level access is opened for you in case record based abstraction is not enough. Even if low level access is used you can use it in combination with SFRecord/SFField objects, but the buffer size calculation depends on you. The filter is capable of calculating the buffer size required to hold the record, but if you want to add some custom data or hide part of the record you can set greater size.

The buffer is navigated too. The buffPos property holds the current position in the buffer and the application is able to perform variable read/write operations at any location in the buffer.  

What the filters are supposed to do?

Current version of the library ships with only one filter but future versions will supply more filters for less popular situations. For example the byte order is different on the different machines and for example integer value will be saved on Macintosh in order different from the order used by the Intel based PC. Thus the filter's purpose is to perform this part of the work transparently. This includes also string conversions and some other tasks.

Supported on:

Windows 95/NT and later
Windows CE 3.0 and later
Pocket PC/Windows Mobile 2003 and later
Windows CE.NET 4 and later