Custom Protocol — Dataset

Overview

This protocol inherits from Protocol Default and it's useful if you want to broadcast dataset changes over clients connected to this protocol. It can be used in 2 modes:

At a glance

Features

• Native Delphi implementation with full ANSI/Unicode support.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Public events

The component exposes the following published events; consult the online help for full event-handler signatures.

Quick Start

Drop the component on a form, configure the properties below and activate it. The snippet that follows shows the typical Dataset subprotocol client and server pair configuration.

Delphi (VCL / FireMonkey)

// --- server side: bind the dataset and broadcast the changes
oServer := TsgcWebSocketServer.Create(nil);
oServer.Port := 80;

oServerDataset := TsgcWSPServer_Dataset.Create(nil);
oServerDataset.Server := oServer;
oServerDataset.DataSet := DMQuotes.cdsQuotes;
oServerDataset.NotifyUpdates := True;
oServerDataset.ApplyUpdates := True;
oServerDataset.UpdateMode := upWhereAll;
oServer.Active := True;

// --- client side: bind a local dataset and receive the changes
oClient := TsgcWebSocketClient.Create(nil);
oClient.Host := '127.0.0.1';
oClient.Port := 80;

oClientDataset := TsgcWSPClient_Dataset.Create(nil);
oClientDataset.Client := oClient;
oClientDataset.DataSet := DMQuotes.cdsQuotes;
oClientDataset.AutoSubscribe := True;
oClient.Active := True;

C++ Builder

// --- server side
oServer = new TsgcWebSocketServer(this);
oServer->Port = 80;

oServerDataset = new TsgcWSPServer_Dataset(this);
oServerDataset->Server = oServer;
oServerDataset->DataSet = DMQuotes->cdsQuotes;
oServerDataset->NotifyUpdates = true;
oServerDataset->ApplyUpdates = true;
oServerDataset->UpdateMode = upWhereAll;
oServer->Active = true;

// --- client side
oClient = new TsgcWebSocketClient(this);
oClient->Host = "127.0.0.1";
oClient->Port = 80;

oClientDataset = new TsgcWSPClient_Dataset(this);
oClientDataset->Client = oClient;
oClientDataset->DataSet = DMQuotes->cdsQuotes;
oClientDataset->AutoSubscribe = true;
oClient->Active = true;

.NET (C#)

// The Dataset subprotocol builds on TDataSet, a VCL and FireMonkey type,
// so it ships in the Delphi and C++ Builder libraries only. For a .NET
// client, publish the row changes over the sgc subprotocol instead:
oClientSGC = new TsgcWSPClient_sgc();
oClientSGC.Client = oClient;
oClientSGC.Subscribe("quotes");
oClientSGC.OnEvent += OnSGCEventEvent;

Common scenarios

Each scenario shows the configuration and method calls needed to drive the component through a specific real-world flow. Every identifier below is taken from the component declaration shipped with the library. The Dataset subprotocol is a Delphi and C++ Builder feature, so the samples below cover those two languages.

1 · Replicating the table, and manual subscriptions

With AutoSubscribe set to True the client subscribes to every field of the bound dataset as soon as the connection is up. Leave it False and call Subscribe_all yourself, or UnSubscribe_all to stop receiving updates. Synchronize asks the server for a fresh snapshot of the whole table, and GetMetaData requests the field definitions only.

oClientDataset.AutoSubscribe := False;
oClientDataset.OnBeforeSynchronize := OnBeforeSynchronizeEvent;
oClientDataset.OnAfterSynchronize := OnAfterSynchronizeEvent;

// after the connection is established
oClientDataset.Subscribe_all;
oClientDataset.Synchronize;
oClientDataset.GetMetaData;

// stop receiving updates
oClientDataset.UnSubscribe_all;

// on the server, push a fresh snapshot to one connection
oServerDataset.Synchronize(Connection);

oClientDataset->AutoSubscribe = false;
oClientDataset->OnBeforeSynchronize = OnBeforeSynchronizeEvent;
oClientDataset->OnAfterSynchronize = OnAfterSynchronizeEvent;

oClientDataset->Subscribe_all();
oClientDataset->Synchronize();
oClientDataset->GetMetaData();

oClientDataset->UnSubscribe_all();

oServerDataset->Synchronize(Connection);

2 · Intercepting record changes

OnBeforeNewRecord, OnBeforeUpdateRecord and OnBeforeDeleteRecord fire before the incoming change is applied. Each handler receives the target dataset and the raw JSON payload, plus a Handled var parameter, set it to True and the component skips its own processing so you can apply the change yourself. The matching OnAfterNewRecord, OnAfterUpdateRecord and OnAfterDeleteRecord fire once the change has been applied.

procedure TForm1.OnBeforeUpdateRecordEvent(Connection: TsgcWSConnection;
  const Dataset: TDataset; const JSON: IsgcObjectJSON;
  var Handled: Boolean);
begin
  // reject the update and handle it manually
  Handled := Dataset.FieldByName('READONLY').AsBoolean;
end;

procedure TForm1.OnAfterUpdateRecordEvent(Connection: TsgcWSConnection;
  const Dataset: TDataset);
begin
  DoLog('row updated');
end;

oClientDataset.OnBeforeUpdateRecord := OnBeforeUpdateRecordEvent;
oClientDataset.OnAfterUpdateRecord := OnAfterUpdateRecordEvent;

void __fastcall TForm1::OnBeforeUpdateRecordEvent(TsgcWSConnection *Connection,
  TDataset *Dataset, const _di_IsgcObjectJSON JSON, bool &Handled)
{
  Handled = Dataset->FieldByName("READONLY")->AsBoolean;
}

void __fastcall TForm1::OnAfterUpdateRecordEvent(TsgcWSConnection *Connection,
  TDataset *Dataset)
{
  DoLog("row updated");
}

oClientDataset->OnBeforeUpdateRecord = OnBeforeUpdateRecordEvent;
oClientDataset->OnAfterUpdateRecord = OnAfterUpdateRecordEvent;

3 · Update mode, formatting and payload encoding

UpdateMode decides which fields go into the WHERE clause of an update, upWhereAll sends every field, upWhereChanged only the modified ones, and upRefreshAll refreshes the whole record afterwards. FormatSettings pins the date, time and decimal formats so two machines with different locales agree on the wire representation, and EncodeBase64 wraps text payloads that would otherwise need escaping.

oServerDataset.UpdateMode := upWhereChanged;
oServerDataset.AutoSynchronize := True;
oServerDataset.NotifyUpdates := True;
oServerDataset.NotifyDeletes := True;
oServerDataset.AutoEscapeText := True;
oServerDataset.EncodeBase64 := False;
oServerDataset.FormatSettings.ShortDateFormat := 'yyyy-mm-dd';

oClientDataset.UpdateMode := upWhereChanged;
oClientDataset.ApplyUpdates := True;
oClientDataset.NotifyUpdates := True;

oServerDataset->UpdateMode = upWhereChanged;
oServerDataset->AutoSynchronize = true;
oServerDataset->NotifyUpdates = true;
oServerDataset->NotifyDeletes = true;
oServerDataset->AutoEscapeText = true;
oServerDataset->EncodeBase64 = false;
oServerDataset->FormatSettings->DateFormat = "yyyy-mm-dd";

oClientDataset->UpdateMode = upWhereChanged;
oClientDataset->ApplyUpdates = true;
oClientDataset->NotifyUpdates = true;

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.