Custom Protocol — Files

Overview

This protocol allows sending files using binary WebSocket transport. It can handle big files with a low memory usage.

At a glance

Features

• Publish/subscribe message pattern to provide one-to-many message distribution and decoupling of applications.
• Acknowledgment of messages sent.
• Implements QoS (Quality of Service) for file delivery.
• Optionally can request Authorization for files received.
• Low memory usage.

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 Files subprotocol client and server pair configuration.

Delphi (VCL / FireMonkey)

// --- server side
oServer := TsgcWebSocketServer.Create(nil);
oServer.Port := 80;
oServerFiles := TsgcWSPServer_Files.Create(nil);
oServerFiles.Server := oServer;
oServerFiles.Files.SaveDirectory := 'C:\server\inbox\';
oServer.Active := True;

// --- client side
oClient := TsgcWebSocketClient.Create(nil);
oClient.Host := '127.0.0.1';
oClient.Port := 80;
oClientFiles := TsgcWSPClient_Files.Create(nil);
oClientFiles.Client := oClient;
oClientFiles.Files.BufferSize := 8192;
oClientFiles.Files.SaveDirectory := 'C:\inbox\';
oClientFiles.Files.QoS.Level := qosLevel1;
oClientFiles.OnFileSent := OnFileSentEvent;
oClientFiles.OnFileReceived := OnFileReceivedEvent;
oClient.Active := True;

oClientFiles.Subscribe('files');
oClientFiles.SendFile('C:\data\report.pdf');

C++ Builder

// --- server side
oServer = new TsgcWebSocketServer(this);
oServer->Port = 80;
oServerFiles = new TsgcWSPServer_Files(this);
oServerFiles->Server = oServer;
oServerFiles->Files->SaveDirectory = "C:\\server\\inbox\\";
oServer->Active = true;

// --- client side
oClient = new TsgcWebSocketClient(this);
oClient->Host = "127.0.0.1";
oClient->Port = 80;
oClientFiles = new TsgcWSPClient_Files(this);
oClientFiles->Client = oClient;
oClientFiles->Files->BufferSize = 8192;
oClientFiles->Files->SaveDirectory = "C:\\inbox\\";
oClientFiles->Files->QoS->Level = qosLevel1;
oClientFiles->OnFileSent = OnFileSentEvent;
oClientFiles->OnFileReceived = OnFileReceivedEvent;
oClient->Active = true;

oClientFiles->Subscribe("files");
oClientFiles->SendFile("C:\\data\\report.pdf");

.NET (C#)

// --- server side
oServer = new TsgcWebSocketServer();
oServer.Port = 80;
oServerFiles = new TsgcWSPServer_Files();
oServerFiles.Server = oServer;
oServerFiles.Files.SaveDirectory = @"C:\server\inbox\";
oServer.Active = true;

// --- client side
oClient = new TsgcWebSocketClient();
oClient.Host = "127.0.0.1";
oClient.Port = 80;
oClientFiles = new TsgcWSPClient_Files();
oClientFiles.Client = oClient;
oClientFiles.Files.BufferSize = 8192;
oClientFiles.Files.SaveDirectory = @"C:\inbox\";
oClientFiles.Files.QoS.Level = TwsQoS.qosLevel1;
oClientFiles.OnFileSent += OnFileSentEvent;
oClientFiles.OnFileReceived += OnFileReceivedEvent;
oClient.Active = true;

oClientFiles.Subscribe("files");
oClientFiles.SendFile(@"C:\data\report.pdf");

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.

1 · Receiving a file and authorising it first

Every incoming transfer raises OnFileReceivedAuthorization before a single byte is written. The handler receives the proposed file name in a var parameter, so you can rename the file, and an Accept flag you can clear to refuse the transfer. Progress arrives on OnFileReceivedFragment, completion on OnFileReceived, and failures on OnFileReceivedError.

procedure TForm1.OnFileReceivedAuthorizationEvent(Connection: TsgcWSConnection;
  const aMessage: TsgcWSMessageFile; var aFileName: string;
  var Accept: Boolean);
begin
  Accept := ExtractFileExt(aMessage.FileName) <> '.exe';
  aFileName := 'received_' + aMessage.FileName;
end;

procedure TForm1.OnFileReceivedFragmentEvent(Connection: TsgcWSConnection;
  const aMessage: TsgcWSMessageFile; var Cancel: Boolean);
begin
  ProgressBar1.Position :=
    Round(aMessage.FilePosition / aMessage.FileSize * 100);
end;

procedure TForm1.OnFileReceivedEvent(Connection: TsgcWSConnection;
  const aMessage: TsgcWSMessageFile);
begin
  DoLog('received ' + aMessage.FileName);
end;

void __fastcall TForm1::OnFileReceivedAuthorizationEvent(
  TsgcWSConnection *Connection, TsgcWSMessageFile *aMessage,
  String &aFileName, bool &Accept)
{
  Accept = ExtractFileExt(aMessage->FileName) != ".exe";
  aFileName = "received_" + aMessage->FileName;
}

void __fastcall TForm1::OnFileReceivedFragmentEvent(
  TsgcWSConnection *Connection, TsgcWSMessageFile *aMessage, bool &Cancel)
{
  ProgressBar1->Position =
    (int)(aMessage->FilePosition * 100 / aMessage->FileSize);
}

void __fastcall TForm1::OnFileReceivedEvent(TsgcWSConnection *Connection,
  TsgcWSMessageFile *aMessage)
{
  DoLog("received " + aMessage->FileName);
}

void OnFileReceivedAuthorizationEvent(TsgcWSConnection Connection,
  TsgcWSMessageFile MessageFile, ref string FileName, ref bool Accept)
{
  Accept = Path.GetExtension(MessageFile.FileName) != ".exe";
  FileName = "received_" + MessageFile.FileName;
}

void OnFileReceivedFragmentEvent(TsgcWSConnection Connection,
  TsgcWSMessageFile MessageFile, ref bool Cancel)
{
  progressBar1.Value =
    (int)(MessageFile.FilePosition * 100 / MessageFile.FileSize);
}

void OnFileReceivedEvent(TsgcWSConnection Connection,
  TsgcWSMessageFile MessageFile)
{
  DoLog("received " + MessageFile.FileName);
}

2 · Big files, chunk size and acknowledged delivery

Files.BufferSize sets the size of every fragment, so a large file is streamed in pieces rather than held in memory. Files.QoS.Level set to qosLevel1 or qosLevel2 makes the peer acknowledge each fragment, and Interval and Timeout control the retry cadence. The SendFile overload that takes an explicit size and QoS lets you override the component defaults for one transfer.

oClientFiles.Files.BufferSize := 65536;
oClientFiles.Files.QoS.Level := qosLevel1;
oClientFiles.Files.QoS.Interval := 1000;
oClientFiles.Files.QoS.Timeout := 30000;
oClientFiles.Files.ClearSentStreamsOnDisconnect := False;

// per-transfer override: file name, chunk size, QoS, data, file id
oClientFiles.SendFile('C:\data\archive.zip', 65536, qosLevel1,
  '', 'archive-1');

oClientFiles->Files->BufferSize = 65536;
oClientFiles->Files->QoS->Level = qosLevel1;
oClientFiles->Files->QoS->Interval = 1000;
oClientFiles->Files->QoS->Timeout = 30000;
oClientFiles->Files->ClearSentStreamsOnDisconnect = false;

oClientFiles->SendFile("C:\\data\\archive.zip", 65536, qosLevel1,
  "", "archive-1");

oClientFiles.Files.BufferSize = 65536;
oClientFiles.Files.QoS.Level = TwsQoS.qosLevel1;
oClientFiles.Files.QoS.Interval = 1000;
oClientFiles.Files.QoS.Timeout = 30000;
oClientFiles.Files.ClearSentStreamsOnDisconnect = false;

oClientFiles.SendFile(@"C:\data\archive.zip", 65536,
  TwsQoS.qosLevel1, "", "archive-1");

3 · Sending a file from the server

On the server side SendFile takes the target connection Guid as its first argument, so you can push a file to one client. BroadcastFile sends the same file to every connected client, optionally narrowed to a channel.

// push to one client, identified by its connection Guid
oServerFiles.SendFile(Connection.Guid, 'C:\server\out\manual.pdf');

// push to everyone
oServerFiles.BroadcastFile('C:\server\out\manual.pdf');

oServerFiles->SendFile(Connection->Guid, "C:\\server\\out\\manual.pdf");

oServerFiles->BroadcastFile("C:\\server\\out\\manual.pdf");

oServerFiles.SendFile(Connection.Guid, @"C:\server\out\manual.pdf");

oServerFiles.BroadcastFile(@"C:\server\out\manual.pdf");

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.