Publish and Subscribe - xylamic/lightrail-pubsub-integration-framework GitHub Wiki

Publish

To be able to publish a message, a Terminal with a "Publisher" standpoint must be registered as seen in the previous explanation.

Once a Terminal is registered, a message can then be sent from it. A delivery contains a message to be sent. A delivery can be created from a string for sending text or a binary array for a binary message. In the case of a binary message, an optional encoding can be specified in the case that it’s actually textual data.

Example C++

IDelivery* message = Lightrail::NewDelivery();
message->SetMessageString(L"This is a string message that will be encoded as UTF-8");

Example C#

Delivery message = new Delivery("This is a string message that will be encoded as UTF-8");

When a message is created and ready for publishing, the message is sent through the registered Terminal.

Example C++

client->Publish(L"PubTerminal", message);

Example C#

client.Publish("PubTerminal", message);

Once sent, any subscribers with Terminals and strings that match your publication will receive the message.

Subscribe

To be able to subscribe to a publication, an event handler must be set up and a Subscriber Terminal must be registered. When deliveries are started, all messages that match your Terminal string will then be received.

Example C++

// set up the callback using your class instance
client->OnPublicationReceived.SetCallback(new XEventCallback<YourClassName, ITerminalDelivery&>(
     this, &YourClassName::PublicationReceived));

// set up the method for receipt
void PublicationReceived(ITerminalDelivery& delivery)
{
     std::wstring msg = delivery.DetailedDelivery()->MessageString();
}

Example C#

// set up the callback
client.OnPublishReceived += new PublishReceived(client_OnPublishReceived);

// set up the method for receipt
void client_OnPublishReceived(DetailedDelivery delivery)
{
    string message = delivery.MessageString();
}

When a message is received, a message can be extracted as a string or binary array with encoding. If a string is extracted, Lightrail will try to decode with an included specified encoding (ie: if the message was encoded as UTF-8, it will be parsed as UTF-8; if the message was encoded as UTF-16 (Unicode), then it will be parsed as UTF-16).

If you are subscribed via multiple Terminals, then the receipt Terminal property which gives the Terminal name can be used to differentiate which Terminal received the delivery.

For any given Lightrail instance, messages are received synchronously and guaranteed to be in order.