How to develop a softphone in C# that enables SIP Instant Messaging (IM)

How to develop a

VoIP softphone in C# that enables SIP Instant Messaging (IM)

This presentation describes how to create a softphone in C# that

allows you to send and receive SIP Instant Messages (IM) in order to

be able to real-time chat communication - by using the background

support of Ozeki VoIP SIP SDK.

01/22

What you need

Windows PC .NET compatible

development kit

installed on your PC

.NET Framework


Ozeki VoIP SIP SDK


to build a VoIP softphone in C#

Download free example source code for this project from http://www.voip-sip-sdk.com/index.php?owpn=540 !

02/22

Table of contents Part 1: Softphone implementation and SIP registration |

p3 Part 2: Implementing the IM functionality | p15

p3

If you have an existing softphone, skip ‘Part 1’ and go to page 15.

http://www.voip-sip-sdk.com/index.php?owpn=540





Create a new Microsoft Visual Studio project and add VoIP components to your references

1. Open Visual Studio and create a new project

by clicking on File then New project

2. As this softphone will be a simple console application,

in the next window you need to select the Visual C# Console Application option

3. After you have specified a name for your new project,

click on the OK button

4. To achieve and use the VoIP components of the SDK, add them to your references

For this, you need to right-click on References than select the Add references option. After

this, browse the SDK.dll file that can be found where the SDK has been installed to. Select the

.dll and click on the OK button

Having done these steps, you can find a new line at the end of the References folder: ‘VoIPSDK’.

This line indicates that now you can use the tools provided by the SDK.

Part 1: Softphone implementation and SIP registration | 03/22

For separating the softphone from the user interface, two classes are used:

1. Softphone.cs: The implementation of the softphone goes here

(including its events, methods, functions, variables)

This class is used to introduce how to declare, define and initialize a softphone, how to

handle some of the Ozeki VoIP SIP SDK's events and how to use some features. So the aim

is creating a ‘telephone software’, which has the same functionalities (or much more), as an

ordinary phone’s .

2. Program.cs:

The class with the Main() method

(this class controls the console window, interacts with the user by using a softphone object)

You will use the Program.cs class to create a new softphone, so you can use the functions

and listen to the events placed here.

Write the code Classes


In the ‘using section’ you need to add some extra lines, as well as:

Without these lines you would have to use

the namespace information as a label for all tools of the SDK.

Write the code Source code analysis

using Ozeki.Network.Nat; using Ozeki.VoIP; using Ozeki.VoIP.SDK;


In a constructor, you also need to initialize this softphone with default parameters:

You need to set the port range, indicated by the first two parameters as the minimum port's and

the maximum port's number. This is the port's interval. The third parameter is the listening port.

If you have any firewall rule that restricts the usable ports, you can set the usable port range

here, which will be used during the calls. These are sample ports only in the example, but a

softphone with these parameters can be used in the most of the cases. (If you are handling

conference calls or handling a lot of lines simultaneously, you will need a wide port range.)

Write the code Softphone.cs

ISoftPhone softphone; // softphone object IPhoneLine phoneLine; // phoneline object

softphone = SoftPhoneFactory.CreateSoftPhone(5000, 10000, 5060);

Create a softphone and a phone line object from the ISoftPhone and the IPhoneLine

interfaces:


In order to create the SIP account, set the followings:

• RegistrationRequired: Is the registration required or not? This field needs to be set to ‘true’, if

you would like to receive incoming calls

• DisplayName: A name to be displayed at the called client.

• UserName: If an other client dials this name (number), the SIP account will be getting called

• AuthenticationId: An identifier to the PBX, like a login name

• RegisterPassword: The password that registers to the PBX. It works in pair with the

authentication ID

• DomainHost: For example a domain name, an IP address

• DomainPort: Port number

The last two values define the PBX address where the softphone will be registered.

You will get the values of these parameters from the user, in the Program.cs file.

Write the code Registration to the PBX

var account = SIPAccount(registrationRequired, displayName, userName, <br> authenticationId, registerPassword, domainHost, domainPort);


If you want to communicate through firewall, you need to set the right NAT Traversal

method:

In this example, it has been set to ‘None’. This is enough for communication on local network.

An other option for the NAT Traversal method is setting it to ‘STUN’. This way, you can define

the Stun server with a NatRemoteServer object by giving the server IP, the username and

password to use as parameters:

You can set automated detection on that IP address you would like to use. If you set the

configuration to ‘None’, but you also set a NatRemoteServer object with the public IP, you will

use the local address on the local network and the public on others:

Write the code NAT (Network Address Translation) Traversal

var natConfiguration = NatConfiguration(NatTraversalMethod.None);

natConfiguration.StunServer = new NatRemoteServer(serverIP, username, password);

natConfiguration.AutoDetect = true;


In order to communicate (and to register to the PBX) you need to create a phone line by

using the previously created SIP account and the NAT Traversal setup:

When the application is running, the state of the phone line can change. To follow these

changes, you need to listen to this change event:

When the phone line has been created, you have to call the RegisterPhoneLine()

method to register the phone line to the softphone. If the registration is set to required,

this method will also send the SIP REGISTER command. You only need to use the

following line:

Write the code PhoneLine

phoneLine = softphone.CreatePhoneLine(account, natConfiguration)

phoneLine.PhoneLineStateChanged += phoneLine_PhoneLineStateChanged;

softphone.RegisterPhoneLine(phoneLine);


The phone line event can be in several states, for example:

• RegistrationFailed: occurs, when registration is needed, but it failed. The phone is

unable to communicate through the PBX

• NoRegNeeded: there is no communication with the server, until the first (made) call.

If you have set any invalid information during the SIP account creation, you can not

even make calls. Since your softphone is not registered to the server, you can not

receive any calls, even with valid SIP account

• RegistrationSucceeded: occurs, when registration is needed, and succeeded. The

phone is able to receive and make calls

• RegistrationTimedOut: some PBXs define for how long a client can be registered

to it. If that time is up, the state of the phone line changes to this

Write the code Events


This class will introduce the usage of a softphone object, it handles the console events,

interacts with the user and uses the opportunities provided by the Softphone class. In

this example, the softphone can only register to a PBX by the values given by the user.

First of all, you need to create a softphone object.

You can handle everything with separated methods. These methods are communicating

with each other, and making the source code more understandable and reusable.

Write the code Program.cs

static Softphone mySoftphone;


In order to initialize your softphone, you need to call an initializer method with the

following lines:

Call this method in the Main() method. Now, there is a new softphone available to use,

and it is already following the states of the phone. You will see how to handle the states

below, after you have done with the greeting and the registration process.

Write the code Initialization

mySoftphone = new Softphone(); mySoftphone.PhoneLineStateChanged += mySoftphone_PhoneLineStateChanged;

Showing a greeting message

In a few lines you can introduce the application to the user. It is preferred to say a few

sentences about the features available. After your softphone has been initialized, call this

method to introduce the application in the Main() method.


As you could see at the Softphone class, you need a configured SIP account in order

to use the softphone for communication. The user needs to enter valid values to create

a SIP account and to register to a PBX. This procedure can be done using such simple

commands as:

Write the code Creating the SIP account by the user's input and registering to a PBX

Console.WriteLine(); Console.ReadLine();


You are subscribed to get notified if the state of the phone line has been changed. At the

mySoftphone_PhoneLineStateChanged method you can set what happens in case of each state. If

the registration is failed, the SIP account details should be provided again. States for this case:

or

The "RegistrationFailed" state occurs, when the registration is simply unsuccessful, for example, if

the user set up invalid SIP account during the registration. The "RegistrationTimedOut" state occurs,

if the registration request takes too long.

If the registration has succeeded or there is no need for registration, you can notify the user

about that. Note, if there is no need for registration, but you could not reach the PBX (or you could,

but with invalid SIP account), you will not notice that until you make your first call. The states to use:

Write the code Handling of the phone line states

PhoneLineState.RegistrationTimedOut

PhoneLineState.RegistrationFailed

PhoneLineState.RegistrationSucceeded PhoneLineState.NoRegNeeded


Instant messaging (IM) is a type of online chat that enables real-time

direct text-based chatting communication among users using

computers or mobile devices. In push mode between two or more

people using personal computers or other devices,

along with shared Instant Messaging software clients.

The user's text is conveyed over a network, such as

the Internet. More advanced Instant Messaging

software clients allow enhanced modes of

communication, such as live voice or video

calling and inclusion of links to media, as well.

What is Instant Messaging (IM)

Part 2: Implementing the IM functionality | 15/22

The Softphone class needs only two objects (ISoftPhone, IPhoneLine) and one variable:

There are two ways to send Instant Messages to an other party:

1. through the IPhoneLine object, with the SendOutofDialogInstantMessage()

method of the object. In this case, you do not need to establish a call with the

other party. (This example presents this way.)

2. through the IPhoneCall object, with the SendInstantMessage() method. In this

case, you have to establish a call before you try to send an Instant Message.

For Instant Messaging you do not need any MediaHandler objects (that is needed in case of an audio call), as

messages will be sent without establishing a call.

Write the code Softphone.cs – Objects and variables

private ISoftPhone softphone; // softphone object private IPhoneLine phoneLine; // phoneline object public string recipient; // the recipient's number as string


For sending an Instant Message, you need to set the parameters of the IPhoneLine

object (phoneLine) by using the followings:

• recipient: the destination number of the Instant Message, as String

• message: the message to be sent

This method will receive the value of the message string from the user, and will send the

given message to the recipient, defined by the recipient variable.

Write the code Softphone.cs – Sending Instant Messages

public void SendMessage(string message) { phoneLine.SendOutofDialogInstantMessage(recipient, message); }


For receiving Instant Messages through the phoneLine object, the application needs to

be subscribed to the OutofDialogInstantMessageReceived event of the phoneLine:

The phoneLine_OutofDialogInstantMessageReceived method notifies the application if

there is an incoming IM through an event, called IncomingMessage.

Write the code Softphone.cs – Receiving Instant Messages

phoneLine.OutofDialogInstantMessageReceived += phoneLine_OutofDialogInstantMessageReceived;


Everything is handled with separated methods that communicates with each other.

New variable: messageToSend, to store the message which is being sent, as String:

Write the code Program.cs – Objects and variables

static string messageToSend;


For initializing, you need to call an initializer method. You also need to subscribe to the

events of the softphone. Add the following lines to subscribe to the IncomingMessage

event of the Softphone class and is set the declared variable to be empty.

Program.cs – Initializing the softphone

mySoftphone.IncomingMessage += mySoftphone_IncomingMessage; messageToSend = String.Empty;

The application uses a method ( GetRecipient() ) for asking the user about the

recipient's number, and to store that in the previously declared recipient variable of the

Softphone object (mySoftphone). This method is being called when the registration was

successful (or no registration was needed).

Program.cs – Getting the message from the user to be sent

There is a method (MessageToSend) that asks the user for messages to be sent, and

sends them to the recipient, until the user closes the application. This method uses the

SendMessage() method of the mySoftphone object:

The MessageToSend() method is being called after the setting of the recipient's number.

Write the code Program.cs – Getting the phone number of the recipient

mySoftphone.SendMessage(messageToSend);


For receiving an Instant Message, the softphone is already subscribed to the necessary

event that calls the mySoftphone_IncomingMessage() method that displays the

originator of the received message and the message itself:

Write the code Program.cs – Receiving incoming Instant Messages

Console.WriteLine("\nMessage received from {0}: {1}", e.Item.Originator, e.Item.Data);


After studying this guide, you need to be familiar with creating a softphone

application that can be used to send and receive Instant Messages (IM) without

making any audio or video calls. It enables the users to do real-time direct text-

based chatting communication.

Thank you for your attention!

For more information please visit

www.voip-sip-sdk.com

or send an e-mail to

[email protected]

22/22

Software

How to develop a softphone in C# that enables SIP Instant Messaging (IM)