This project is read-only.

What is Salaam?

Salaam is a cross-platform library written in C# and available for Windows versions which could serve .Net Framework 2.0 and upper, Mac OS X, Linux, iOS, Android, Solaris and many other Mono and .Net compatible operating systems and engines including MonoGame, Box2D, XNA and Unity3D and many more.

In a simple word, it is very similar to Apple's Bonjour; but if it is similar to Apple's Bonjour, why someone should use this library? we were working on a cross-platform network application and we tried to use Apple's Bonjour to locate the peers on the network using Mono.ZeroConf from Mono project, but there were some problems using this library including that the bonjour service must have been installed on the OS before using the application and besides that the Mono.ZeroConf may not be working on all versions of all Operating Systems (In our case, some new versions of linux). So we decided to create Salaam (Like 'Bonjour' that means 'Hello' in French, 'Salaam' means 'Hello' too in Persian) library to solve these problems. The complete illustrations of library are present below.

If you have a server application and one or two client application and you want clients to find the server or vice versa, a great choice for you is Salaam because you can use Salaam as a interface to connect peers easily. You just need to make a instance of SalaamService and set your application's details like the port you use in the server application and its name, and then register the Salaam service to start network broadcasting. Beside of this, Salaam browsers can see the registered Salaam services, so you need to setup a Salaam browser on the client side of your application. Then you find the address and port of the server application in your client application and now it is easy to connect using any internet protocol or socket options to connect to your server application.

Salaam uses UdpClient class to broadcast the service over Udp protocol. This protocol gives access to the possibilities which Tcp doesn't, like connectionless packets transfer.

 

 

How to use Salaam?

In the following code sample, it is illustrated how to use this very simple library in your application. There are also sample codes available for download in download section provided for better understanding of code usage.

All the Salaam classes are located inside the Dolphins.Salaam namespace.

SalaamService:

The first step, is to setup the SalaamService on your server application. the following code demonstrates this step. (Suppose our Application is a LAN chat application which uses Tcp)

 

SalaamService service = new SalaamService("_myApp._tcp", "My Application", 2000);

service.Register();

 

According to the recent code, we are announcing to the clients on the LAN that the application named My Application is listening for incoming connections on port 2000 (This is the port that the chat application is listening on, not the port, Salaam uses to broadcast on. This it a very important matter that we have to keep in mind). That's clear but what is the first argument 'Service Type'? Just like the Apple's Bonjour, this string is being used to identify different Applications on the network which are using Salaam to broadcast their services. Everyone of these applications, has its own communication protocol and uses this 'Service Type' as an identification to its service, so other clients which use the same communication protocol (say for example HTTP) can easily identify this application and connect it using the provided port.

An standard format that Apple uses in Bonjour for 'Service Type' is _yourApplicationProtocol._networkProtocol so in this case we used _myApp._tcp (An HTTP server may use _http._tcp like the way HTTP Server that use Bonjour do).

The constructor's chart:

SalaamService Constructor Chart

The recent code is the simplest and quickest way to reach the goal of registering a service using Salaam, but Salaam is not limited to these 2 lines of code, if you want more options including events and methods look at the following charts to understand the events, methods and properties of SalaamService for your more advanced usage.

 

SalaamService Structure

SalaamService Events

In fact these 2 line of code are the required code to use SalaamService, but there are more options including other methods, properties and events useful in advanced usage.

 

SalaamBrowser:

Just like the SalaamService , we will start by the simplest and quickest way to setup the SalaamBrowser and then we will read more advanced documentations.

As in the first step, we have setup the SalaamService, the second step is to setup the SalaamBrowser. The following code demonstrates the simplest code we can use.

 

SalaamBrowser browser = new SalaamBrowser();

browser.Start("_myApp._tcp");

 

As you can see, it is very simple to setup and start the Salaam browser but how to figure out when a peer appears on the network or even when is disappears? There are two options to access the peers' instances in the form of a SalaamClient, we can use browser.SalaamClients to get the list of all found SalaamClient peers or to handle the ClientAppeared and ClientDisappeared to be notified whenever a peer appears or disappears. The following charts demonstrates these concepts.

SalaamBrowser Structure

SalaamBrowser Events

In the above charts, as we can see, the SalaamClient objects are being used to store Salaam clients' information including HostName, Address, Name of the server application, Service Type, the Port at which the server application is listening on and finally a Message from the peer which may be set in SalaamService setup process.

 

SalaamClient:

This is a read-only class used to get information concerning a peer's information. The following chart illustrates the SalaamClient class.

SalaamClient Structure

SalaamClientEventArgs:

SalaamClientEventArgs class is used as a means of event argument in many events, further to getting instance of SalaamClient, you can determine whether this appeared client is from the local machine or not. This class is used in events where we need to get information about the client that raised the event.

 

Salaam library works on almost all, .Net Framework 2 and Mono compatible applications. This library is a lightweight easy to use and only uses the System namespace of the .Net or Mono.

Last edited Aug 29, 2012 at 1:11 AM by pkdeveloper2012, version 6

Comments

No comments yet.