Custom Protocol — Presence

Overview

Presence protocol allows you to know who is subscribed to a channel, this makes it easier to create chat applications and know who is online, example: game users, chat rooms, users viewing the same document...

At a glance

Features

• By default user is identified by a name, but this can be customized passing more data: email, company, twitter...
• Events to Authorize if a Channel can be created, if a member is allowed...
• Every time a new member joins a channel, all members are notified.
• Publish messages to all channel subscribers.
• 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 Presence subprotocol client and server pair configuration.

Delphi (VCL / FireMonkey)

// --- server side
oServer := TsgcWebSocketServer.Create(nil);
oServer.Port := 80;
oServerPresence := TsgcWSPServer_Presence.Create(nil);
oServerPresence.Server := oServer;
oServer.Active := True;

// --- client side
oClient := TsgcWebSocketClient.Create(nil);
oClient.Host := '127.0.0.1';
oClient.Port := 80;
oClientPresence := TsgcWSPClient_Presence.Create(nil);
oClientPresence.Client := oClient;
oClientPresence.Presence.Name := 'alice';
oClientPresence.Presence.Info.Values['avatar'] := 'a.png';
oClientPresence.OnSession := OnPresenceSessionEvent;
oClientPresence.OnPublishMsg := OnPublishMsgEvent;
oClient.Active := True;

oClientPresence.Subscribe('room-42');
oClientPresence.Publish('hello room-42', 'room-42');
oClientPresence.GetMembers('room-42');

C++ Builder

// --- server side
oServer = new TsgcWebSocketServer(this);
oServer->Port = 80;
oServerPresence = new TsgcWSPServer_Presence(this);
oServerPresence->Server = oServer;
oServer->Active = true;

// --- client side
oClient = new TsgcWebSocketClient(this);
oClient->Host = "127.0.0.1";
oClient->Port = 80;
oClientPresence = new TsgcWSPClient_Presence(this);
oClientPresence->Client = oClient;
oClientPresence->Presence->Name = "alice";
oClientPresence->OnSession = OnPresenceSessionEvent;
oClientPresence->OnPublishMsg = OnPublishMsgEvent;
oClient->Active = true;

oClientPresence->Subscribe("room-42");
oClientPresence->Publish("hello room-42", "room-42");
oClientPresence->GetMembers("room-42");

.NET (C#)

// the .NET client prefixes the presence events with OnPresence
// and delivers members and messages as plain strings
oServer = new TsgcWebSocketServer();
oServer.Port = 80;
oServerPresence = new TsgcWSPServer_Presence();
oServerPresence.Server = oServer;
oServer.Active = true;

oClient = new TsgcWebSocketClient();
oClient.Host = "127.0.0.1";
oClient.Port = 80;
oClientPresence = new TsgcWSPClient_Presence();
oClientPresence.Client = oClient;
oClientPresence.Presence.Name = "alice";
oClientPresence.OnPresenceSession += OnPresenceSessionEvent;
oClientPresence.OnPresencePublishMsg += OnPublishMsgEvent;
oClient.Active = true;

oClientPresence.Subscribe("room-42");
oClientPresence.Publish("hello room-42", "room-42");
oClientPresence.GetMembers("room-42");

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 · Who is in the room

OnNewMember and OnRemoveMember report members joining and leaving the server, OnNewChannelMember and OnRemoveChannelMember do the same for one channel. GetMembers asks for the current roster and the answer arrives on OnGetMembers, carrying a TsgcWSPresenceMemberList you can walk.

procedure TForm1.OnNewChannelMemberEvent(Connection: TsgcWSConnection;
  const aChannel: TsgcWSPresenceChannel;
  const aMember: TsgcWSPresenceMember);
begin
  DoLog(aMember.Name + ' joined ' + aChannel.Name);
end;

procedure TForm1.OnGetMembersEvent(Connection: TsgcWSConnection;
  const aMembers: TsgcWSPresenceMemberList;
  const aChannel: TsgcWSPresenceChannel);
var
  i: Integer;
begin
  for i := 0 to aMembers.Count - 1 do
    DoLog(aMembers.Member[i].Name);
end;

oClientPresence.OnNewChannelMember := OnNewChannelMemberEvent;
oClientPresence.OnGetMembers := OnGetMembersEvent;
oClientPresence.GetMembers('room-42');

void __fastcall TForm1::OnNewChannelMemberEvent(TsgcWSConnection *Connection,
  TsgcWSPresenceChannel *aChannel, TsgcWSPresenceMember *aMember)
{
  DoLog(aMember->Name + " joined " + aChannel->Name);
}

oClientPresence->OnNewChannelMember = OnNewChannelMemberEvent;
oClientPresence->OnGetMembers = OnGetMembersEvent;
oClientPresence->GetMembers("room-42");

void OnNewChannelMemberEvent(TsgcWSConnection Connection,
  string Channel, string Member)
{
  DoLog(Member + " joined " + Channel);
}

void OnGetMembersEvent(TsgcWSConnection Connection, string Channel,
  string Members)
{
  DoLog(Channel + ": " + Members);
}

oClientPresence.OnPresenceNewChannelMember += OnNewChannelMemberEvent;
oClientPresence.OnPresenceGetMembers += OnGetMembersEvent;
oClientPresence.GetMembers("room-42");

2 · Channel messages and invitations

Publish sends a message to a channel, and every subscriber receives it on OnPublishMsg with the message, the channel and the sending member. Invite asks a specific member to join a channel, the invited client sees OnChannelInvitation and answers by setting the Accept var parameter, then the inviter is told the outcome on OnChannelInvitationResponse.

procedure TForm1.OnPublishMsgEvent(Connection: TsgcWSConnection;
  const aMsg: TsgcWSPresenceMsg;
  const aChannel: TsgcWSPresenceChannel;
  const aMember: TsgcWSPresenceMember);
begin
  DoLog(aChannel.Name + ' / ' + aMember.Name + ': ' + aMsg.Text);
end;

procedure TForm1.OnChannelInvitationEvent(Connection: TsgcWSConnection;
  const aMember: TsgcWSPresenceMember;
  const aChannel: TsgcWSPresenceChannel; var Accept: Boolean;
  var aErrorCode: Integer; var aErrorText: string);
begin
  Accept := aChannel.Name <> 'private';
  if not Accept then
  begin
    aErrorCode := 403;
    aErrorText := 'invitation refused';
  end;
end;

oClientPresence.Publish('hello room-42', 'room-42');
oClientPresence.Invite('room-42', 'bob');

void __fastcall TForm1::OnPublishMsgEvent(TsgcWSConnection *Connection,
  TsgcWSPresenceMsg *aMsg, TsgcWSPresenceChannel *aChannel,
  TsgcWSPresenceMember *aMember)
{
  DoLog(aChannel->Name + " / " + aMember->Name + ": " + aMsg->Text);
}

oClientPresence->Publish("hello room-42", "room-42");
oClientPresence->Invite("room-42", "bob");

void OnPublishMsgEvent(TsgcWSConnection Connection, string Channel,
  string Message)
{
  DoLog(Channel + ": " + Message);
}

void OnChannelInvitationEvent(TsgcWSConnection Connection,
  string Channel, string From)
{
  DoLog(From + " invited you to " + Channel);
}

oClientPresence.OnPresencePublishMsg += OnPublishMsgEvent;
oClientPresence.OnPresenceChannelInvitation += OnChannelInvitationEvent;
oClientPresence.Publish("hello room-42", "room-42");
oClientPresence.Invite("room-42", "bob");

3 · Acknowledged delivery and Base64 payloads

Acknowledgment.Enabled asks the peer to confirm every presence message, with Interval and Timeout driving the retry cadence. EncodeBase64 wraps the payload so binary or multi-line text survives the JSON envelope untouched. On the server side Broadcast pushes a message to every member, optionally narrowed to one channel.

oClientPresence.Acknowledgment.Enabled := True;
oClientPresence.Acknowledgment.Interval := 1000;
oClientPresence.Acknowledgment.Timeout := 30000;
oClientPresence.EncodeBase64 := True;

// server-side push
oServerPresence.EncodeBase64 := True;
oServerPresence.Broadcast('server restarting');
oServerPresence.Broadcast('room closing', 'room-42');

oClientPresence->Acknowledgment->Enabled = true;
oClientPresence->Acknowledgment->Interval = 1000;
oClientPresence->Acknowledgment->Timeout = 30000;
oClientPresence->EncodeBase64 = true;

oServerPresence->EncodeBase64 = true;
oServerPresence->Broadcast("server restarting");
oServerPresence->Broadcast("room closing", "room-42");

oClientPresence.Acknowledgment.Enabled = true;
oClientPresence.Acknowledgment.Interval = 1000;
oClientPresence.Acknowledgment.Timeout = 30000;

oServerPresence.Broadcast("server restarting");
oServerPresence.Broadcast("room closing", "room-42");

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.