Using the Silverlight Classic API
The DiffusionClient class is the main class that is used. This class enables the user to set all of the connection and topic information.
Instantiation and connection example
theClient = new DiffusionClient( Dispatcher ); // Instantiate the server details object and the initial topic to subscribe to ServerDetails details = new ServerDetails( "http://localhost:8080", "SpotOnly" ); // Add the server details to the client theClient.AddServerDetails( details ); // Add the event listeners theClient.ConnectionStatus += DiffusionConnectionStatus; theClient.MessageReceived += theClient_MessageReceived; // Now connect theClient.Connect();
Setting credentials
If credentials are required by the Diffusion™ server then use the Credentials property on the DiffusionClient class. The DiffusionClientCredentials class takes a constructor argument of userName and password. Please bear in mind that these are only tokens and can contain any information that the AuthorisationHandler requires. However, if you set the username as an empty string (that is, an anonymous user) the password is not stored and you cannot retrieve it with getCredentials.
theClient.Credentials = new DiffusionClientCredentials( "username", "password" );
Rejection of credentials event
If the credentials are rejected by the Diffusion server, a ServerRejectedCredentials event is fired. This can be subscribed to by using the following code:
theClient.ServerRejectedCredentials += ServerRejectedCredentials;
Message not acknowledged event
When a message is created with the "acknowledge" flag, this event is fired when a message is not acknowledged by the Diffusion server within the specified time period. This can be subscribed to by using the following code:
theClient.MessageNotAcknowledged += MessageNotAcknowledged;
The ConnectionStatus event
The ConnectionStatus event contains information about whether the connection was successful. Here follows an example of the usage of this event.
/// <summary> /// Called when the connection state to Diffusion changes. /// </summary> /// <param name="sender"></param> /// <param name="e"></param> void DiffusionConnectionStatus( object sender, DiffusionConnectionStatusEventArgs e ) { switch( e.StatusType ) { case DiffusionConnectionStatusType.ConnectionFailed: { Dispatcher.BeginInvoke( () => MessageBox.Show( "Unable to connect to Diffusion. Diffusion reports: " + e.ExtraData, "Connection failed", MessageBoxButton.OK ) ); } break; case DiffusionConnectionStatusType.ConnectionReset: { Dispatcher.BeginInvoke( () => MessageBox.Show( "The connection to Diffusion has been reset. Diffusion reports: " + e.ExtraData, "Connection failed", MessageBoxButton.OK ) ); } break; } }
The MessageReceived event
When messages arrive from the Diffusion server on a subscribed topic, the MessageReceived event is fired. This event contains a sender and a TopicMessageEventArgs object which itself contains a TopicMessage object which can be interrogated to discover the contents of the received message.
The TopicStatusMessageReceived event
When the status of a topic changes on the Diffusion server, the TopicStatusMessageReceived event is fired. This event contains a sender and a TopicStatusMessageEventArgs object which contains the alias of the topic on which the status has changed. Currently, only the notification of the removal of a topic is implemented.
Subscriptions
After the client has connected, you can issue Subscribe and Unsubscribe commands. These commands take string arguments which can be a topic selection pattern, a list of topics that are comma-delimited, or a single topic.
Sending non-encoded topic messages
Once the client has connected, it can send messages to the Diffusion server on a particular topic. To do this, use either the Send or SendTopicMessage methods on the DiffusionClient object, as shown in the following code:
theClient.Send( "Fred", "Hello, publisher that looks after Fred" ); TopicMessage message = new TopicMessage( "Fred", "Hello, publisher that looks after Fred" ); theClient.SendTopicMessage( message );
In the above examples, the publisher that looks after the topic Fred receives a messageFromClient notification internally.
Sending an encrypted topic message
Sending an encrypted topic message is achieved by calling the SendTopicMessageEncrypted method on the DiffusionClient object by using the following code:
theClient.SendTopicMessageEncrypted( new TopicMessage( "Fred", "Hello, publisher that looks after Fred" ) );
This sets the relevant encoding flags on the message itself, and the message will be encrypted immediately prior to sending to the Diffusion server.
Sending a compressed topic message
Sending a compressed topic message is achieved by calling the SendTopicMessageCompressed method on the DiffusionClient object by using the following code:
theClient.SendTopicMessageCompressed( new TopicMessage( "Fred", "Hello, publisher that looks after Fred" ) );
This sets the relevant encoding flags on the message itself, and the message will be compressed immediately prior to sending to the Diffusion server.
Sending a Base64-encoded topic message
Sending a Base64-encoded topic message is achieved by calling the SendTopicMessageBase64 method on the DiffusionClient object to using the following code:
theClient.SendTopicMessageBase64( new TopicMessage( "Fred", "Hello, publisher that looks after Fred" ) );
This sets the relevant encoding flags on the message itself, and the message will be Base64-encoded immediately prior to sending to the Diffusion server.
Ping
A client can ping the Diffusion server. To process the ping response, the user monitors the MessageReceived event and checks for a message type of PingServer, as shown in the following code:
private void HandleServerPingMessage( TopicMessageEventArgs e ) { var message = e.Message as PingMessage; if( message != null ) { tbElapsedTime.Text = message.ElapsedTime.ToString(); tbQueueSize.Text = message.QueueSize.ToString(); } }
Fetch
Using the fetch method, a client can send a request to the Diffusion server for the current state of a topic, which returns a state message to the client. A client can do this even if not subscribed to the topic.
Topic listeners
During the lifetime of the connection, it might be required to have modular components that get notified about topic messages – these are known as topic listeners. A topic listener calls a supplied function with a TopicMessage object when the topic of the message matches the pattern supplied. It is also worth noting that the OnMessageReceived event is called as well as the topic listener event itself.
You can have many topic listeners on the same topic pattern if required. For example, if you want to be notified about a particular topic, use the following code:
instrumentListener = theClient.AddTopicListener( "^SpotOnly$", ProcessInstruments, this );
Enabling JavaScript® method invoking
To call JavaScript functions (and they are permitted to do so by the Silverlight® runtime), use the following method call:
theClient.InitialiseJavaScriptMethodInvoking( HtmlPage.Window );
Listening to internal transport debug messages
theClient.DiffusionTraceEvent += theClient_DiffusionTraceEvent;
This enables the user to monitor all internal debug messages within the Silverlight API.