Adding Custom Information to Data Packets
Go Up to Controlling What Information Is Included in Data Packets
Dataset providers can add application-defined information to data packets using the Datasnap.Provider.TDataSetProvider.OnGetDataSetProperties event. This information is encoded as an OleVariant, and stored under a name you specify. Client datasets can then retrieve the information using their GetOptionalParam method. You can also specify that the information be included in delta packets that the client dataset sends when updating records. In this case, the client dataset may never be aware of the information, but the provider can send a round-trip message to itself.
When adding custom information in the OnGetDataSetProperties event, each individual attribute (sometimes called an "optional parameter") is specified using a Variant array that contains three elements: the name (a string), the value (a Variant), and a boolean flag indicating whether the information should be included in delta packets when the client applies updates. Add multiple attributes by creating a Variant array of Variant arrays. For example, the following OnGetDataSetProperties event handler sends two values, the time the data was provided and the total number of records in the source dataset. Only the time the data was provided is returned when client datasets apply updates:
Delphi:
procedure TMyDataModule1.Provider1GetDataSetProperties(Sender: TObject; DataSet: TDataSet; out Properties: OleVariant);
begin
Properties := VarArrayCreate([0,1], varVariant);
Properties[0] := VarArrayOf(['TimeProvided', Now, True]);
Properties[1] := VarArrayOf(['TableSize', DataSet.RecordCount, False]);
end;
C++:
void __fastcall TMyDataModule1::Provider1GetDataSetProperties(TObject *Sender, TDataSet *DataSet, out OleVariant Properties)
{
int ArrayBounds[2];
ArrayBounds[0] = 0;
ArrayBounds[1] = 1;
Properties = VarArrayCreate(ArrayBounds, 1, varVariant);
Variant values[3];
values[0] = Variant("TimeProvided");
values[1] = Variant(Now());
values[2] = Variant(true);
Properties[0] = VarArrayOf(values,2);
values[0] = Variant("TableSize");
values[1] = Variant(DataSet->RecordCount);
values[2] = Variant(false);
Properties[1] = VarArrayOf(values,2);
}
When the client dataset applies updates, the time the original records were provided can be read in the provider's Provider.TDataSetProvider.OnUpdate event:
Delphi:
procedure TMyDataModule1.Provider1UpdateData(Sender: TObject; DataSet: TCustomClientDataSet);
var
WhenProvided: TDateTime;
begin
WhenProvided := DataSet.GetOptionalParam('TimeProvided');
// …
end;
C++:
void __fastcall TMyDataModule1::Provider1UpdateData(TObject *Sender, TCustomClientDataSet *DataSet)
{
Variant WhenProvided = DataSet->GetOptionalParam("TimeProvided");
// …
}