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.
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
||Sets/gets the buffer size. Buffer
size is the amount of bytes read/written from/to the stream in
one Read/Write operation.
||Get/Set the position in the buffer.
Next Put, Get, PutVar, GetVar operation will occur at this
||Code page for UNICODE <-> ANSI
conversions. Ignored in UNICODE mode.
||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
||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.
||Calculates the buffer size over the
data contained by the passed record (SFRecord). Automatically
called by the SFRecord Bind and ReBind methods.
||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).
||Resets the buffer - position and
||Writes a SFRecord or SFFiled to the
buffer from the current buffer position.
||Reads a SFRecrod or SFField from the
buffer (from the current buffer position).
||Writes a value to the buffer - at
the current buffer position.
||Reads a value from the current
||Reads the buffer from a stream.
||Writes the buffer to the stream.
||Moves the current position in the
stream in buffSize units. (buffSize specifies the unit size in
||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).
||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
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.
Windows 95/NT and later
Windows CE 3.0 and later
Pocket PC/Windows Mobile 2003 and later
Windows CE.NET 4 and later