1. 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. OZEKI VoIP SIP SDK 01/22

2. What you need Windows PC.NET compatible development kit installed on your PC.NET Framework installed on your PC Ozeki VoIP SIP SDK installed on your PC 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.

3. 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

4. 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 Part 1: Softphone implementation and SIP registration |04/22

5. 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; Part 1: Softphone implementation and SIP registration |05/22

6. 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: Part 1: Softphone implementation and SIP registration |06/22

7. 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, authenticationId, registerPassword, domainHost, domainPort); Part 1: Softphone implementation and SIP registration |07/22

8. 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; Part 1: Softphone implementation and SIP registration |08/22

9. 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); Part 1: Softphone implementation and SIP registration |09/22

10. 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 Part 1: Softphone implementation and SIP registration |10/22

11. 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; Part 1: Softphone implementation and SIP registration |11/22

12. 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. Part 1: Softphone implementation and SIP registration |12/22

13. 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(); Part 1: Softphone implementation and SIP registration |13/22

14. 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 Part 1: Softphone implementation and SIP registration |14/22

15. 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

16. 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 Part 2: Implementing the IM functionality |16/22

17. 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); } Part 2: Implementing the IM functionality |17/22

18. 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; Part 2: Implementing the IM functionality |18/22

19. 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; Part 2: Implementing the IM functionality |19/22 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;

20. 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); Part 2: Implementing the IM functionality |20/22

21. 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); Part 2: Implementing the IM functionality |21/22

22. 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 info@voip-sip-sdk.com OZEKI VoIP SIP SDK 22/22