What is Salaam? - Sojaner/Salaam GitHub Wiki

What is Salaam?

Salaam is a cross-platform library written in C# and available for Windows versions who can serve .Net Framework 2.0 or upper, Mac OS X, Linux, iOS, Android, XNA, Solaris and many operating systems that Mono and .Net can work with.

In a simple word, it is very similar to Bonjour; but if it is similar to Bonjour, why use this library? we were working on a cross-platform network application and we tried to use Bonjour to find the peers on the network using Mono.ZeroConf but there were some problems like the bonjour service must be installed on the OS before using the application and it will make the application dependence on Bonjour service and the library files are different in each OS. So we decided to make a library to make it even easier. The complete illustration is given following text.

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.

In Salaam we used UdpClient to broadcast because however Udp is an unsecure, connectionless and unsafe protocol, it is more useful rather that other protocols like Tcp.

How to use Salaam in my application?

In the following text, you can learn how to use this very simple library in your application. Further to this text documentation you can watch the video tutorial or download the sample code to understand it better.

All the Salaam classes are in the Dolphins.Salaam namespace.

The first step is to setup the SalaamService on your server application. the following code demonstrates. (Suppose My Application is a server of a chat application which uses Tcp.

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

service.Register();

According to the below code, you are telling your clients that the server application named My Application on the port 2000 is listening for incoming connections. but what is the first argument (Service Type)? just like the Bonjour, in order to identify the accurate server application and to make sure whether this application is the exactly one that you are looking for, you need to set this string value. The universal standard format of this string is _yourApplicationName._protocol so in this documentation we used _myApp._tcp.

The constructor's chart:

The code below is the simplest and quickest way to reach the goal, but Salaam is not limited to this 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 goal, else ignore the paragraph and move to the Salaam browser section.

The fact is that the 2 line code is the required code to use SalaamService, the rest of properties, methods and events are just optional but recommended (e.g. using events are very useful).

SalaamBrowser:

Now it's time to walk through the Salaam browsers. the class of the Salaam browser is SalaamBrowser.

Just like the SalaamService explanation, I will show you the simplest and quickest way to setup the SalaamBrowser and then I give you more advanced documents.

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

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 can I be informed when a peer appeared or disappeared? You have 2 choices, you can use browser.SalaamClients to get the list of found peers or to handle the ClientAppeared and ClientDisappeared to reach the goal. The following charts demonstrates better.

In the above charts, you may seen an unknown type-SalaamClient. This is a type used to store a Salaam client’s data including HostName, Address, Name of the server application, Service Type, Port which server application is listening on and finally the message of client-which you set this custom message in SalaamService.

SalaamClient:

There is nothing important to say about this type, because there is no specific method or event for this type. The fact is that this is a read-only class used to get information concerning an appeared client. So the following chart is enough to understand it.

We explained all the types and classes, but there is one other informative point here; in SalaamClientEventArgs-which you get 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.

Now you are prepared to work with this library. You can use it on almost all of .Net Framework 2 applications and Mono applications.