Class TObjStream (unit SuperStream)

Inherits from

TStreamAdapter

Object stream adapters read and write objects from other streams. It is often useful to couple this adapter with a buffering adapter, as object streams frequently read and write with thousands of small byte count io operations.

Constructors


constructor Create(stream : TStream; owned : Boolean; options : TObjStreamOptions);

Construct an object stream.

constructor CreateOnFile(const fn : String; options : TObjStreamOptions; dir : TObjIODirection);

Construct an object stream on a file.


Functions

destructor Destroy;


procedure FlushObjectList;

Flush the list of objects written/read.

function ReadObject : TObject;

Read an object from the stream.

class function ReadObjectInFile(const fn : String; options : TObjStreamOptions) : TObject;

Reads a single object from a file, very conveniently.

function ReadObjectWith(obj : TObject; io : TObjIO; var version : Integer) : TObject;

Read an object from the stream using the given io procedure.

class procedure RegisterClass(cls : TClass; _writer : TObjIO; latest : Integer);

Register class notifies the streaming system of a persistent capable class.

class procedure RegisterClassEx(cls : TClass; _writer : TObjIO; latest : Integer; init : TInitializer);

Register class notifies the streaming system of a persistent capable class.

class procedure RegisterDefaultClasses;

Assigns default io procedures for some of Delphi's classes.

procedure TransferArrays( firstItem : array of const; firstItemAddresses : array of Pointer; counts : array of Integer; direction : TObjIODirection);

Use TransferArrays to load and store multiple arrays of atomic values.

procedure TransferArraysEx( firstItem : array of const; firstItemAddresses : array of Pointer; itemTypes : array of Integer; counts : array of Integer; direction : TObjIODirection);

Use TransferArrays to load and store multiple arrays of atomic values, with additional type information.

procedure TransferBlocks( addresses : array of pointer; sizes : array of integer; direction : TObjIODirection);

Use TransferBlocks to load and store blocks of memory in an object stream.

procedure TransferItem(const item : TVarRec; itemAddress : Pointer; direction : TObjIODirection);

TransferItem is used to read or write a single TVarRec-based object.

procedure TransferItemEx(const item : TVarRec; itemAddress : Pointer; itemType : Integer; direction : TObjIODirection);

TransferItemEx is used to read or write a single TVarRec-based object, supplying a specific type.

procedure TransferItems( items : array of const; itemAddresses : array of pointer; direction : TObjIODirection; var version : Integer);

Use TransferItems to load and store atomic values.

procedure TransferItemsEx( items : array of const; itemAddresses : array of pointer; itemTypes : array of Integer; direction : TObjIODirection; var version : Integer);

Transfer items to and from the stream, with type information.

procedure TransferVarRec(var item : TVarRec; direction : TObjIODirection);

TransferVarRec does the io for a single TVarRec, where that TVarRec is the actual storage location for the value.

procedure WriteObject(obj : TObject);

Write an object to the stream.

class procedure WriteObjectToFile(const fn : String; options : TObjStreamOptions; obj : TObject);

Writes a single object to a file, conveniently.

procedure WriteObjectWith(obj : TObject; io : TObjIO; version : Integer);

Write an object to the stream using the given io procedure.

Properties

Events

event OnObjCreation : TObjCreation

If assigned, this event will be fired whenever a new object is created.

Variables


Constructors


constructor Create(stream : TStream; owned : Boolean; options : TObjStreamOptions);

ParameterDescription
streamThe stream to read or write objects to/from.
ownedIf true, the target stream will be freed when the object stream is freed.
optionsOptions from the TobjStreamOption type.

Construct an object stream.


constructor CreateOnFile(const fn : String; options : TObjStreamOptions; dir : TObjIODirection);

ParameterDescription
fnThe file to use for streaming.
optionsOptions from the TObjStreamOption type.
dirThe IO direction (iodirRead, iodirWrite).

Construct an object stream on a file. The stream will be buffered internally. You must also specify whether you intend to read or write from the stream.


Functions


destructor Destroy;


procedure FlushObjectList;

Flush the list of objects written/read. This is useful if you are resetting the stream to read it again.


function ReadObject : TObject;

Read an object from the stream. The object's class must have been registered. IO routines for subclasses will automatically be called.


class function ReadObjectInFile(const fn : String; options : TObjStreamOptions) : TObject;

ParameterDescription
filenameThe file to read the object from.

Reads a single object from a file, very conveniently.


function ReadObjectWith(obj : TObject; io : TObjIO; var version : Integer) : TObject;

ParameterDescription
objAn already constructed empty object to read values into.
ioThe io procedure to use for this read or write only.
versionThe version number to pass to the io procedure.
callSuperClassIOIf true, the object's superclass io procedure will be called after the specified io procedure is called.

Read an object from the stream using the given io procedure.


class procedure RegisterClass(cls : TClass; _writer : TObjIO; latest : Integer);

ParameterDescription
clsThe class being registered.
_writerAn io procedure for the class.
latestThe current version number for the class (an integer). The version number will usually be incremented each time the structure of the object changes.

Register class notifies the streaming system of a persistent capable class.


class procedure RegisterClassEx(cls : TClass; _writer : TObjIO; latest : Integer; init : TInitializer);

ParameterDescription
clsThe class being registered.
_writerAn io procedure for the class.
latestThe current version number for the class (an integer). The version number will usually be incremented each time the structure of the object changes.
initObject initializer.

Register class notifies the streaming system of a persistent capable class.


class procedure RegisterDefaultClasses;

Assigns default io procedures for some of Delphi's classes. If this is not called, io procedures will have to be registered for all classes. IO procedures are registered for TStringList and TObjList. TObjList is a list of objects, and is contained within this unit.


procedure TransferArrays( firstItem : array of const; firstItemAddresses : array of Pointer; counts : array of Integer; direction : TObjIODirection);

ParameterDescription
firstItemAn open array of the first item of each array.
firstItemAddressesAn open array of the addresses of the first item in each array.
countsAn open array containing a count for each array to be written.
directioniodirRead or iodirWrite, depending on whether read or write is desired.

Use TransferArrays to load and store multiple arrays of atomic values.


procedure TransferArraysEx( firstItem : array of const; firstItemAddresses : array of Pointer; itemTypes : array of Integer; counts : array of Integer; direction : TObjIODirection);

ParameterDescription
firstItemAn open array of the first item of each array.
firstItemAddressesAn open array of the addresses of the first item in each array.
itemTypesAn open array of ssvt constants indicating the type of each array.
countsAn open array containing a count for each array to be written.
directioniodirRead or iodirWrite, depending on whether read or write is desired.

Use TransferArrays to load and store multiple arrays of atomic values, with additional type information.


procedure TransferBlocks( addresses : array of pointer; sizes : array of integer; direction : TObjIODirection);

ParameterDescription
addressesAn open array of pointers to the blocks.
sizesAn open array of the sizes of each block.
directioniodirRead or iodirWrite, depending on whether read or write is desired.

Use TransferBlocks to load and store blocks of memory in an object stream.


procedure TransferItem(const item : TVarRec; itemAddress : Pointer; direction : TObjIODirection);

ParameterDescription
itemThe item to transfer.
itemAddressWhere the item is.
directionWhether to read or write.

TransferItem is used to read or write a single TVarRec-based object. This is very useful for writing the SDL classes, which store DObjects that are equivalent to TVarRec.


procedure TransferItemEx(const item : TVarRec; itemAddress : Pointer; itemType : Integer; direction : TObjIODirection);

ParameterDescription
itemThe item to transfer.
itemAddressWhere the item is.
itemTypeThe type of the variable (ssvt constant).
directionWhether to read or write.

TransferItemEx is used to read or write a single TVarRec-based object, supplying a specific type.


procedure TransferItems( items : array of const; itemAddresses : array of pointer; direction : TObjIODirection; var version : Integer);

ParameterDescription
itemsAn array of items to read or write. The items should be encased in square brackets: [a,b,c]. This is Delphi's open array syntax.
itemAddressesPointers to each of the variables passed in items, also in open array format: [@a, @b, @c].
directionEither iodirRead or iodirWrite, depending on whether objects are being read or written.
versionThis will contain the version number of the object read in.

Use TransferItems to load and store atomic values. Be careful with floating point -- it doesn't provide a way to do single and double, yet, because there's no way to distinguish those types. If you want to do singles, doubles, or TDateTime, use the TransferItemsEx call instead, which lets you specify the types of your members.


procedure TransferItemsEx( items : array of const; itemAddresses : array of pointer; itemTypes : array of Integer; direction : TObjIODirection; var version : Integer);

ParameterDescription
itemsAn array of items to read or write. The items should be encased in square brackets: [a,b,c]. This is Delphi's open array syntax.
itemAddressesPointers to each of the variables passed in items, also in open array format: [@a, @b, @c].
itemTypesThe itemTypes open array exists so that atomic types not handled by Delphi's open array system can be used. Each variable in the items parameter should have, in itemTypes, a corresponding type indicator. Note that this is usually only necessary of SINGLE or DOUBLE values are going to be written.

Here are the possible values:

  • ssvtNone
  • ssvtSingle
  • ssvtDouble
  • ssvtInteger
  • ssvtBoolean
  • ssvtChar
  • ssvtExtended
  • ssvtString
  • ssvtPointer
  • ssvtPChar
  • ssvtObject
  • ssvtClass
  • ssvtWideChar
  • ssvtPWideChar
  • ssvtAnsiString
  • ssvtCurrency
  • ssvtVariant
  • ssvtInterface
  • ssvtWideString
directionEither iodirRead or iodirWrite, depending on whether objects are being read or written.
versionThis will contain the version number of the object read in.

Transfer items to and from the stream, with type information. If you need to distinguish between different forms of floating point, use this routine instead. itemTypes is an array of ssvt codes (see the top of this file) that correspond to the atomic data types. You can use ssvtNone if you want the default mechanism to handle it. The best way to use this is to stream your singles and doubles first, then the rest of your items. The list of itemtypes doesn't have to be the same length as the list of items to transfer -- ssvtNone will be assumed for the remaining items if the list is shorter.

The most common use of this routine is to transfer single or double floating point values, whose type is not handled accurately by the array of const system Delphi provides.


procedure TransferVarRec(var item : TVarRec; direction : TObjIODirection);

TransferVarRec does the io for a single TVarRec, where that TVarRec is the actual storage location for the value.


procedure WriteObject(obj : TObject);

ParameterDescription
objThe object to write.

Write an object to the stream. The object's class must have been registered. IO routines for subclasses will automatically be called.


class procedure WriteObjectToFile(const fn : String; options : TObjStreamOptions; obj : TObject);

ParameterDescription
filenameThe file to write the object info.
objThe object to write. The object must have its class registered.

Writes a single object to a file, conveniently.


procedure WriteObjectWith(obj : TObject; io : TObjIO; version : Integer);

ParameterDescription
objThe object to write.
ioThe io procedure to use.
versionThe version number that will be passed to the io procedure.
callSuperClassIOIndicates whether the object's superclass io procedures will be called after the specified io procedure is called.

Write an object to the stream using the given io procedure.


Properties


Events


event OnObjCreation : TObjCreation

If assigned, this event will be fired whenever a new object is created. This gives the program a chance to alter the construction of the new object.


Variables