abto softwareâ€™s voip sip sdk

DEVELOPER MANUAL

v. 2

02.04.2013

ABTO Software’s VoIP SIP SDK

© 2013 ABTO Software® VoIP SIP SDK

® www.voipsipsdk.com Skype: sales.abto.software 2 [email protected] Tel: 1-773-800-2875

Table of Contents

QUICK START ......................................................................................................................................................... 3

GETTING STARTED ........................................................................................................................................... 3 HOW TO ADD VOIP SIP SDK TO THE APPLICATION AND MAKE CALLS ................................................................... 4

Tutorial for VB 6 ................................................................................................................................ 4 Tutorial for Delphi .............................................................................................................................. 6 Tutorial for Visual Studio (C#) ........................................................................................................... 7 Tutorial for VS 2005 (C++) .............................................................................................................. 10

HOW TO HANDLE ABTO SDK EVENTS IN DIFFERENT LANGUAGES...................................................................... 13 Tutorial for Visual Basic 2005 ......................................................................................................... 13 Tutorial for Visual Basic 6................................................................................................................ 15 Tutorial for Visual C++ 2005............................................................................................................ 16 Tutorial for JavaScript ..................................................................................................................... 19 Tutorial for Delphi 7 ......................................................................................................................... 22 Tutorial for Visual C# 2005 .............................................................................................................. 25

ABTOPHONE NAMESPACE ................................................................................................................................. 28

_IABTOPHONEEVENTS INTERFACE .................................................................................................................. 28 Events 28

IABTOPHONE INTERFACE ................................................................................................................................ 34 Methods 34 Properties: ....................................................................................................................................... 44

ICONFIG INTERFACE ....................................................................................................................................... 46 Methods 46 Properties ........................................................................................................................................ 47

FAQ. PROBLEMS AND SOLUTIONS.................................................................................................................... 60

REGISTRATION DOESN'T WORK ........................................................................................................................ 60 ARE THERE ANY FAX DETECTION OPTIONS? ..................................................................................................... 60 SHUTTING DOWN ............................................................................................................................................ 60 HOW TO USE CODECS? ................................................................................................................................... 60 HOW TO TURN OFF ONE CONNECTION? ............................................................................................................ 61 HOW TO GET THE CURRENT AUDIO LEVEL ON MICROPHONE/SPEAKER? .............................................................. 61 HOW TO GET/SET THE CURRENT VOLUME LEVEL? ............................................................................................. 62 IS THERE A CERTAIN ORDER THAT THINGS NEED TO BE DONE? ........................................................................... 62 HOW TO RELOAD NEW VERSION OF DLL? .......................................................................................................... 62 HOW TO DISTINQUISH SEVERAL CALLS THROUGH ONE APPLICATION? ................................................................. 63 DOES SIP SDK SUPPORT MULTI INSTANCES IN ONE COMPUTER? ...................................................................... 63 WHERE CAN I READ THE SIP RESPONSE OF A FAILED CALL? .............................................................................. 63 HOW TO USE "ISLINEOCCUPIED" METHOD? ...................................................................................................... 63 HOW TO AVOID "503 NO DNS RESULTS" MESSAGE? ........................................................................................ 64 HOW TO GET CALLERID ON INCOMING CALL? ................................................................................................... 64 WHAT IS "EXPIRETIME" SETTING? ................................................................................................................... 64 CAN SDK WRITE LOG FILE?............................................................................................................................. 65 C# EXAMPLE DOESN'T WORK ON WIN7 X64 ...................................................................................................... 65 HOW TO COPY SDK ON ANOTHER COMPUTER? ................................................................................................ 66 WHAT IS THE CONFIG FILE PHONECFG.INI? ....................................................................................................... 66 HOW TO EXCLUDE PHONECFG.INI? .................................................................................................................. 67




QUICK START

Getting Started

ABTO Software VoIP SIP SDK is designed for developing a soft-phone with custom business logic. Typical scenario

1. Decide which programming language would you like to use for develop soft-phone. 2. Select and make copy of existing example from SDK setup folder. 3. Review and modify copied project.

Using SDK instance SDK supports 2 interfaces IAbtoPnone and IConfig. First one - is SIP phone interface, second - used tp configure phone. Instance life cycle

A. Create instance (use 'CreateInstance(__uuidof(CAbtoPhone)' for C++, 'new CAbtoPhoneClass' for C# and VB). B. Subscribe for events C. Configure crated phone instanse (ports, registration, license, log-level, audio devices, network interface,

codec's list, etc.) by reading them from ini file or direct set from code. D. Invoke method 'Initialize'. E. Make calls (StartCall, Answer, Hangup), handle events. F. Unsubscribe from events receiving, destroy instance.




How to add VoIP SIP SDK to the application and make calls

Prerequisites for continuing tutorial: 1. Two computers to conduct tests 2. VB6 or Delphi or VS IDE 3. ABTO Software VoIP SIP SDK installed We are going to make several simple steps to make our own SIP phone using SIP SDK.

Tutorial for VB 6

1. Open VB.6 2. Open new windows project: Standart Exe 3. At the moment you have got empty form in IDE. 4. Add reference to SIP SDK (if you cannot find SIP SDK in the list, check Troubleshooting section): Project->References Locate "ABTO SIP SDK 3.0.0.12 Type Library"

Check the box and press OK 5. Create controls as in image (name them: AddressBox, BtnCall)




6. Define AbtoPhone variable. Select in context menu "View code". Write following code: Private WithEvents AbtoPhone As CAbtoPhone 7. Add code to initialize. Private Sub Form_Load() Set AbtoPhone = New CAbtoPhone Dim Configuration As CConfig Set Configuration = AbtoPhone.Config 'Configuration.LogLevel = eLogWarning 'Configuration.LicenseUserId = "" 'Configuration.LicenseKey = "" AbtoPhone.ApplyConfig AbtoPhone.Initialize End Sub 8. Add code to start a call (Double click 'Start Call' button and add following code): Private Sub BtnCall_Click() If Len(AddressBox.Text) > 0 Then AbtoPhone.StartCall AddressBox.Text End If End Sub 9. Let’s add code to accept incoming call. Add new event: Private Sub AbtoPhone_OnIncomingCall(ByVal RemoteAddres As String, ByVal LineId As Long) If MsgBox(RemoteAddres + "Answer?", vbYesNo, "Incoming Call") = VbMsgBoxResult.vbYes Then AbtoPhone.AnswerCall Else AbtoPhone.RejectCall End If End Sub




10. Run application.

Tutorial for Delphi

1. Open Delphi 2. Open new windows project: File->New Application 3. At the moment you have got empty form in IDE. 4. Add reference to SIP SDK (if you cannot find SIP SDK in the list, check Troubleshooting section): Go to menu: Project->Import Type Library Locate "ABTO SIP SDK 3.0.0.12 Type Library"

In edit box "Unit dir name:" type full path to current project folder. Press "Create unit" Will be generated new unit "SIPVoipSDK_TLB" in file SIPVoipSDK_TLB.pas. 5. Create controls as in image (name them: AddressBox, CallButton)




6. Go to the source code, add declaration private AbtoPhone: TCAbtoPhone; 7. Add code to initialize. Using object inspector add handler procedure TForm1.FormCreate(Sender: TObject); var phoneCfg : Variant; begin AbtoPhone := SIPVoipSDK_TLB.TCAbtoPhone.Create(Self); phoneCfg := AbtoPhone.Config; {Note: Uncomment following lines if needed} //Log level //phoneCfg.LogLevel := LogLevelType.eLogDebug;//eLogError //Specify Licensy key //phoneCfg.LicenseUserId := '...'; //phoneCfg.LicenseKey := '...'; AbtoPhone.ApplyConfig;//Apply modified config try AbtoPhone.Initialize; //Initialize component except end; end; Run application.

Tutorial for Visual Studio (C#)

1. Open VS 2005 2. Create project: File->New->Project->Visual C#->Windows->Windows Application 3. Add reference to SIP SDK:




Right click on References in Solution Explorer and choose "Add reference" Goto COM Components tab Locate "ABTO SIP SDK 3.0.0.12 Type Library"

Press OK. 4. Create controls as in image

5. Go to source code. 6. Add using directive (in bottom of existing "using..." declaration) using SIPVoipSDK; 7. Declare and initialize phone instance variable: private CAbtoPhone AbtoPhone = new CAbtoPhone();




8. Add code to initialize private void SIPPhone_Load(object sender, EventArgs e) { //Get config CConfig CConfig phoneCfg = AbtoPhone.Config; //Specify Licensy key //phoneCfg.LicenseUserId = "..."; //phoneCfg.LicenseKey = "..."; //Log level //phoneCfg.LogLevel = LogLevelType.eLogDebug;//eLogError //Apply modified config AbtoPhone.ApplyConfig(); try { AbtoPhone.Initialize(); } catch(Exception exc) { MessageBox.Show(exc.Message, "Error", MessageBoxButtons.OK); } } 9. Add code to start a call. Double click Start Call button and add following code: private void CallButton_Click(object sender, EventArgs e) { if (AddressBox.Text.Length > 0) { AbtoPhone.StartCall(AddressBox.Text); } } 10. Look existing examples how to handle events and make initialization. Run application.




Tutorial for VS 2005 (C++)

1. Open VS 2005 2. Create project: File->New->Project->Visual C++->MFC->MFC Application Set name "SIPPhone" Select Application type: as 'Dialog box' 3. Create controls as in image

(name them: AddressBox, CallButton) 3. Import dll to the project. Appendfollowing lines in file stdafx.h: #define _ATL_ATTRIBUTES #include <atlbase.h> #import "C:\\Program Files\\Abto, LLC\\SIP VoIP SDK\\binary\\SIPVoipSDK.dll" no_namespace embedded_idl [module(name="SIPPhone")]; 4. Define UserAgent variable. Write following code in SIPPhoneDlg.cpp: IAbtoPhonePtr theAbtoPhone; 5. Add ATL atribute to handle events [event_receiver(com)] class CSIPPhoneDlg : public CDialog { } 6. Add function to handle incoming call events

HRESULT OnIncomingCall(BSTR remoteAddress, long lineId);

7. Add function to handle Start Call button void OnBnClickedCallStart(); 8. Add code to initialize/handle incoming cals/initiate call BOOL CSIPPhoneDlg::OnInitDialog() { CDialog::OnInitDialog(); SetIcon(m_hIcon, TRUE); SetIcon(m_hIcon, FALSE);




//Create phone component HRESULT hr = theAbtoPhone.CreateInstance(__uuidof(CAbtoPhone)); if(FAILED(hr)) { AfxMessageBox(_T("Can't load CAbtoPhone component.\nCheck is registered 'SIPVoIPSDK.dll'")); return TRUE; } //Hook event __hook(&_IAbtoPhoneEvents::OnIncomingCall, theAbtoPhone, &CSIPPhoneDlg::OnIncomingCall); //Get config IConfigPtr phoneCfg; theAbtoPhone->get_Config(&phoneCfg); //Log level //phoneCfg->put_LogLevel(eLogWarning); //Apply modified config theAbtoPhone->ApplyConfig(); //Initialize hr = theAbtoPhone->Initialize(); if(hr == DISP_E_EXCEPTION) { AfxMessageBox(_T("Some troubles with component initialization")); return TRUE; } return TRUE; } HRESULT CSIPPhoneDlg::OnIncomingCall(BSTR remoteAddress, long lineId) { int resp = AfxMessageBox(CString(remoteAddress) + CString(_T("Answer?")), MB_YESNO); if(resp == IDYES) theAbtoPhone->AnswerCall(); else theAbtoPhone->RejectCall(); return S_OK; } void CSIPPhoneDlg::OnBnClickedCallStart() { CString address; GetDlgItemText(IDC_ADDRESS_EDIT, address); if(!address.IsEmpty()) theAbtoPhone->StartCall(address.AllocSysString()); }

Run application




That's it. We have added sdk to our application. Now compile the application and copy it to second computer. Please do not forget to install SIP SDK on second computer. Suppose computer1 IP address is 192.168.0.101 and computer2 IP address is 192.168.0.102. Run the application on both computers. Then on second computer enter address sip:192.168.0.101 and press Start Call. That's it. Now you should be able to talk and hear on both ends. Also please check samples_source_code folder from SIP SDK installation for further examples.




How to handle ABTO SDK events in different languages

Tutorial for Visual Basic 2005

Imports SIPVoipSDK

2. Declare phone component in the following way:

Private AbtoPhone As CAbtoPhoneClass

3. Create phone component and add event handlers

Public Sub New() Me.AbtoPhone = New CAbtoPhoneClass() Me.LineConnections = New ArrayList() Me.InitializeComponent() 'Event handlers AddHandler AbtoPhone.OnInitialized, AddressOf AbtoPhone_OnInitialized AddHandler AbtoPhone.OnLineSwiched, AddressOf AbtoPhone_OnLineSwiched AddHandler AbtoPhone.OnEstablishedCall, AddressOf AbtoPhone_OnEstablishedCall AddHandler AbtoPhone.OnIncomingCall, AddressOf AbtoPhone_OnIncomingCall AddHandler AbtoPhone.OnClearedCall, AddressOf AbtoPhone_OnClearedCall AddHandler AbtoPhone.OnVolumeUpdated, AddressOf AbtoPhone_OnVolumeUpdated AddHandler AbtoPhone.OnRegistered, AddressOf AbtoPhone_OnRegistered AddHandler AbtoPhone.OnUnRegistered, AddressOf AbtoPhone_OnUnRegistered AddHandler AbtoPhone.OnPlayFinished, AddressOf AbtoPhone_OnPlayFinished AddHandler AbtoPhone.OnEstablishedConnection, AddressOf AbtoPhone_OnEstablishedConnection AddHandler AbtoPhone.OnClearedConnection, AddressOf AbtoPhone_OnClearedConnection AddHandler AbtoPhone.OnToneReceived, AddressOf AbtoPhone_OnToneReceived AddHandler AbtoPhone.OnTextMessageReceived, AddressOf AbtoPhone_OnTextMessageReceived AddHandler AbtoPhone.OnPhoneNotify, AddressOf AbtoPhone_OnPhoneNotify AddHandler AbtoPhone.OnRemoteAlerting, AddressOf AbtoPhone_OnRemoteAlerting AddHandler AbtoPhone.OnHoldCall, AddressOf AbtoPhone_OnHoldCall AddHandler AbtoPhone.OnTextMessageSentStatus, AddressOf AbtoPhone_OnTextMessageSentStatus End Sub

4. Implement handlers Private Sub AbtoPhone_OnInitialized(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnLineSwiched(ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnEstablishedCall(ByVal adress As String, ByVal lineId As Integer) End Sub




Private Sub AbtoPhone_OnIncomingCall(ByVal adress As String, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnClearedCall(ByVal Msg As String, ByVal status As Integer, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnVolumeUpdated(ByVal IsMicrophone As Integer, ByVal level As Integer) End Sub Private Sub AbtoPhone_OnRegistered(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnUnRegistered(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnPlayFinished(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnEstablishedConnection(ByVal addrFrom As String, ByVal addrTo As String, ByVal connectionId As Integer, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnClearedConnection(ByVal connectionId As Integer, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnToneReceived(ByVal tone As Integer, ByVal connectionId As Integer, ByVal lineId As Integer) End Sub

Private Sub AbtoPhone_OnTextMessageReceived(ByVal address As String, ByVal message As String) End Sub

Private Sub AbtoPhone_OnPhoneNotify(ByVal Msg As String) End Sub

Private Sub AbtoPhone_OnRemoteAlerting(ByVal ConnectionId As Integer, ByVal responseCode As Integer, ByVal reasonMsg As String) End Sub Private Sub AbtoPhone_OnHoldCall(ByVal LineId As Integer, ByVal isHeld As Integer) End Sub Private Sub AbtoPhone_OnTextMessageSentStatus(ByVal address As String, ByVal reason As String, ByVal bSuccess As Integer) End Sub




Tutorial for Visual Basic 6

1. Declare phone component in the following way:

Private WithEvents AbtoPhone As CAbtoPhone

2. Declare and implement handlers Private Sub AbtoPhone_OnInitialized(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnLineSwiched(ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnEstablishedCall(ByVal adress As String, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnIncomingCall(ByVal adress As String, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnClearedCall(ByVal Msg As String, ByVal status As Integer, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnVolumeUpdated(ByVal IsMicrophone As Integer, ByVal level As Integer) End Sub Private Sub AbtoPhone_OnRegistered(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnUnRegistered(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnPlayFinished(ByVal Msg As String) End Sub Private Sub AbtoPhone_OnEstablishedConnection(ByVal addrFrom As String, ByVal addrTo As String, ByVal connectionId As Integer, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnClearedConnection(ByVal connectionId As Integer, ByVal lineId As Integer) End Sub Private Sub AbtoPhone_OnToneReceived(ByVal tone As Integer, ByVal connectionId As Integer, ByVal lineId As Integer) End Sub




Private Sub AbtoPhone_OnTextMessageReceived(ByVal address As String, ByVal message As String) End Sub

Private Sub AbtoPhone_OnPhoneNotify(ByVal Msg As String) End Sub

Private Sub AbtoPhone_OnRemoteAlerting(ByVal ConnectionId As Integer, ByVal responseCode As Integer, ByVal reasonMsg As String) End Sub Private Sub AbtoPhone_OnHoldCall(ByVal LineId As Integer, ByVal isHeld As Integer) End Sub Private Sub AbtoPhone_OnTextMessageSentStatus(ByVal address As String, ByVal reason As String, ByVal bSuccess As Integer) End Sub

Tutorial for Visual C++ 2005

1. Declare class, that will handle events: [event_receiver(com)] class CMainDlg : public CDialog { ... }; 2. Declare event handlers and helper functions as class members: HRESULT AbtoPhone_OnInitialized(BSTR Msg); HRESULT AbtoPhone_OnLineSwiched(long lineId); HRESULT AbtoPhone_OnEstablishedCall(BSTR Msg, long lineId); HRESULT AbtoPhone_OnIncomingCall(BSTR remoteAddress, long lineId); HRESULT AbtoPhone_OnClearedCall(BSTR Msg, long Status, long lineId); HRESULT AbtoPhone_OnToneReceived(LONG tone, LONG connectionId, LONG lineId); HRESULT AbtoPhone_OnVolumeUpdated(long IsMicrophone, long level); HRESULT AbtoPhone_OnRegistered(BSTR Msg); HRESULT AbtoPhone_OnUnRegistered(BSTR Msg); HRESULT AbtoPhone_OnPlayFinished(BSTR Msg); HRESULT AbtoPhone_OnEstablishedConnection(BSTR AddrFrom, BSTR AddrTo, long connectionId, long lineId); HRESULT AbtoPhone_OnClearedConnection(long connectionId, long lineId); HRESULT AbtoPhone_OnTextMessageReceived(BSTR from, BSTR message); HRESULT AbtoPhone_OnTextMessageSentStatus(BSTR from, BSTR reason, long bSuccess); HRESULT AbtoPhone_OnPhoneNotify(BSTR Msg); HRESULT AbtoPhone_OnRemoteAlerting(long connectionId, long responseCode, BSTR reasonMsg); HRESULT AbtoPhone_OnHoldCal(long lineId, long isHeld);

void HookPhoneEvents(IAbtoPhone* pSource); void UnHookPhoneEvents(IAbtoPhone* pSource);




3. Implement helpers functions:

void CMainDlg::HookPhoneEvents(IAbtoPhone* pSource) { __hook(&_IAbtoPhoneEvents::OnInitialized, pSource, &CMainDlg::AbtoPhone_OnInitialized); __hook(&_IAbtoPhoneEvents::OnEstablishedConnection, pSource, &CMainDlg::AbtoPhone_OnEstablishedConnection); __hook(&_IAbtoPhoneEvents::OnClearedConnection, pSource, &CMainDlg::AbtoPhone_OnClearedConnection); __hook(&_IAbtoPhoneEvents::OnIncomingCall, pSource, &CMainDlg::AbtoPhone_OnIncomingCall); __hook(&_IAbtoPhoneEvents::OnEstablishedCall, pSource, &CMainDlg::AbtoPhone_OnEstablishedCall); __hook(&_IAbtoPhoneEvents::OnClearedCall, pSource, &CMainDlg::AbtoPhone_OnClearedCall); __hook(&_IAbtoPhoneEvents::OnVolumeUpdated, pSource, &CMainDlg::AbtoPhone_OnVolumeUpdated); __hook(&_IAbtoPhoneEvents::OnRegistered, pSource, &CMainDlg::AbtoPhone_OnRegistered); __hook(&_IAbtoPhoneEvents::OnUnRegistered, pSource, &CMainDlg::AbtoPhone_OnUnRegistered); __hook(&_IAbtoPhoneEvents::OnPlayFinished, pSource, &CMainDlg::AbtoPhone_OnPlayFinished); __hook(&_IAbtoPhoneEvents::OnToneReceived, pSource, &CMainDlg::AbtoPhone_OnToneReceived); __hook(&_IAbtoPhoneEvents::OnTextMessageReceived, pSource, &CMainDlg::AbtoPhone_OnTextMessageReceived); __hook(&_IAbtoPhoneEvents::OnTextMessageSentStatus, pSource, &CMainDlg::AbtoPhone_OnTextMessageSentStatus); __hook(&_IAbtoPhoneEvents::OnPhoneNotify, pSource, &CMainDlg::AbtoPhone_OnPhoneNotify); __hook(&_IAbtoPhoneEvents::OnLineSwiched, pSource, &CMainDlg::AbtoPhone_OnLineSwiched); __hook(&_IAbtoPhoneEvents::OnRemoteAlerting, pSource, &CMainDlg::AbtoPhone_OnRemoteAlerting); __hook(&_IAbtoPhoneEvents::OnHoldCall, pSource, &CMainDlg::AbtoPhone_OnHoldCal); } void CMainDlg::UnHookPhoneEvents(IAbtoPhone* pSource) { __unhook(pSource); }

4. Invoke helper functions after component created and before destroyed:

BOOL CMainDlg::OnInitDialog() {

....

HRESULT hr = theAbtoPhone.CreateInstance(__uuidof(CAbtoPhone)); //Create event receiver HookPhoneEvents(theAbtoPhone);

...

}

void CMainDlg::OnClose() {




...

//Delete event handler UnHookPhoneEvents(theAbtoPhone); //Release component theAbtoPhone.Release();

...

}

5. Implement event handlers:

HRESULT CMainDlg::AbtoPhone_OnInitialized(BSTR Msg) { } HRESULT CMainDlg::AbtoPhone_OnLineSwiched(long lineId) { } HRESULT CMainDlg::AbtoPhone_OnEstablishedCall(BSTR Msg, long lineId) { } HRESULT CMainDlg::AbtoPhone_OnIncomingCall(BSTR remoteAddress, long lineId) { } HRESULT CMainDlg::AbtoPhone_OnClearedCall(BSTR Msg, long Status, long lineId) { } HRESULT CMainDlg::AbtoPhone_OnToneReceived(LONG tone, LONG connectionId, LONG lineId) { } HRESULT CMainDlg::AbtoPhone_OnVolumeUpdated(long IsMicrophone, long level) { } HRESULT CMainDlg::AbtoPhone_OnRegistered(BSTR Msg) { } HRESULT CMainDlg::AbtoPhone_OnUnRegistered(BSTR Msg) { }

HRESULT CMainDlg::AbtoPhone_OnPlayFinished(BSTR Msg) { } HRESULT CMainDlg::AbtoPhone_OnEstablishedConnection(BSTR AddrFrom, BSTR AddrTo, long connectionId, long lineId) { } HRESULT CMainDlg::AbtoPhone_OnClearedConnection(long connectionId, long lineId) { } HRESULT CMainDlg::AbtoPhone_OnTextMessageReceived(BSTR from, BSTR message) { } HRESULT CMainDlg::AbtoPhone_OnTextMessageSentStatus(BSTR from, BSTR reason, long bSuccess) { } HRESULT CMainDlg::AbtoPhone_OnPhoneNotify(BSTR Msg) { } HRESULT CMainDlg::AbtoPhone_OnRemoteAlerting(long connectionId, long responseCode, BSTR reasonMsg) { } HRESULT CMainDlg::AbtoPhone_OnHoldCal(long lineId, long isHeld) { }

*Look implementation details in SDK examples.

Tutorial for JavaScript

Important: Only IE browser supports ABTO Software VoIP SIP SDK!

Declare and implement event handlers in following way:

<title>JavaScript example</title> <script language="javascript" for="AbtoPhone" event="OnInitialized(msg)">

</script>

<script language="javascript" for="AbtoPhone" event="OnLineSwiched(lineId)">  </script>

<script language="javascript" for="AbtoPhone" event="OnEstablishedCall(msg)">  </script>

<script language="javascript" for="AbtoPhone" event="OnIncomingCall(adress, lineId)">  </script>

<script language="javascript" for="AbtoPhone" event="OnClearedCall(msg, status, lineId )">  </script> <script language="javascript" for="AbtoPhone" event="OnVolumeUpdated(IsMic, level)">  </script>

<script language="javascript" for="AbtoPhone" event="OnRegister(msg)">  </script>

<script language="javascript" for="AbtoPhone" event="OnUnRegister(msg)">  </script>

<script language="javascript" for="AbtoPhone" event="OnPlayFinished(msg)">  </script>

<script language="javascript" for="AbtoPhone" event="OnEstablishedConnection(addrFrom, addrTo, connectionId, lineId)">  </script>

<script language="javascript" for="AbtoPhone" event="OnClearedConnection(connectionId, lineId)">  </script>

<script language="javascript" for="AbtoPhone" event="OnToneReceived(tone, connectionId, lineId)">  </script>




}

function UserAgent_OnPlayFinished(msg) { }

function OnEstablishedConnection(addrFrom, addrTo, connectionId, lineId) { }

function OnClearedConnection(connectionId, lineId) { }

function UserAgent_OnToneReceived(tone, connectionId, lineId) { }

function OnTextMessageReceived(address, message) { }

function UserAgent_OnPhoneNotify(msg) { }

function OnRemoteAlerting(ConnectionId, responseCode, reasonMsg) { }

function OnTextMessageSentStatus(address, reason, bSuccess) { }

//--> </script>

Tutorial for Delphi 7

1. Declare event handlers in following way: { event handlers } procedure AbtoPhone_OnInitialized(ASender: TObject; const Msg: WideString);




procedure AbtoPhone_OnLineSwitched(Sender: TObject; LineId: Integer); procedure AbtoPhone_OnEstablishedCall(ASender: TObject; const Msg: WideString; LineId: Integer); procedure AbtoPhone_OnIncomingCall(ASender: TObject; const AddrFrom: WideString; LineId: Integer); procedure AbtoPhone_OnClearedCall(ASender: TObject; const Msg: WideString; Status: Integer; LineId: Integer); procedure AbtoPhone_OnVolumeUpdated(Sender: TObject; IsMicrophone: Integer; Level: Integer); procedure AbtoPhone_OnRegistered(ASender: TObject; const Msg: WideString); procedure AbtoPhone_OnUnregistered(ASender: TObject; const Msg: WideString); procedure AbtoPhone_OnPlayFinished(ASender: TObject; const Msg: WideString); procedure AbtoPhone_OnEstablishedConnection(ASender: TObject; const AddrFrom: WideString; const AddrTo: WideString; ConnectionId: Integer; LineId: Integer); procedure AbtoPhone_OnClearedConnection(Sender: TObject; ConnectionId: Integer; LineId: Integer); procedure AbtoPhone_OnToneReceived(ASender: TObject; Tone: Integer; ConnectionId: Integer; LineId: Integer); procedure AbtoPhone_OnTextMessageReceived(ASender: TObject; const address: WideString; const message: WideString); procedure AbtoPhone_OnNotify(ASender: TObject; const Msg: WideString); procedure AbtoPhone_OnRemoteAlerting(ASender: TObject; ConnectionId: Integer; responseCode: Integer; const reasonMsg: WideString); procedure AbtoPhone_OnHoldCall(ASender: TObject; LineId: Integer; isHeld: Integer); procedure AbtoPhone_OnTextMessageSentStatus(ASender: TObject; const address: WideString; const reason: WideString; bSuccess: Integer); 2. Assign handers to events: procedure TSipPhoneForm.FormCreate(Sender: TObject); var ... begin ... AbtoPhone := SIPVoipSDK_TLB.TCAbtoPhone.Create(Self); ... ... Self.AbtoPhone.OnInitialized := AbtoPhone_OnInitialized; Self.AbtoPhone.OnLineSwiched := AbtoPhone_OnLineSwitched; Self.AbtoPhone.OnEstablishedCall := AbtoPhone_OnEstablishedCall; Self.AbtoPhone.OnIncomingCall := AbtoPhone_OnIncomingCall; Self.AbtoPhone.OnClearedCall := AbtoPhone_OnClearedCall; Self.AbtoPhone.OnVolumeUpdated := AbtoPhone_OnVolumeUpdated; Self.AbtoPhone.OnRegistered := AbtoPhone_OnRegistered; Self.AbtoPhone.OnUnRegistered := AbtoPhone_OnUnregistered; Self.AbtoPhone.OnPlayFinished := AbtoPhone_OnPlayFinished; Self.AbtoPhone.OnEstablishedConnection:= AbtoPhone_OnEstablishedConnection; Self.AbtoPhone.OnClearedConnection := AbtoPhone_OnClearedConnection; Self.AbtoPhone.OnPhoneNotify := AbtoPhone_OnNotify; Self.AbtoPhone.OnToneReceived := AbtoPhone_OnToneReceived; Self.AbtoPhone.OnTextMessageReceived := AbtoPhone_OnTextMessageReceived; Self.AbtoPhone.OnRemoteAlerting := AbtoPhone_OnRemoteAlerting; Self.AbtoPhone.OnHoldCall := AbtoPhone_OnHoldCall; Self.AbtoPhone.OnTextMessageSentStatus:= AbtoPhone_OnTextMessageSentStatus;




end; 3. Implement handers: { event handlers } procedure TSipPhoneForm.AbtoPhone_OnInitialized(ASender: TObject; const Msg: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnLineSwitched(Sender: TObject; LineId: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnEstablishedCall(ASender: TObject; const Msg: WideString; LineId: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnIncomingCall(ASender: TObject; const AddrFrom: WideString; LineId: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnClearedCall(ASender: TObject; const Msg: WideString; Status: Integer; LineId: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnVolumeUpdated(Sender: TObject; IsMicrophone: Integer; Level: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnRegistered(ASender: TObject; const Msg: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnUnregistered(ASender: TObject; const Msg: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnPlayFinished(ASender: TObject; const Msg: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnEstablishedConnection(ASender: TObject; const AddrFrom: WideString; const AddrTo: WideString; ConnectionId: Integer; LineId: Integer); var end; procedure TSipPhoneForm.AbtoPhone_OnClearedConnection(Sender: TObject; ConnectionId: Integer; LineId:




Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnNotify(ASender: TObject; const Msg: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnToneReceived(ASender: TObject; Tone: Integer; ConnectionId: Integer; LineId: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnTextMessageReceived(ASender: TObject; const address: WideString; const message: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnRemoteAlerting(ASender: TObject; ConnectionId: Integer; responseCode: Integer; const reasonMsg: WideString); begin end; procedure TSipPhoneForm.AbtoPhone_OnHoldCall(ASender: TObject; LineId: Integer; isHeld: Integer); begin end; procedure TSipPhoneForm.AbtoPhone_OnTextMessageSentStatus(ASender: TObject; const address: WideString; const reason: WideString; bSuccess: Integer); begin end;

Tutorial for Visual C# 2005

1. Append using section using SIPVoipSDK; 2. Declare and create phone component in the following way private CAbtoPhoneClass AbtoPhone = new CAbtoPhoneClass(); 3. Add event handlers public SIPPhoneForm() { this.AbtoPhone.OnInitialized += new _IAbtoPhoneEvents_OnInitializedEventHandler(this.AbtoPhone_OnInitialized);




this.AbtoPhone.OnLineSwiched += new _IAbtoPhoneEvents_OnLineSwichedEventHandler(this.AbtoPhone_OnLineSwiched); this.AbtoPhone.OnEstablishedCall += new _IAbtoPhoneEvents_OnEstablishedCallEventHandler(this.AbtoPhone_OnEstablishedCall); this.AbtoPhone.OnIncomingCall += new _IAbtoPhoneEvents_OnIncomingCallEventHandler(this.AbtoPhone_OnIncomingCall); this.AbtoPhone.OnClearedCall += new _IAbtoPhoneEvents_OnClearedCallEventHandler(this.AbtoPhone_OnClearedCall); this.AbtoPhone.OnVolumeUpdated += new _IAbtoPhoneEvents_OnVolumeUpdatedEventHandler(this.AbtoPhone_OnVolumeUpdated); this.AbtoPhone.OnRegistered += new _IAbtoPhoneEvents_OnRegisteredEventHandler(this.AbtoPhone_OnRegistered); this.AbtoPhone.OnUnRegistered += new _IAbtoPhoneEvents_OnUnRegisteredEventHandler(this.AbtoPhone_OnUnRegistered); this.AbtoPhone.OnPlayFinished += new _IAbtoPhoneEvents_OnPlayFinishedEventHandler(this.AbtoPhone_OnPlayFinished); this.AbtoPhone.OnEstablishedConnection += new _IAbtoPhoneEvents_OnEstablishedConnectionEventHandler(this.AbtoPhone_OnEstablishedConnection); this.AbtoPhone.OnClearedConnection += new _IAbtoPhoneEvents_OnClearedConnectionEventHandler(this.AbtoPhone_OnClearedConnection); this.AbtoPhone.OnToneReceived += new _IAbtoPhoneEvents_OnToneReceivedEventHandler(this.AbtoPhone_OnToneReceived); this.AbtoPhone.OnTextMessageReceived += new _IAbtoPhoneEvents_OnTextMessageReceivedEventHandler(this.AbtoPhone_OnTextMessageReceived); this.AbtoPhone.OnPhoneNotify += new _IAbtoPhoneEvents_OnPhoneNotifyEventHandler(this.AbtoPhone_OnPhoneNotify); this.AbtoPhone.OnRemoteAlerting += new _IAbtoPhoneEvents_OnRemoteAlertingEventHandler(this.AbtoPhone_OnRemoteAlerting); InitializeComponent(); } 4. Implement handlers private void AbtoPhone_OnInitialized(string Msg) { } private void AbtoPhone_OnLineSwiched(int lineId) { } private void AbtoPhone_OnEstablishedCall(string adress, int lineId) { } private void AbtoPhone_OnIncomingCall(string adress, int lineId) { } private void AbtoPhone_OnClearedCall(string Msg, int status, int lineId) {




} private void AbtoPhone_OnToneReceived(int, int connectionId, int lineId) { private void AbtoPhone_OnVolumeUpdated(int IsMicrophone, int level) { } private void AbtoPhone_OnRegistered(string Msg) { } private void AbtoPhone_OnUnRegistered(string Msg) { } private void AbtoPhone_OnPlayFinished(string Msg) { } private void AbtoPhone_OnEstablishedConnection(string addrFrom, string addrTo, int connectionId, int lineId) { } private void AbtoPhone_OnClearedConnection(int connectionId, int lineId) { } private void AbtoPhone_OnTextMessageReceived(string from, string message) { private void AbtoPhone_OnPhoneNotify(string message) { } private void AbtoPhone_OnRemoteAlerting(int connectionId, int responseCode, string reasonMsg) { } *Look implementation details in SDK examples.




ABTOPHONE NAMESPACE

_IAbtoPhoneEvents Interface

Namespace: ABTOPhone Assembly: Interop.SIPVoipSDK.dll

Events

Name Description

OnInitialized

SDK generates this event when internal initialization completed. Syntax: HRESULT OnInitialize([in] BSTR Msg); Event arguments: Msg – is equal to “Initialized” when SDK completely initialized, or contains error string. Possible error string are: “No output audio devices present!” “No input audio devices present!” “No network interfaces present!” “No codecs found!” “License key not set” etc.

OnLineSwiched

SDK generates this event when some line become current after call IAbtoPhone::SetCurrentLine. Syntax: HRESULT OnLineSwiched([in] LONG LineId); Event arguments: lineId - current line id (possible values: 1,2,3,4,5,6,7,8).

OnEstablishedConnection

SDK generates this event when established new incoming or outgoing connection. Syntax: HRESULT OnEstablishedConnection([in] BSTR AddrFrom,[in] BSTR AddrTo, [in] LONG ConnectionId, [in] LONG LineId); Event arguments: AddrFrom - value from SIP header 'From'. AddrTo - value from SIP header 'To'. ConnectionId - unique Id assigned to this connection. LineId - index of line (in range 1..8) that contains this connection.

OnClearedConnection SDK generates this event when dropped connection that was established before. Syntax:

mk:@MSITStore:C:/Program%20Files%20(x86)/ABTO%20Software/VoIP%20Video%20SIP%20SDK/Help/VoiPSIPSDKHelp.chm::/html/abtophone_namespace.htm




HRESULT OnClearedConnection([in] LONG ConnectionId, [in] LONG LineId); Event arguments: ConnectionId - connection unique Id. LineId - index of line (in range 1..8) that contains this connection.

OnIncomingCall

SDK generates this event when new incoming connection received (after event _IAbtoPhoneEvents::OnEstablishedConnection). Syntax: HRESULT OnIncomingCall([in] BSTR AddrFrom, [in]LONG LineId); Event arguments: AddrFrom - contains value from SIP header 'From'. Has following format: "[CallerId] <sip:[Extension]@[domain]>". Example: " 'NewUser' <sip:[email protected]>", "sip:[email protected]". LineId - index of line (in range 1..8) where received this connection.

OnEstablishedCall

SDK generates this event when user answered incoming call or when outgoing call established. Syntax: HRESULT OnEstablishedCall([in] BSTR Msg, [in]LONG LineId); Event arguments: Msg - typical is equal "Call Established on Line #1". lineID - index of line (in range 1..8) where received this connection.

OnClearedCall

SDK generates this event after was cleared last connection in call (after event _IAbtoPhoneEvents::OnClearedConnection). Also, this event will be generated, when call was unanswered by remote side or remote side wasn't found. Syntax: HRESULT OnClearedCall([in] BSTR Msg, [in] LONG Status, [in]LONG LineId); Event arguments: Msg - typical is equal "Call completed". Status - status code. LineId - index of line (in range 1..8) where cleared this connection.

OnVolumeUpdated

SDK generates this event when speaker/microphone signal level was changed. Note: client application have to be subscribed on this event receiving by using property IConfig::VolumeUpdateSubscribed. By default, this event is not subscribed. Syntax: HRESULT OnVolumeUpdated([in] LONG IsMicrophone, [in] LONG Level);




Event arguments: IsMicrophone - is equal to 1 when changed signal level from misrophone, and 0 - in other case. Level - new level value in range [0.. 32767].

OnRegistered

SDK generates this event when received successful confirmation from registrar server. Syntax: HRESULT OnRegister([in] BSTR Msg); Event arguments: Msg - this string has format: "TEXT: CODE REASON" Where: TEXT - resume string generated by SDK; CODE - Status-Code from SIP response; REASON - Status-Line from SIP response. Example: "Registration success: 200 OK"; "Registration failure: 401 Unauthorized".

OnUnRegistered

SDK generates this event when registration data removed from server. Syntax: HRESULT OnUnRegister([in] BSTR Msg); Event arguments: Msg - always equal to "Registration removed".

OnPlayFinished

SDK generates this event when finished playing of sound file. Syntax: HRESULT OnPlayFinished([in] BSTR Msg); Event arguments: Msg - has following format: "Play Finished on Line: <lineIdx>". Example: "Play Finished on Line: 1". Look also: method IAbtoPhone::PlayFile.




OnToneReceived

SDK generates this event when received DTMF tone from remote side. Syntax: HRESULT OnToneReceived([in] LONG Tone, [in] LONG ConnectionId, [in] LONG LineId); Event arguments: Tone – tone code. ConnectionId – connection from wich this tone received LineId – line Id which this connnection belongs Possible tones are:

Code 48 49 50 51 52 53 54 55 56 57 42 35 65 66 67 68 69 70

Symbol 0 1 2 3 4 5 6 7 8 9 * # A B C D E F

Where 'F' - means tone from fax mashine.

OnTextMessageReceived

SDK will generates this event when received new text message. Syntax: HRESULT OnTextMessageReceived([in] BSTR address, [in] BSTR message); Event arguments: address - contains value from SIP header 'From'. Has following format: "[CallerId] <sip:[Extension]@[domain]>". Example: " 'NewUser' <sip:[email protected]>", "sip:[email protected]". message - received message

OnPhoneNotify

SDK generates this event when it has some additional information about event or phone state. Syntax: HRESULT OnPhoneNotify([in] BSTR Msg); Event arguments: Msg – state string Example: After generation OnRegistered event, SDK also generates this event with message: “Registered as [email protected]”

OnRemoteAlerting

SDK generates this event when received SIP status message from remote side. Syntax: HRESULT OnRemoteAlerting([in] LONG ConnectionId, [in] LONG responseCode, [in] BSTR reasonMsg); Event arguments: ConnectionId - unique id of connection that received this SIP message.




responseCode - contains value from SIP header 'StatusCode'. reasonMsg - contains value from SIP header 'StatusLine'. Example: 2 100 Trying 5 183 Session progres

OnHoldCall

SDK generates this event as result of invoking IAbtoPhone::HoldRetrieveCurrentCall. Syntax: HRESULT OnHoldCall([in]LONG LineId, [in]LONG isHeld); Event arguments: lineId - current line id (possible values: 1,2,3,4,5,6,7,8). isHeld - is equal 1 when call is held.

OnTextMessageSentStatus

SDK generates this event as result of invoking IAbtoPhone::SendTextMessage. Syntax: HRESULT OnTextMessageSentStatus([in] BSTR address, [in] BSTR reason, [in]LONG bSuccess); Event arguments: address - contains value from SIP header 'From'. reason - contains value from SIP header 'StatusLine'. bSuccess - is equal 0 if message wasn't send.

OnRecordFinished

SDK generates this event in 2 cases: a. When early started file recording (IAbtoPhone::StartRecording) was stopped by invoking method IAbtoPhone::StopRecording; b. When early started buffer recording (IAbtoPhone::StartRecordingBuffer) was stopped automatically because of completely filled buffer. Syntax: HRESULT OnRecordFinished([in] BSTR msg); Event arguments: msg - typical equal to 'Record finished'.

OnDetectedAnswerTime

SDK measures duration of received voice answer from remote side and generates this event (only once per call). Explanation: Most humans only talk for about 1.5 seconds where answering machines are usually longer than 3. Look more here: http://blog.tropo.com/2010/12/17/human-vs-answering-machine-detection/. Syntax:




HRESULT OnDetectedAnswerTime([in] LONG TimeSpanMs, [in] LONG ConnectionId); Event arguments: TimeSpanMs contains duration of voice answer from remote side (difference between events VoiceStarted - VoiceStoped received from remote side). ConnectionId - unique Id assigned to this connection. Usage example (C++): HRESULT CMainDlg::AbtoPhone_OnDetectedAnswerTime(LONG TimeSpanMs, LONG ConnectionId) { CString str; str.Format(_T("OnDetectedAnswerTime: '%s' connectionId: %d"), (TimeSpanMs > 3000) ? _T("Machine") : _T("Human") , ConnectionId); DisplayNotifyMsg(str); return S_OK; }




IAbtoPhone Interface


Methods

Name Description

Initialize

This main method that initializes created component. It makes following actions: Check license Check existing output audio devices Check existing input audio devices Check existing network interfaces Check codec's list Initializes internal components When this method successfully finished or some error happens during initialization it generates event _IAbtoPhoneEvents::OnInitialized Syntax: HRESULT Initialize(); Notes: When SDK initialized by this method it sends events from same thread where it was created. We recommend to configure registrar/ports/DNS/LOG and other properties over ICOnfig interface BEFORE this method called.

InitializeEx

This method processes same actions that IAbtoPhone::InitializeEx, but it has one more argument. Syntax: HRESULT Initialize([in]LONG sendEventsFromSameThread); Notes: When SDK initialized by this method and value 'sendEventsFromSameThread' is not zero - it sends events from other internal thread, not from thread where it was created.

SetCurrentLine

This method selects line which will be used by other methods for make calls, playing files, etc. When this method successfully finished it generates event _IAbtoPhoneEvents::OnLineSwiched. Syntax: HRESULT SetCurrentLine([in] LONG lineId); Method arguments:





lineIdx - index of line which set as current. Have to be in range [1..8].

IsLineOccupied

This method returns zero when line is ready to start call. Syntax: HRESULT IsLineOccupied([in] LONG lineId, [out,retval] LONG *Occupied); Method arguments: lineId - index of line which state we would like to get. Have to be in range [1..8]. Occupied - return value. Zero - if line can be used for start call, non zero - in other case (line is speaking, ringing, calling etc.).

StartCall

This method starts new outgoing call. Syntax: HRESULT StartCall([in] BSTR Destination); Method arguments: Destination - SIP address of remote side. It can be fully qualified string like 'sip:extension@server:port' (example 'sip:[email protected]', <sip:[email protected]:5070>) or just extension number like '5555'. In this case SDK will try to convert it to form described above, using existing settings. Example: SDK registered on server 'sipserver.com', when invoke StartCall('5555') SDK converts this address to 'sip:[email protected]'. Notes: 1. When SDK can't convert address to fully qualified form it breaks and generates event _IAbtoPhoneEvents::OnPhoneNotify. 2. SDK tries to find line which can be used for new call, when all lines are busy it breaks. 3. SDK plays internal dial tone when received event _IAbtoPhoneEvents::OnRemoteAlerting(n, 180, "Ringing"). You can disable this feature using property IConfig::DialToneEnabled. 4. When remote side answered call, will be generated events _IAbtoPhoneEvents::OnEstablishedConnection, _IAbtoPhoneEvents::OnEstablishedCall. 5. When remote side doesn't answer call or address not found will be generated event_IAbtoPhoneEvents::OnClearedCall. 6. You can break calling using method IAbtoPhone::HangUpLastCall.

HangUp

This method hangs up selected connection. Syntax: HRESULT HangUp(LONG ConnectionId); Method arguments: ConnectionId - unique id that was received from event




_IAbtoPhoneEvents::OnEstablishedConnection. Note: When connection hanged up will generated event _IAbtoPhoneEvents::OnClearedConnection.

HangUpLastCall

This method process same actions that IAbtoPhone::HangUp. Main difference - it doesn't need arguments and simple hags up last established connection. Syntax: HRESULT HangUpLastCall();

AnswerCall

This method is used for answer incoming call. You have to call it when received event _IAbtoPhoneEvents::OnIncomingCall. Syntax: HRESULT AnswerCall(); Note: When answered call on inactive line - this line doesn't become current automatically.

RejectCall

This method is used for reject incoming call. You have to call it when received event _IAbtoPhoneEvents::OnIncomingCall. Syntax: HRESULT RejectCall();

TransferCall

This method implements unattended transfer call established on current line. Syntax: HRESULT TransferCall([in] BSTR Destination); Method arguments: Destination - string in same format as in IAbtoPhone::StartCall. Notes: 1. When this method invoked, but there is no established call on current line - it breaks. 2. When there is many connections established (conference call) SDK redirects only first connection in the call. 3. When operation completed SDK generates event _IAbtoPhoneEvents::OnPhoneNotify and after that _IAbtoPhoneEvents::OnClearedConnection, _IAbtoPhoneEvents::OnClearedCall.

AttendedTransferCall This method implements attended transfer call established on current line.




Short instruction how to prepare for invoke this method: A. Answer/Start call on line 1 (IAbtoPhone::AnswerCall/IAbtoPhone::StartCall); B. Put call on Hold (IAbtoPhone::HoldRetrieveCurrentCall); C. Set current line 2 (IAbtoPhone::SetCurrentLine); D. Answer (establish) second call (IAbtoPhone::StartCall); E. Make transfer (IAbtoPhone::AttendedTransferCall(1)) to line 1. F. Hang up (IAbtoPhone::HangUpLastCall). Syntax: HRESULT AttendedTransferCall([in] LONG lineId);

TransferConnection

This method allows transfer only selected connection from conference call. Syntax: HRESULT TransferConnection([in] LONG ConnectionId, [in] BSTR Destination); Method arguments: ConnectionId - selected connection ID. Destination - destination where to transfer connection. Notes: Look more on IAbtoPhone::TransferCall

HoldRetrieveCurrentCall

This method holds/retrieves current line call. Syntax: HRESULT HoldRetrieveCurrentCall(); Notes: While call is held no sound is sent/received on local side.

JoinToCurrentCall

This method allows move existing connections into single line and makes conference call. Short instruction how to prepare for invoke this method: A. Answer/Start call on line 1 (IAbtoPhone::AnswerCall/IAbtoPhone::StartCall); B. Set current line 2 (IAbtoPhone::SetCurrentLine); C. Answer/Start call on line 2 (IAbtoPhone::AnswerCall/IAbtoPhone::StartCall); D. Join connection from line 1 to line 2 (IAbtoPhone::JoinToCurrentCall(1)) Syntax: HRESULT JoinToCurrentCall([in] LONG lineId);




Method arguments: lineId - index of line which connections move to current line. Have to be in range [1..8].

PlayFile

This method starts play file on current line. Method returns non zero when playing started. Syntax: HRESULT PlayFile([in] BSTR FilePath, [out,retval] LONG *Succeeded); Method arguments: FilePath - full path to file or just file name. Succeeded - return result. Notes: 1. When passed file name only, SDK tries to find this file in current folder, where executable was started. 2. When passed empty string it stops playback. 3. When playing has already started it generates event _IAbtoPhoneEvents::OnPhoneNotify("File playing has already started") and doesn't start playing new file. 4. File has to have *.wav format. 5. When playing finished SDK generates event _IAbtoPhoneEvents::OnPlayFinished.

PlayFileLine

This method starts play file on selected line. Syntax: HRESULT PlayFileLine([in] BSTR FilePath, [in]LONG lineId, [out,retval] LONG *Succeeded) Notes: See method IAbtoPhone::PlayFile.

StartRecording

This method starts recording sound on current line. Syntax: HRESULT StartRecording([in] BSTR FilePath); Method arguments: FilePath - full path to file or file name. Notes: 1. When passed file name only, SDK stores file into local applicadion data folder. For WinXP it's folder: "C:\Documents and Settings\-USER-\Local Settings\Application Data\VoIP Video SIP SDK" For Win7 it's folder: "C:\Users\-USER-\AppData\Local\VoIP Video SIP SDK" 2. When recording has already started or file already exist, this method




breaks. 3. Pay attention on option IConfig::MP3RecordingEnabled. When this option disabled - SDK creates uncompressed wav file. When this option enabled - SDK creates mp3 file.

StopRecording

This method stops recoding that was started by IAbtoPhone::StartRecording. Syntax: HRESULT StopRecording();

SendTextMessage

This method sends text message. Syntax: HRESULT SendTextMessage([in] BSTR Address, [in] BSTR Message, [in] LONG bSendUnicode); Method arguments: Address - SIP URI "sip:extension@domain", example "sip:[email protected]". When passed only extension number and phone is already registered in some domain, SDK authomatically converts this extension to fully qualified form. Message - text message. bSendUnicode - when this value is not 0, SDK sends message in Unicode format. In other case - message will be converted and sent as ANSI. Notes: As sending result SDK generates event _IAbtoPhoneEvents::OnTextMessageSentStatus

SendTone

This method sends single DTMF to all connections into current line. Syntax: HRESULT SendTone([in] BSTR Tone); Method arguments: Tone - string with single tone character that have to be sent. Example: theAbtoPhone->SendTone("1"); Notes: 1. SDK generates DTMF with duration 200ms. 2. SDK sends only first symbol from input string. 3. Allowed symbols are 0,1,2,3,4,5,6,7,8,9,*,#. 4. When DTMF received on remote side it generates event _IAbtoPhoneEvents::OnToneReceived. 5. SDK sends DTMF in two ways:




Inband as normal audio tones in the RTP stream with no special coding or markers

As specially marked events in the RTP stream - see: RFC4733 (RFC2833)

6. Playing sent tones on local side can be disabled via property IConfig::LocalTonesEnabled

SendToneEx

This method sends single DTMF to all connections into current line, with selected sending methods. Syntax: HRESULT SendToneEx([in] LONG Tone, [in] LONG Duration, [in] BOOL bSendAudio_InBand, [in] BOOL bSend_RFC4733_OutOfBand, [in] BOOL bSend_SIP_INFO); Method arguments: Tone - tone character that has to be sent. Example: theAbtoPhone->SendTone('1') or SendTone(1); Duration - tone duration in miliseconds. bSendAudio_InBand - when this argument not 0, SDK will send tone as in band, audio. bSend_RFC4733_OutOfBand - when this argument not 0, SDK will send tone in RTP stream/out of band. bSend_SIP_INFO - when this argument not 0, SDK will send tone in SIP message INFO.

AppendWav

This method is obsolete and does nothing. Syntax: HRESULT AppendWav([in] BSTR DestinationFilename, [in] BSTR SourceFilename);

RetrieveExternalAddress

This method returns IP address of selected network interface, which used for sent SIP/RTP data. Syntax: HRESULT RetrieveExternalAddress([out, retval] BSTR *pVal);

ApplyConfig

This method reconfigures phone using values updated over config interface. Look more below on property IAbtoPhone::Config. Syntax: HRESULT ApplyConfig();




CancelConfig

This method reverts config interface to previous state, after IAbtoPhone::ApplyConfig was invoked. All changes that was made are ignored. Syntax: HRESULT CancelConfig();

SetConnectionContribution

This method sets input/output gain for selected connection in conference call. Syntax: HRESULT SetConnectionContribution([in] LONG ConnectionId, [in]LONG inputGain, [in]LONG outputGain); Method arguments: ConnectionId - id received from event _IAbtoPhoneEvents::OnEstablishedConnection. inputGain - gain in range [0..100]. outputGain - gain in range [0..100]. Notes: For example, when you have conference call that contains local side and two connections (connectionIdA = 12, connectionIdB =15), and would like to disable microphone for connectionIdA, invoke method in following way: SetConnectionContribution(12, 100, 0).

SetConnectionContributionRelated

This method sets input/output gain for selected connection in relation to other connection into conference call. Syntax: HRESULT SetConnectionContributionRelated([in] LONG ConnectionIdInput, [in] LONG ConnectionIdOutput, [in]LONG inputGain, [in]LONG outputGain); Method arguments: ConnectionIdInput, ConnectionIdOutput - id received from event _IAbtoPhoneEvents::OnEstablishedConnection. inputGain - gain in range [0..100]. outputGain - gain in range [0..100]. Notes: For example, you have conference call, that contains local side and two connections (connectionIdA = 12, connectionIdB = 15), and would like to disable sound from microphone from connectionIdA for connectionIdB, invoke method in following way: SetConnectionContributionRelated(12, 15, 100, 0). ConnectionIdB can't hear sound from microphone from connectionIdA.

SetConnectionContributionRelatedLocal This method does the same with IAbtoPhone::SetConnectionContributionRelated but sets contribution




related to local side. Syntax: HRESULT SetConnectionContributionRelatedLocal([in] LONG ConnectionIdInput, [in] LONG ConnectionIdOutput, [in]LONG inputGain, [in]LONG outputGain); Notes: For example, conference call, that contains local side and two connections (connectionIdA = 12, connectionIdB =15). After SetConnectionContributionRelatedLocal(12, 100, 0) is invoked local side can't hear sound from microphone from connectionIdA.

PlayBuffer

This method starts playing sound from incoming buffer. When there is established call - sound, that is playing will be transfered to remote side. Syntax: HRESULT PlayBuffer([in] LONGLONG buffer_ptr, [in] LONG size, [in] LONG rate); Method arguments: buffer_ptr - pointer on incoming buffer allocated by user. size - buffer lenght. rate - sample rate for sound stored in buffer.

StartRecordingBuffer

This method starts recording sound to incoming buffer. Syntax: HRESULT StartRecordingBuffer([in] LONGLONG buffer_ptr, [in] LONG size); Method arguments: buffer_ptr - pointer on incoming buffer allocated by user. size - buffer lenght. Notes: When buffer completely filled SDK generates event _IAbtoPhoneEvents::OnRecordFinished and stops recording.

RetrieveVersion

This method returns SDK version description. Example: "ABTO SIP SDK 4.6.326.1 build_26.03.2013". Syntax: HRESULT RetrieveVersion([out, retval] BSTR *pVal);

GetSIPHeaderValue

This method allows access to sip headers of last received INVITE message on current line. Values are available after receiving the event OnIncomingCall. Method returns the value for the specified field on success and null if not found.




Syntax: HRESULT GetSIPHeaderValue([in] BSTR Header, [out, retval] BSTR *pHeaderVal); Example: Received message: INVITE sip:[email protected] SIP/2.0 Via: SIP/2.0/UDP 192.168.15.5:5060;branch=z9hG4bK-d8754z-756bf572b2279a64-1---d8754z-;rport Max-Forwards: 70 Call-ID: MzJiNTNkN2FhM2Y5NTE2ODE2MmRjMWU1ZmUyMzUxYzk. CSeq: 1 INVITE Session-Expires: 1800 Min-SE: 90 .... private void onIncomingCall(string addrFrom, int lineId) { // Notice there is no : in the parameter to the method string callId = abtoPhone.GetSIPHeaderValue(“Call-ID”); // callId now has value - MzJiNTNkN2FhM2Y5NTE2ODE2MmRjMWU1ZmUyMzUxYzk. // Continue processing the incoming call per usual }

GetSIPHeaderValueLine

This method does same as 'GetSIPHeaderValue', but has lineId argument. Syntax: HRESULT GetSIPHeaderValueLine([in] BSTR Header, [in]LONG lineId, [out, retval] BSTR *pHeaderVal);

SetSIPHeaderValue

This method allows to add custom headers to outgoing SIP INVITE message. Method has to be invoked before StartCall and headers will be applied only once. Syntax: HRESULT SetSIPHeaderValue([in] BSTR Header, [in] BSTR HeaderVal); Example: private void customStartCall(string dest) { string field = “X-CUSTOM”; string value = “custom header value”; abtoPhone.SetSIPHeaderValue(field, value);




// When we initiate the call the header value will be sent along with the invite. // Continue processing the incoming call per usual that will now send // X-CUSTOM in the invite message. abtoPhone.StartCall(dest); }

StartRecordingConnection

This method starts recording incoming sound from selected connection only. Syntax: HRESULT StartRecordingConnection([in] LONG ConnectionId, [in] BSTR FilePath); Method arguments: ConnectionId - unique id that was received from event _IAbtoPhoneEvents::OnEstablishedConnection. FilePath - full path to file or file name. Notes: Look method IAbtoPhone::StartRecording.

StopRecordingConnection

This method stops recoding that was started by IAbtoPhone::StartRecordingConnection. Syntax: HRESULT StopRecordingConnection([in] LONG ConnectionId);

Properties:

Name Description

Config

This method is used for retrieve special config interface. Syntax: HRESULT Config([out,retval] IConfig **pConfig); Method can be used in following way: A. Get config interface (IAbtoPhone::Config); B. Modify some values using settings form or in directly from code; C. Apply changes (IAbtoPhone::ApplyConfig).

Subscriptions

This method is used for retrieve special subscriptions interface. Syntax: HRESULT Subscriptions([out,retval] ISubscriptions **pSubscriptions);

PlaybackMuted This method mutes/unmutes speaker.




Syntax: HRESULT PlaybackMuted([in] LONG Muted); HRESULT PlaybackMuted([out,retval] LONG *Muted); Property arguments: Muted - set it to 1 for mute, and 0 for unmute.

PlaybackVolume

This property gets/sets speaker sound level. Syntax: HRESULT PlaybackVolume([in] LONG Level); HRESULT PlaybackVolume([out,retval] LONG *Level); Property arguments: Level - level value. Has to be in range [0..100].

RecordMuted

This method mutes/unmutes microphone. Syntax: HRESULT RecordMuted([in] LONG Muted); HRESULT RecordMuted([out,retval] LONG *Muted); Property arguments: Muted - set it to 1 for mute, and 0 for unmute.

RecordVolume

This property gets/sets microphone sound level. Syntax: HRESULT RecordVolume([in] LONG Level); HRESULT RecordVolume([out,retval] LONG *Level); Property arguments: Level - microphone sound level. Has to be in range [0..100].




IConfig Interface


Methods

Name Description

Load

This method loads phone properties from text file. Syntax: HRESULT Load([in] BSTR fileName, [out, retval] LONG *Result); Method arguments: fileName - full path to file or just file name. Result - non zero if file was read successfully. Notes: Existing examples uses the file "phoneCfg.ini". When passed file name only, SDK tries to find this file into application data folder (see below), then, if not found - in folder where application was started. SDK setup places this file into folder: For WinXP it's folder: "C:\Documents and Settings\-USER-\Local Settings\Application Data\VoIP Video SIP SDK" For Win7 it's folder: "C:\Users\-USER-\AppData\Local\VoIP Video SIP SDK"

Store

This method saves config properties in file. Syntax: HRESULT Store([in] BSTR fileName); Method arguments: fileName - full path to file or just file name. Notes: Existed file content will be replaced. See also notes for IConfig::Load

LoadFromStr

This method loads phone properties from input string. Syntax: HRESULT LoadFromStr([in] BSTR str, [out, retval] LONG *Result); Method arguments: str - string with serialized values. Used same format as SDK writes in config file.

StoreAsStr This method saves config properties in string.





Syntax: HRESULT StoreAsStr([out, retval] BSTR *str);

Properties

Name Description

ListenPort

This property changes UDP port number that is used for send/receive SIP messages. Syntax: HRESULT ListenPort([in] LONG Port); HRESULT ListenPort([out,retval] LONG *Port); Notes: By default this values is equal to 5060.

RtpStartPort

This property changes UDP port that is used for send/receive RTP messages. SDK uses range of RTP ports [RtpStartPort ... RtpStartPort+100]. Default value: 17384. Syntax: HRESULT RtpStartPort([in] LONG Port); HRESULT RtpStartPort([out,retval] LONG *Port);

ActivePlaybackDevice

This property sets device that have to be used for playing sound. Syntax: HRESULT ActivePlaybackDevice([in] BSTR DeviceName); HRESULT ActivePlaybackDevice([out,retval] BSTR *DeviceName); Method arguments: DeviceName - existing device name, received from property IConfig::PlaybackDevice

PlaybackDevice

This property returns playback device specified by index. Syntax: HRESULT PlaybackDevice([in] LONG Index, [out, retval] BSTR *pVal); Method arguments: Index - value on range [0..PlaybackDeviceCount-1] pVal - string, returned device name.

PlaybackDeviceCount

This read-only property returns count of available playback devices. Syntax: HRESULT PlaybackDeviceCount([out, retval] LONG *pVal);

ActiveRecordDevice This property sets microphone device that have to be used for recording sound.




Syntax: HRESULT ActiveRecordDevice([in] BSTR DeviceName); HRESULT ActiveRecordDevice([out,retval] BSTR *DeviceName); Method arguments: DeviceName - existing device name, received from property IConfig::RecordDevice

RecordDevice

This property returns microphone device specified by index. Syntax: HRESULT RecordDevice([in] LONG Index, [out, retval] BSTR *pVal); Method arguments: Index - value on range [0..PlaybackDeviceCount-1] pVal - string, returned device name.

RecordDeviceCount

This read-only property returns count of available microphone devices. Syntax: HRESULT RecordDeviceCount([out, retval] LONG *pVal);

ActiveNetworkInterface

This property sets network interface that will be used for sending receiving SIP/RTP messages. Syntax: HRESULT ActiveNetworkInterface([in] BSTR DeviceName); HRESULT ActiveNetworkInterface([out,retval] BSTR *DeviceName);

NetworkInterface

This property returns network interface specified by index. Syntax: HRESULT NetworkInterface([in] LONG Index, [out, retval] BSTR *Name); Method arguments: Index - value on range [0..NetworkInterfaceCount-1] Name - string, returned network interface name. Note Added new interface name "Auto". When this interface name is selected - SDK tries to automatically find proper network transport, based on routing rules between local computer and SIP server where application is registered.

NetworkInterfaceCount

This read-only property returns count of available network interfaces. Syntax: HRESULT NetworkInterfaceCount([out, retval] LONG *pVal);

SetCodecOrder This method allows change codec order.




Syntax: HRESULT SetCodecOrder([in] BSTR CodecksListAsStr, [in] LONG SelectedCount); Method arguments: CodecksListAsStr - codec's order separated by '|' char. Example: "G.711 mu-law|G.711 a-law|Speex NB 8,000bps |". SelectedCount - this argument is obsolete and doesn't used.

CodecCount

This property returns count of loaded codec's. Syntax: HRESULT CodecCount([out, retval] LONG *Count);

CodecName

This property returns codec name specified by index. Syntax: HRESULT CodecName([in] LONG Index, [out, retval] BSTR *Name); Method arguments: Index - value on range [0..CodecCount-1] Name - string, returned codec name.

CodecSelected

This property returns non zero when codec specified by index is selected, and zero - in other case. Syntax: HRESULT CodecSelected([in] LONG Index, [out, retval] LONG *Selected); Method arguments: Index - value on range [0..CodecCount-1] Selected - non zero when codec is selected, and zero - in other case.

EchoCancelationEnabled

This property enables/disables echo cancelation. Syntax: HRESULT EchoCancelationEnabled([in] LONG Enabled); HRESULT EchoCancelationEnabled([out,retval] LONG *Enabled);

SilenceDetectionEnabled This property is obsolete and does nothing.

AutoGainControlEnabled

This property enables/disables auto gain control. Syntax: HRESULT AutoGainControlEnabled([in] LONG Enabled); HRESULT AutoGainControlEnabled([out,retval] LONG *Enabled);

NoiseReductionEnabled

This property enables/disables noise reduction. Syntax: HRESULT NoiseReductionEnabled([in] LONG Enabled);




HRESULT NoiseReductionEnabled([out,retval] LONG *Enabled);

LicenseDomain

This property sets/gets web domain, used for web-key generation. Syntax: HRESULT LicenseDomain([in] BSTR Domain); HRESULT LicenseDomain([out,retval] BSTR *Domain);

LicenseKey

This property sets/gets license key, provided after you buy this SDK. Syntax: HRESULT LicenseKey([in] BSTR Key); HRESULT LicenseKey([out,retval] BSTR *Key);

LicenseUserId

This property sets/gets license user id. Syntax: HRESULT LicenseUserId([in] BSTR UserId); HRESULT LicenseUserId([out,retval] BSTR *UserId);

ProxyDomain

This property sets/gets outbound proxy domain. Syntax: HRESULT ProxyDomain([in] BSTR Domain); HRESULT ProxyDomain([out,retval] BSTR *Domain);

ProxyPass

This property sets/gets outbound proxy password. Syntax: HRESULT ProxyPass([in] BSTR Pass); HRESULT ProxyPass([out,retval] BSTR *Pass);

ProxyUser

This property sets/gets outbound proxy username. Syntax: HRESULT ProxyUser([in] BSTR User); HRESULT ProxyUser([out,retval] BSTR *User);

RegAuthId

This property sets/gets authentification id. Use it, when registrar needs other id that differs from extension number. Syntax: HRESULT RegAuthId([in] BSTR AuthId); HRESULT RegAuthId([out,retval] BSTR *AuthId);

RegDomain

This property sets/gets registrar server, eg. 'callcentric.com', 'iptel.org' etc. Syntax: HRESULT RegDomain([in] BSTR Domain); HRESULT RegDomain([out,retval] BSTR *Domain);

RegExpire This property sets/gets expiration timeout. How long registration remains active, seconds, eg. '300'.




Syntax: HRESULT RegExpire([in] LONG Expire); HRESULT RegExpire([out,retval] LONG *Expire); Note: When this value are equal to 0, SDK won't send REGISTER message. But 'RegDomain' and 'RegUser' values will be used for outgoing calls.

RegPass

This property sets/gets registration password. Syntax: HRESULT RegPass([in] BSTR Pass); HRESULT RegPass([out,retval] BSTR *Pass);

RegRealm

This property sets/gets realm which will be associated with username and password credentials. Syntax: HRESULT RegRealm([in] BSTR Pass); HRESULT RegRealm([out,retval] BSTR *Pass);

RegUser

This property sets/gets registration user name (SIP number, extension). Syntax: HRESULT RegUser([in] BSTR User); HRESULT RegUser([out,retval] BSTR *User);

StunServer

This property sets STUN server. A STUN (Simple Traversal of User Datagram Protocol) server allows clients find out their public address, the type of NAT they are behind and the internet side port associated by the NAT with a particular local port. Value example: stun.ekiga.net Syntax: HRESULT StunServer([in] BSTR StunAddress); HRESULT StunServer([out,retval] BSTR *StunAddress);

CallerId

This property gets/sets caller id (display name). When caller id is not empty, SDK uses it in SIP headers like: "caller_id" <extension@domain>. Syntax: HRESULT CallerId([in] BSTR Id); HRESULT CallerId([out,retval] BSTR *Id);

UserAgent

This property sets/gets string that is placed in SIP message INVITE, header - "UserAgent". Syntax: HRESULT UserAgent([in] BSTR AgentName);




HRESULT UserAgent([out,retval] BSTR *AgentName);

SamplesPerSecond

This property sets/gets number of sound samples per second. It allows change sound quality. By default this value is 32000 samples per second. Syntax: HRESULT SamplesPerSecond([in] LONG Samples); HRESULT SamplesPerSecond([out,retval] LONG *Samples);

DialToneEnabled

This property enables/disables playing internal dial tones (when received event OnRemoteAlerting(n, 180, "Ringing")). Syntax: HRESULT DialToneEnabled([in] LONG Enabled); HRESULT DialToneEnabled([out,retval] LONG *Enabled);

VolumeUpdateSubscribed

This property sets/gets subscription state for event _IAbtoPhoneEvents::OnVolumeUpdated. Subscription is needed because of this event is generated fairly often, and not all clients wants to handle it. Look also _IAbtoPhoneEvents::OnVolumeUpdated. Syntax: HRESULT VolumeUpdateSubscribed([in] LONG Enabled); HRESULT VolumeUpdateSubscribed([out,retval] LONG *Enabled);

LogLevel

This property sets/gets log level. SDK creates log file "SIPVoipSDKLog.txt" in folder where registered "SIPVoIPSDK.dll". Possible log levels are: eLogNone, eLogCritical, eLogError, eLogWarning, eLogInfo, eLogDebug. Syntax: HRESULT LogLevel([in] LogLevelType level); HRESULT LogLevel([out,retval] LogLevelType *level);

AdditionalDnsServer

This property sets/gets additional dns server string. This feature may be need when SDK reports error like "503 No DNS result found". Sometimes can help using Google open DNS "8.8.8.8". Syntax: HRESULT AdditionalDnsServer([in] BSTR dnsServerIPAddress); HRESULT AdditionalDnsServer([out,retval] BSTR *dnsServerIPAddress);

MP3RecordingEnabled

This property sets/gets MP3 recording mode. When this option enabled and invoked method IAbtoPhone::StartRecording SDK will record sound in MP3 format. Recorded file has size less in 11times then wav with same lenght. Syntax:




HRESULT MP3RecordingEnabled([in] LONG Enabled); HRESULT MP3RecordingEnabled([out,retval] LONG *Enabled); Note: This option has no effect in case when started buffer recording using method IAbtoPhone::StartRecordingBuffer;

LocalAudioEnabled

This property sets/gets ability to work without audio devices connected. When this option enabled SDK doesn't check are audio devices connected and also doesn't play any sounds. Syntax: HRESULT LocalAudioEnabled([in] LONG Enabled); HRESULT LocalAudioEnabled([out,retval] LONG *Enabled); Note: This option has to be enabled before invoked method IAbtoPhone::Initialize();

RingToneEnabled

This property enables/disables playing ring tone when received incoming call. When this option enabled SDK tries to play *.wav file, that was set via property IConfig::RingToneFile. If ringtone file is not set or doesn't found will be played single tone with duration 1 second. Syntax: HRESULT RingToneEnabled([in] LONG Enabled); HRESULT RingToneEnabled([out,retval] LONG *Enabled);

RingToneFile

This property allows set custom ring tone that SDK plays when incoming call received. Syntax: HRESULT RingToneFile([in] BSTR wavFile); HRESULT RingToneFile([out,retval] BSTR *wavFile); Note: 1. By default SDK uses file 'telephone-ring.wav'. 2. Ringtone file has to have wav format. 2. When property set as file name only, SDK will try to find it same folder with application exe file.

ActiveVideoDevice

This property sets web camera that will be used for capture video. Syntax: HRESULT ActiveVideoDevice([in] BSTR DeviceName); HRESULT ActiveVideoDevice([out,retval] BSTR *DeviceName);

VideoDevice This property returns web camera specified by index.




Syntax: HRESULT VideoDevice([in] LONG Index, [out, retval] BSTR *Name); Method arguments: Index - value on range [0..VideoDeviceCount-1] Name - string, returned video device name.

VideoDeviceCount

This read-only property returns count of available video devices. Syntax: HRESULT VideoDeviceCount([out, retval] LONG *pVal);

LocalVideoWindow

This property sets/gets window handle where SDK will display pictures captured from local camera. Syntax: HRESULT LocalVideoWindow([in] LONG hVideoWindow); HRESULT LocalVideoWindow([out,retval] LONG* hVideoWindow);

LocalTonesEnabled

This property disables/enables playing DTMF tones on local side when they are sending via method IAbtoPhone::SendTone. Syntax: HRESULT LocalTonesEnabled([in] LONG Enabled); HRESULT LocalTonesEnabled([out,retval] LONG* Enabled);

RemoteVideoWindow

This property sets/gets window handle where SDK will display pictures received from remote side. Syntax: HRESULT RemoteVideoWindow([in] LONG hVideoWindow); HRESULT RemoteVideoWindow([out,retval] LONG* hVideoWindow);

VideoCallEnabled

This property enables/disables all video features. When this option enabled SDK can send/receive video data. Syntax: HRESULT VideoCallEnabled([in] LONG Enabled); HRESULT VideoCallEnabled([out,retval] LONG *Enabled);

CallInviteTimeout

This property defines how long SDK have to wait for remote side response on outgoing call. Syntax: HRESULT CallInviteTimeout([in] LONG timeoutSeconds); HRESULT CallInviteTimeout([out,retval] LONG *timeoutSeconds); Note: timeoutSeconds - value in seconds. Default value is equal to 40 (second).

EncryptedCallEnabled When this property is enabled SDK uses SRTP protocol for sending audio. When this property is disabled SDK uses RTP protocol for sending audio.




Syntax: HRESULT EncryptedCallEnabled([in] LONG Enabled); HRESULT EncryptedCallEnabled([out,retval] LONG *Enabled); Note: Call wan't be established when this option is enabled but remote side doesn't support SRTP.

KeepAliveTimeSIP

When this property is not 0 SDK uses it as time interval in seconds for sending keep alive packets. This feature can help to just keep the SIP port (tunnel) open through the Firewall. Syntax: HRESULT KeepAliveTimeSIP([in] LONG seconds); HRESULT KeepAliveTimeSIP([out,retval] LONG *seconds); Note: By default this option is disabled (equal to 0). Recommended enabled value - 30.

KeepAliveTimeRTP

When this property is not 0 SDK uses it as time interval in seconds for sending keep alive packets. This feature can help to just keep the RTP port (tunnel) open through the Firewall. Syntax: HRESULT KeepAliveTimeRTP([in] LONG seconds); HRESULT KeepAliveTimeRTP([out,retval] LONG *seconds); Note: By default this option is disabled (equal to 0). Recommended enabled value - 180.

ICEEnabled

This property allows enable/disable ICE (Interactive Connectivity Establishment) feature. Syntax: HRESULT ICEEnabled([in] LONG Enabled); HRESULT ICEEnabled([out,retval] LONG *Enabled); Note: When this option is enabled SDK includes in SDP section of SIP INVITE message list of candidates that can be used for RTP connection. Also has to be set STUN setting. Recomended STUN value is stun.xten.com.

DtmfAsSipInfoEnabled This property allows enable/disable sending tones (DTMF) as SIP INFO messages.




Syntax: HRESULT DtmfAsSipInfoEnabled([in] LONG Enabled); HRESULT DtmfAsSipInfoEnabled([out,retval] LONG *Enabled); Note: By default SDK sends tones as: 1. inband as normal audio tones in the RTP stream with no special coding or markers 2. As specially marked events in the RTP stream - see: RFC 2833 3. SIP INFO packets (when enabled this option).

LogPath

This property allows change path where SDK creates log file SIPVoipSDKLog.txt. Syntax: HRESULT LogPath([in] BSTR logFilePath); HRESULT LogPath([out,retval] BSTR *logFilePath); Note: By default SDK creates log file in local application data folder. For WinXP it's folder: "C:\Documents and Settings\-USER-\Local Settings\Application Data\VoIP Video SIP SDK" For Win7 it's folder: "C:\Users\-USER-\AppData\Local\VoIP Video SIP SDK"

VideoFrameWidth

This property allows set witdh of wrame wich SDK will request from local web camera. Syntax: HRESULT VideoFrameWidth([in] LONG Width); HRESULT VideoFrameWidth([out,retval] LONG *Width); Note: Default wideo frame width is equal to 352 (CIF).

VideoFrameHeight

This property allows set height of wrame wich SDK will request from local web camera. Syntax: HRESULT VideoFrameHeight([in] LONG Width); HRESULT VideoFrameHeight([out,retval] LONG *Width); Note: Default wideo frame width is equal to 288 (CIF).

SDPInRingingMsgEnabled

When property enabled - it causes appending SDP part to SIP message Ringing, which SDK sends automatically, when incoming call received. This feature allows receive early media before call is established. Syntax: HRESULT SDPInRingingMsgEnabled([in] LONG Enabled);




HRESULT SDPInRingingMsgEnabled([out,retval] LONG *Enabled);

AutoAnswerEnabled

When property enabled - SDK automatically answers all incoming calls. Syntax: HRESULT AutoAnswerEnabled([in] LONG Enabled); HRESULT AutoAnswerEnabled([out,retval] LONG *Enabled);

MixerFilePlayerEnabled

This property allows change way how SDK plays files. When this option enabled (default state) - SDK plays files via internal mixer. This allows send to remote side mixed sound from microphone, file, tones. Disadvantage of this method - only single line can play file in same time. When this option disabled - SDK plays files via line-dependent player. This allows play different files in different lines in same time, but local sound from microphone can't be sent during playing. Syntax: HRESULT MixerFilePlayerEnabled([in] LONG Enabled); HRESULT MixerFilePlayerEnabled([out,retval] LONG *Enabled);

SignallingTransport

This property allows change transport which SDK uses for sending SIP messages. Possible values are: eTransportUDP, eTransportTCP Default value: eTransportUDP. Syntax: HRESULT SignallingTransport([in] TransportType transp); HRESULT SignallingTransport([out,retval] TransportType *transp);

LoopbackNetworkInterfaceEnabled

This property allows enable sending messages via loopback network interface (127.0.0.1). This mode allows test SDK-based SIP clients and SIP server on same machine. By default proerty is disabled. Syntax: HRESULT LoopbackNetworkInterfaceEnabled([in] LONG Enabled); HRESULT LoopbackNetworkInterfaceEnabled([out,retval] LONG *Enabled);

ExSipAccount_Count

This read-only property returns count of managed SIP accounts. Syntax: ExSipAccount_Count([out, retval] LONG *pVal)

ExSipAccount_Get This method returns managed SIP account specified by index. Syntax:




HRESULT ExSipAccount_Get([in] LONG ExAccountIdx, [out] BSTR* Domain, [out] BSTR* User, [out] BSTR* Pass, [out] BSTR* AuthId, [out] BSTR* DisplName, [out] LONG* Expire, [out] BOOL* bEnable) Method arguments: ExAccountIdx - value on range [0..ExSipAccount_Count-1]. Domain - string, registrar server. Similar with value managed via property 'RegDomain'. User - string, registration user name. Similar with value managed via property 'RegUser'. Pass - string, registration password. Similar with value managed via property 'RegPass'. AuthId - string, authentification id. Similar with value managed via property 'RegAuthId'. DisplName - string, display name. Similar with value managed via property 'CallerId'. Expire - integer, registration expiration timeout. Similar with value managed via property 'RegExpire'. bEnable - bool, is this account enabled.

ExSipAccount_GetDefaultIdx

This method returns index of default account (account which will be used for outgoing calls). Syntax: HRESULT ExSipAccount_GetDefaultIdx([out, retval] LONG* ExAccountIdx)

ExSipAccount_SetDefaultIdx

This method allows to set selected registration account as default for outgoing cals. Syntax: HRESULT ExSipAccount_SetDefaultIdx([in] LONG ExAccountIdx)

ExSipAccount_ResetAll

This method clears all managed accounts list. Syntax: HRESULT ExSipAccount_ResetAll(); Note: Typical use case with editing account list has folowing steps: 1. Get acounts count - 'ExSipAccount_Count' 2. Create GUI view with accounts list - 'ExSipAccount_Get' 3. Edit accounts via GUI view 4. Clear all existing accounts - ExSipAccount_ResetAll 5. Add again modified accounts - ExSipAccount_Add

ExSipAccount_Add

This method adds new SIP account. Syntax: HRESULT ExSipAccount_Add([in] BSTR Domain, [in] BSTR User, [in] BSTR Pass,




[in] BSTR AuthId, [in] BSTR DisplName, [in] LONG Expire, [in] BOOL bEnable, [in] BOOL bDefault); Method arguments: Same with method ''ExSipAccount_Get' bDefault - has to be set as 'true', when default account is adding.

ComfortNoiseOnMutedMicEnabled

In case when you have established call and microphone is muted, SDK send to remote side voice depending on this optin state. When this option is enabled (set to non 0) - SDK generates and sends comfort noise. When this option is disabled (set to 0) - SDK doesnt sends anything. Syntax: HRESULT ComfortNoiseOnMutedMicEnabled([in] LONG Enabled); HRESULT ComfortNoiseOnMutedMicEnabled([out,retval] LONG *Enabled);

SendRingingMsgEnabled

When this option is enabled (set to non 0) - SDK answers incoming calls requests with 180 Ringing. When this option is disabled (set to 0) - SDK doesnt sends anything. Syntax: HRESULT SendRingingMsgEnabled([in] LONG Enabled); HRESULT SendRingingMsgEnabled([out,retval] LONG *Enabled);

MaxJitterDelay This property is obsolete and does nothing.

MinJitterDelay This property is obsolete and does nothing.

SoundBufferDepth This property is obsolete and does nothing.




FAQ. PROBLEMS AND SOLUTIONS

Registration doesn't work

Solution

1. Check Proxy/Domain, User and Password fields. 2. Expire Time property must be a positive integer. 3. Put 'AuthId' same as 'UserName'. 4. Leave 'Realm' field empty. 5. Check your credential using some other application.

Are there any Fax detection options?

Response:

Fax detection is implemented. If a fax signal arrives in the process of transmission, then the event OnToneReceived('F', x, y) is raised.

Shutting down

"Do I need to unregister? Is there a sequence I should be using when I want to shut down the softphone? Currently I am not doing anything".

Response

In general, you don't have to do anything specific, unless there are active calls. In such case, you should "Hang up" first to shutdown correctly. SDK will unregister authomatically before exit or new registration.

How to use codecs?

Response

SDK setup package contains all codecs available. When you want to disable/enable some codecs or change codec order for media negotiation use existing GUI or do it from own source code.




Edit codecs order using GUI: Go to setting form. Check box on each line - allow disable/enable codec; Buttons" MoveUp"/"MoveDown" - allow change codec order; Edit codecs order using source code: Invoke methods in following order: Retrieve config interface using property IAbtoPhone::Config(); Change codec order using method IConfig::SetCodecOrder("G.711 mu-law|G.711 a-law|Speex NB 8,000bps|Speex NB 15,000bps|GSM|RFC4733 DTMF tones|"); Apply changes using method: IAbtoPhone::ApplyConfig(). Modified codecs order will be used when sending INVITE message, in SDP section;

How to turn off one connection?

"When a SIP SDK are managing two simultaneous connections and only one connection need turn off. How is it possible to do this using the example of Delphi".

Response

The solution of this problem has already been demonstrated in the c++ sample. There is a list box where are placed all simultaneous connections in order of its creation. Every created connection has own connectionId, that you can retrieve as parameter of OnEstablishedConnection event. To close the necessary connection invoke method HangUp(connectionId) using as actual parameter the ID of connection that is currently selected in the connection list box.

How to get the current audio level on microphone/speaker?

Response

SDK has ability to display current audio level. To enable this feature: process following steps: A. Subscribe for event receiving using property IConfig::VolumeUpdateSubscribed; B. Hadle event _IAbtoPhoneEvents::OnVolumeUpdated; SDK generates events 10times per second.




How to get/set the current volume level?

Response

Use properties: IAbtoPhone::RecordVolume;

Is there a certain order that things need to be done?

"I was having problems setting the record device. I could get the list of devices fine. But if I set the Record or Sound Device before I run the Initialize() command the device will not be set to the active one. Is there a certain order that things need to be done for all to work together?"

Response

Steps to start call: 1. Create instance of AbtoPhone; 2. Configure instance using: a. Set registration credential; b. Set SIP listen Port; c. Set license key; d. etc. 3. Invoke 'Initialize'. Now you iterate trough: playback/record devices, codecs, network interfaces. 4. Change playback/record device using properties: IConfig::ActivePlaybackDevice; IConfig::ActiveRecordDevice;

5. Look projects in setup package for complete source code examples.

How to reload new version of dll?

Response

1. Copy new version of "SIPVoipSDK.dll" into directory where it is registered/installed. 2. Rebuild your project.




How to distinquish several calls through one application?

Response

To start several call you have to use different lines. Do it in following order: abtoPhone.SetCurrentLine(1); abtoPhone.StartCall(“sip:extension1@domain”); abtoPhone.SetCurrentLine(2); abtoPhone.StartCall(“sip:extension2@domain”); All events, that SDK sends, has lineId identifier, that allows recognize lines.

Does SIP SDK support multi instances in one computer?

Response:

Yes, it does. More over, you can use multiple instances in single application. SDK automatically avoids SIP/RTP ports conflict between instances. Known issue, when using multiple instance of SDK in single process - only single instance can access audio/video devices.

Where can I read the SIP response of a failed call?

Response

Handle event _IAbtoPhoneEvents::OnClearedCall(BSTR Msg, LONG Status, LONG LineId); where 'Status' - contains reason of call end.

How to use "IsLineOccupied" method?

Response

You can use it in the following way: C++ example: LONG lineId = 1; LONG Occupied;




theAbtoPhone->IsLineOccupied(lineId, &Occupied); C# example: int occupied = AbtoPhone.IsLineOccupied(1); When returned result is not equal zero it means that line can be used for start call, in other case - line can has established call, or is calling.

How to avoid "503 No DNS results" message?

Answer

Try to add additional DNS server using property IConfig::AdditionalDnsServer or modify line "DnsServer=8.8.8.8" in phoneCfg.ini. Try to ping registration domain to look does it response. Try to set registration domain as IP adress.

How to get CallerID on incoming call?

Answer

Handle event _IAbtoPhoneEvents::OnIncomingCall(BSTR AddrFrom, LONG LineId) AddrFrom - contains value from SIP header 'From'. It has following format: "[CallerId] <sip:[Extension]@[domain]>". Example: " 'NewUser' <sip:[email protected]>", "sip:[email protected]".

What is "ExpireTime" setting?

Response

ExpireTime it's the period after which registrar server considers the device is out of service and clears any session references. SDK put this value as "Expires" header into REGISER message. Typical value is 300(seconds). If this value is equal to 0, SDK won't send REGISTER message, even when other registration fields (Domain/UserName/Password) are filled.




Can SDK write log file?

Answer

Yes, it can. Log file has name "SIPVoipSDKLog.txt", and by default SDK creates it in same folder where is registred "SIPVoIPSDK.dll". SDK allows change how many details write into log file via property IConfig::LogLevel(LogLevelType l). Possible levels are: eLogNone, eLogCritical, eLogError, eLogWarning, eLogInfo, eLogDebug. Also log level can be changed from phonecfg.ini. Modify line: "LogLevel=4". Possible levels are: -1(disable log), 2, 3, 4, 6, 7 SDK also allows change log file folder via property IConfig::LogPath(BSTR logFilePath).

C# example doesn't work on Win7 x64

Response

In case of getting an runtime error on x64 computer, with .net based examples you have to modify projects Build settings, as shown on image below.




How to copy SDK on another computer?

Response

1. Copy following files from SDK folder "binary": avcodec-53.dll avutil-51.dll codec_g729.dll codec_gsm.dll codec_pcmapcmu.dll codec_tones.dll Interop.SIPVoipSDK.dll lame_enc.dll libspandsp.dll Microsoft.VC80.CRT.manifest msvcp80.dll msvcr80.dll phoneCfg.ini SIPVoipSDK.dll swscale-2.dll 2. Register SDK ActiveX

Start cmd.exe with administrator permissions

Go to folder where copied files on previous stage via command "cd" Example: cd "c:\Program Files\SomeVoipApp"

Type command: regsvr32 SIPVoIPSDK.dll

3. Note All copied files not must to be placed in same folder with custom application. They can be copied into some subfolder like "SIPSDK".

What is the config file phoneCfg.ini?

Response

SDK has ability to serialize IConfig's properties in the text file via methods IConfig::Load, IConfig::Store. Default name of config file is "phoneCfg.ini" and it can be used from all SDK examples applications. You can edit config file using Notepad or some other application and change properties values, it's very helpful when newly added properties isn't presented in Settings form. When some option was not found, or has wrong value in config file SDK uses hardcoded default value.




How to exclude phoneCfg.ini?

Response

1. Remove code that loads settings from ini file: C++: phoneCfg->Load(CComBSTR(m_cfgFileName), &bRes); C#: phoneCfg.Load(cfgFileName);

2. Add/Uncomment code that configures phone settings: //Listen ports //phoneCfg->put_ListenPort(); //phoneCfg->put_RtpStartPort(17400); //License key //phoneCfg->put_LicenseUserId(_T("")); //phoneCfg->put_LicenseKey(_T("")); //Registration data //phoneCfg->put_RegDomain(_T("")); //phoneCfg->put_RegUser(_T("")); //phoneCfg->put_RegPass(_T("")); //Log level //phoneCfg->put_LogLevel(eLogWarning); //Set AdditionalDnsServer as google dns //phoneCfg->put_AdditionalDnsServer(_T("8.8.8.8")); When you don't change some property SDK will use default value. Also, you can configure phone using standart compiled examples, and after that copy values from created phoneCfg.ini, before delete it.

3. Remove code that stores setings in ini file: C++: phoneCfg->Store(CComBSTR(m_cfgFileName)); C#: phoneCfg.Store(cfgFileName);