eyeball ms-sip library v10.0 developer reference guide

Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved.

Eyeball MSSIPLibrary v10.0

Developer Reference Guide

Last Modified: October 2014



1. Introduction

MS-SIP library provides tools to application developers that allow integration of live audio, video communication with Lync servers and clients into new or existing applications and services.


1.1. Supported Platforms and Features MS-SIP library is written in C++ and available for Linux platform.

Developer Platforms

Programming Languages:

C++ Developer Tools: GCC

Supported Features

MS-SIP library supports the following features:

Lync interoperability

Multi-user login

Multi-user calls

Certificate verification for TLS connection

Audio/Video

Application share

Instant Message (IM)

Trusted Application support

Lync federation call support

SIP compression (MS-SIPCOMP)

Bandwidth Management (MS-ICE2BWM)

Presence (MS-PRES)

HD video negotiation, BW estimation, PLI, VSR and more(MS-RTP, MS-RTCP)

Microsoft standard encryption for Multiple call (MS-SRTP)

Conncection Keep-Alive and MTLS (MS-CONMGMT)

NTLMv2 mechanism (MS-NLMP)

Call Hold/Resume, BW extension, MSI, Video receive capabilities and more(MS-SDPEXT)

End-point Identification (MS-SIPAE)

Registration, provisioning mechanism (MS-SIPREGE)

Header extension, GRUU and more (MS-SIPRE) Short-term credential mechanism for Media-Relay (MS-AVEDGEA)


1.2. Programming Conventions

Programming Conventions

In this document, the phrase current user refers to the local user, as opposed to the remote user.

We use the following conventions to define a variable’s data type:

Variable name starting with ‘n’ and ‘i’ such as nFileId, iField refers to an Integer data type

Variable name starting with ‘s’ such as sUserID refers to a String data type

Variable name starting with ‘b’ such as bAccept refers to a Boolean data type

Variable name starting with ‘a’ such as aContactList refers to an array data type. This is a one-dimensional array. Storing two-dimensional information is simply done by concatenating rows to each other, forming a one-dimensional array.

All strings are case-sensitive unless specified otherwise.


2. Supported Standards The supported standard RFC are as follows:

MS-AVEDGEA

MS-CONMGMT

MS-ICE

MS-ICE2

MS-ICE2BWM

MS-NLMP

MS-PRES

MS-RTCP

MS-SDPEXT

MS-SIPAE

MS-SIPCOMP

MS-SIPRE

MS-SIPREGE

MS-SRTP

MS-TURN

MS-TURNBWM


3. Using Eyeball MS-SIP Library


3.1. Creating the Main Objects class SimpleApp : public IEventHandler, public IAudioDataHandlerCallback,

IVideoDataHandlerCallback

{

public:

MsSipAgent *agent;

SimpleApp(){

agent = new MsSipAgent(this);

}

}

SimpleApp *app = new SimpleApp();


3.2. Using the Features and Functions

Set TURN and SIP servers

app->agent->SetTurnServerConfiguration(sStunServer, nStunPort, sTurnServer,

nTurnPort);

app->agent->SetSipServerConfiguration(nAccountId, sSipServer, nSipPort, sDomain);

Login

app->agent->Login(nAccountId, sUsername, sPassword);

OR

Using Trusted application

Set Trusted application certificate and add default application endpoint

app->agent->SetTrustedAppDomainCertificate(iApplicationAccount, sCertificatePath);

app->agent->AddTrustedApplicationEndpoint(iAccount, iApplicationAccount,

sApplicationEndpoint, isDefault);

Start Trusted application negotiation and create connection

app->agent->StartTrustedApplicationNegotiation(iApplicationAccount, sApplicationId,

iListeningPort, sApplicationGRUU, sSipProxyAddress, nSipPort, sApplicationDomain);

Call

app->agent->Call(nAccountId, sCallee, bConf, sConversationId);


3.3. Handling Event Notifications

The application sends several event notifications to the application running on the MS-SIP library. The application needs to handle these events as necessary.

void OnIncomingCall(int iLine, const std::string &sCaller, bool bVideo, bool

bAppShare, bool bIM, bool bConf, int iAccount, const std::string &sMsg, const

std::string &sConversationId, const std::string &sTrustedAppUser){

// Handle Call Request

printf("%s is calling", sCaller.c_str());

// To whom this call arrived (only valid when TrustedApp is in use)

printf("%s to ", sTrustedAppUser.c_str());

}


4. Eyeball MS-SIP: APIs

The Library

The library uses the concept of line as follows:

An application program may be a single-line application or a multi-line application.

Each line is identified using a number. For example, if an application has 3 lines, the lines will be denoted as lines 0, 1 and 2.

When an incoming call is received, Eyeball Messenger SDK assigns the first available line to the call. If all lines are busy, the caller will receive “Busy Here” and the call will not be established.

The SIP Communicator control uses the concept of multiple SIP accounts:

An application program may register multiple user accounts with multiple SIP proxy servers.

Each SIP account is identified using a number provided by the application programmer.

A SIP account could have multiple call lines, but not the reverse. A call line already used by one SIP account cannot be re-used by another SIP account.

Methods and events of the library are described in the next section.


4.1 MS-SIP Methods

Methods

4.1.1 Setting up the Library

Use the following APIs for setting up TURN and SIP-Proxy. MsSipLibrary exposes two APIs for using

predefined IP and port for media and signaling. Microsoft standard MTLS certificate verification and SIP message compression algorithm can be accessible too.

SetTurnServerConfiguration (sTurnUdpAddress, iTurnUdpPort, sTurnTcpAddress, iTurnTcpPort)

Set TURN server configuration

sTurnUdpAddress:

TURN UDP server address.

iTurnUdpPort

TURN UDP server port.

sTurnTcpAddress:

TURN TCP server address.

iTurnTcpPort:


TURN TCP server port.

SetSipServerConfiguration (iAccount, sSipProxyAddress, iSipPort, sSipDomain)

Set SIP server configuration.

iAccount

The account number.

sSipProxyAddress:

SIP server address.

iSipPort:

SIP server port.

sSipDomain:

SIP domain.

SetInterface(bMedia, &vsIPAddress)

Set the network interface(s) for media and signaling. bMedia:

Is true for media candidates, false for signaling.

vsIPAddress:

Is the list of IP addresses.

This must be called before login.

SetPortRange(bMedia, uLower, uUpper)


Set the port ranges for media and signaling. bMedia:

Is true for media candidates, false for signaling.

uLower:

Is the minimum port value.

uUpper:

Is the maximum port value.

This must be called before login.

SetCertificateVerificationCallback( callback)

Set the callback function which will be invoked for verification of certificate for TLS connection. Return 1 if

the verification is to be succeeded, 0 if the verification fails and the connection is to be teared down callback:

the callback function.

StartSipCompressionNegotiation( iAccount)

Start negotiation if SIP compression is to be enabled. iAccount:

The account number.

This must be called before registering if SIP compression is desired. No SIP message like REGISTER must be sent until its response is received via OnSipCompressionNegotiationResponse event.


4.1.2 Standard Lync Sign in

After setting the SIP-Proxy address of Lync Edge or Front end the following APIs should be used for sign in. After using these APIs MsSipLibrary will work as a Lync Client.

Login (iAccount, sUsername, sPassword)

Login with a username and password.

iAccount:

The account number.

sUsername:

Username.

sPassword:

Password.

Logout(iAccount)

Logout from an account.

iAccount:

The account number.


4.1.3 Configure Library to work without signing in

MsSipLibrary can receive and make call and initiate an IM session without sign-in . To enable this feature

make MsSipLibrary a Trusted App in Lync Front-End topology and create a static route for the trusted app listening port for receiving call and create an application endpoint for that trusted application for mak ing outbound call.

SetTrustedAppDomainCertificate(iApplicationAccount, &sCertificatePath)

Set the AD signed domain certificate for trusted application domain. Certificate must be in .pem format.

iApplicationAccount:

Is the trusted application account number.

sCertificatePath:

Is the path of the AD signed domain certificate.

AddTrustedApplicationEndpoint(iAccount, iApplicationAccount, &sApplicationEndpoint, isDefault)


Add the default and other additional endpoint to the related trusted application account.

iAcccount:

The account number provided by application (must be >= 0). iApplicationAccount:


sApplicationEndpoint:

SIP URI of the trusted application endpoint.

isDefault:

is true if the endpoint is default, otherwise false .

This API must be invoked with default endpoint before the negotiation start for application.

StartTrustedApplicationNegotiation(iApplicationAccount, &sApplicationId, iListeningPort, &sApplicationGRUU, &sSipProxyAddress, iSipPort, &sApplicationDomain)

Start trusted application negotiation with Lync server for provisioning.


Is the trusted application account number. sApplicationId:

The name of the Trusted Applications created on Lync Server iListeningPort:

The port on which trusted application will listen. sApplicationGRUU:

The service GRUU of trusted application created on Lync server. sSipProxyAddress:

Lync SIP server address iSipPort:

SIP server port sApplicationDomain:


Domain of the created trusted application.

RemoveTrustedApplication(iApplicationAccount)

Remove trusted application with all of its endpoint.




4.1.4 Set and Use presence services

Lync uses extended SIP messages for presence. By using following APIs this service is achievable from the MSSIP library.

SetPresence(iAccount, &sAvailability)

Set presence for logged in user. iAccount:

The account number.

sAvailability:

Is the availability string such as - "online", "offline", "idle", "busy", "inacall", "busyidle", "donotdisturb" or "away".

Subscribe(iAccount, &sSubscribeURI)

Subscribe for state category for the given remote user. iAccount:

The account number.

sSubscribeURI:

URI of the remote user

This function should be called after OnUpdateContactList event is fired.


UnSubscribe(iAccount, &sUnSubscribeURI)

Un-subscribe for state category for the given remote user. iAccount:

The account number.

sSubscribeURI:

URI of the remote user

This function should be called after OnUpdateContactList event is fired.

GetSubscriberList(iAccount, *pvList)

Get the list of subscribers for the logged in user iAccount:

The account number.

pvList:

The vector in which the list of subscribers' URIs will be inserted.

GetContactList(iAccount, *pvList)

Get the list of contacts for the logged in user. iAccount:

The account number.

pvList:

The vector in which the list of subscribers' URIs will be inserted.

GetContactState(iAccount, &vContactURI, *pvList)


Get the state of remote user. iAccount:

The account number.

vContactURI:

URIs of contacts.

pvList:

states of the contacts will be inserted.

DirectorySearch(iAccount, sSearchName)

Search for username in a domain containing desired name. iAccount:

The account number.

sSearchName:

Is the name to be searched.


4.1.5 Set codec for Media and use SRTP

Codec for audio, video and application share can be set by the following APIs. Microsoft uses their own

media encryption protocol named MS-SRTP. This encryption feature is also available in MsSipLibrary.

The expected video resolution, framerate, bitrate can also be published to the remote end through the library.

SetAudioCodec(iLine, bModality, ullSSRC, &sAudioCodec)

Set audio codecs.

iLine:

Line number for which the audio codec will be set.

bModality:

unused

ullSSRC:

Is the SSRC value that would be used for audio channel

sAudioCodec:

comma separated audio codecs each of whose attributes are separated by space as the following format (the optional fourth attribute is for fmtp):

"sCodecPayload1 sCodecName1 sCodecBitrate1 [sFmtpAttr1], sCodecPayload2 sCodecName2 sCodecBitrate2 [sFmtpAttr2]" eg., "0 PCMU 8000, 111 SIREN 16000, 101 telephone-event 8000 0-16"

To clear the codec the sAudioCodec should be empty. This function should be called before making or answering a call before making a call the iLine should be -1


SetVideoCodec (iLine, bModality, ullSSRC, &sVideoCodec)

Set video codecs.

iLine:

Line number for which the video codec will be set.

bModality:

should be true if attributes for video modality is to be present in the SDP, false otherwise.

ullSSRC:

is the SSRC value that would be used for video channel

sVideoCodec:

comma separated video codecs each of whose attributes are separated by space as the following format (the optional fourth attribute is for fmtp)

"sCodecPayload1 sCodecName1 sCodecBitrate1 [sFmtpAttr1], sCodecPayload2 sCodecName2 sCodecBitrate2 [sFmtpAttr2]" eg., "34 H263 90000, 121 x-rtvc1 90000, 122 X-H264UC 90000 packetization-mode=1;mst-mode=NI-TC"

To clear the codec the sVideoCodec should be empty. This function should be called before making or answering a call. Before making a call the iLine should be -1

SetAppShare(iLine, &sCodec)

Set application sharing support. iLine:

The line number in which the application share will be made.


sCodec:

The codec for the application sharing.

To clear the application share support the sCodec should be empty. This function should be called before making or answering a call. Before making a call the iLine should be -1.

SetVideoReceiveCapabilities (iLine, sVideoPayloadType, sCapabilityId, sWidthofVideoFrame, sHeightofVideoFrame, sFramesPerSecond, sMaximumBitrate)

Set video receive capabilities.

This function must be called immediately after setting video codec using SetVideoCodec(). For multiple resolutions this function must be called for each of them.

To clear a resolution the sWidthofVideoFrame should be empty for that part icular sVideoPayloadType and sCapabilityId.

Since this setting is preserved, this function should be called (multiple times if necessary) before making or answering a call to set/reset the resolution capabilities.

This API can be used to set capabilities through "a=fmtp:". Provide empty string in the last three

parameters and capability value for sWidthofVideoFrame. eg., SetVideoReceiveCapabilities(0, "121", "263", "CIF=15", "", "", "");.

For multiple capability value this function must be called for each of them.

Before making a call the iLine should be -1.

iLine:

The line number for which the video capabilities will be set.

sVideoPayloadType:

The payload Number.

sCapabilityId:

The random unique Id.


sWidthofVideoFrame:

The video frame width.

sHeightofVideoFrame:

The video frame height.

sFramesPerSecond:

The video frame per second.

sMaximumBitrate:

The maximum bitrate per second.

EnableSrtp ( iSrtpState)

Set SRTP mode to Rejected, Optional or Required iSrtpState:

0(Rejected), 1(Optional) and 2(Required)

Use this API before making or receiving a call.


4.1.6 Instant Messaging

Microsofts' session initiated Instant messaging is available in MsSipLibrary. This feature can be accessible through the following APIs.

SetIM(iLine, &supportedIMTypes)

Set supported text message types. iLine:

The line number for which the message types will be set.

supportedIMTypes:

Space separated message types as the following format "sMessageType1 sMessageType2" eg., "text/plain text/rtf text/html"

To clear the message types the supportedIMTypes should be empty. This function should be called before making or answering a call. Before making a call the iLine should be -1

SendChatMessage(iLine, &sMessage)

Send text chat message. iLine:

The line number in which the text message will be sent.

sMessage:

The text message that will be sent


4.1.7 Make and Receive Call

The following APIs are common for audio, video, application share and chat session. After a successful

call MsSipLibrary provides parsed raw media data as RTP header and payload. Inside of the library the encrypted media data is decrypted and provided as raw payload.

Call (iAccount, sCallee, bConf, &sConversationId)

Initiate call. Returns the line number that has been used to make the call

iAccount:

The account number from which the call is to be made.

sCallee:

Callee URI.

bConf:

True if the call is to be added to a conference call, false if the call is to be one-one.

sConversationId:

The conversation ID.

This ID can be used to track if the new dialog is under an existing conversation or create a new conversation and also to create different dialogs with different media but under the same conversation.

HoldLine(iLine, bHold)

Hold or resume a running call. iLine:


The line on which the call is going on.

bHold:

hold or unhold. (true for hold, false for unhold).

EndCall (iLine, bEndAll)

End a running call.

iLine:

The line on which the call is going on, -1 to end all calls

bEndAll:

True if the call is ended otherwise false.

ModifySession (iLine, bUnused, bVideo)

Add/remove video in/from an on going call.

iLine:


bUnused:

Reserved.

bVideo:

True to add video, false to remove video.

RespondCall ( iLine, bAccept, bConf, iReasonCode, &sReasonPhrase)

Respond an incoming call request.


For accepting the call the iReasonCode must be 0 or sReasonPhrase empty string. For declining a custom iReasonCode with sReasonPhrase can be given, otherwise 0 as the reason code or empty string as the reason phrase should be given.

iLine:


bAccept:

True to accept, false to reject.

bConf:

True if the callee accepts to join a conference, false if the call is to be one-one.

iReasonCode:

The reason code for declining the call (ex: 415).

sReasonPhrase:

The reason for declining the call (ex: Unsupported Media Type)

For accepting or normal declining the call the iResonCode must be 0 or sReasonPhrase empty string

RespondReinvite ( iLine)

Respond upon an incoming reinvite request.

This function must be called upon receiving OnReinviteRequest event.

iLine:


This function must be called upon receiving OnReinviteRequest event.

SendSipRequestInCall(iLine, &msgType, &contentType, &content)


Send SIP request in dialog. iLine:


msgType:

The message which can be INFO or MESSAGE.

contentType:

List of content types that need to be set for each body.

content:

The list of bodies.

SendSipResponse(iLine, &sRequest, &sResponseCode, &sResponseBody)

Send SIP response in dialog. iLine:


sRequest:

The request for which response is to be sent.

sResponseCode:

The response code.

sResponseBody:

The response body.

GetSipHeader ( &sMsg, &sHeaderName, sValue)

Parse the desired sip header from sip message.returns the number of values extracted


sMsg:

The sip message from which the header will be extracted.

sHeaderName:

The name of the sip header whose value is needed to be extracted.

sValue:

A vector of string containing the desired header's values.

AddSipHeader (&sMsg, &sHeaderName, &sValue)

Add the desired sip header to a sip message.

sMsg:

The sip message from which the header will be added.

sHeaderName:

The name of the sip header whose value is needed to be added.

sValue:

A vector of string containing the desired header's values.

PutCallInConference ( iLine)

Put an ongoing call into a conference.

iLine:


SendAudioData( iLine, pRtpHeader, iRtpHeaderLength, pData, iDataLength)


Send audio data.

iLine:


PRtpHeader:

The RTP header.

iRtpHeaderLength:

Length of the RTP header.

pData:

Data

iDataLength:

The length of data

SendVideoData( iLine, pRtpHeader, iRtpHeaderLength, pData, iDataLength)

Send video data.

iLine:


PRtpHeader:

The RTP header.

iRtpHeaderLength:


pData:

Data

iDataLength:


The length of data

SendApplicationData( iLine, pRtpHeader, iRtpHeaderLength, pData, iDataLength)

Send application data in application sharing call.

iLine:


PRtpHeader:

The RTP header.

iRtpHeaderLength:


pData:

Data

iDataLength:

The length of data

SetAudioCallback ( iLine, pHandler)

Set callback for audio data.

iLine:


pHandler:

HandleAudioCallback method is fired when audio data is available, application must implement this method to handle received audio data.


SetVideoCallback ( iLine, pHandler)

Set callback for video data.

iLine:


pHandler:

HandleVideoCallback method is fired when video data is available, application must implement this method to handle received video data.


4.1.8 Eyeball's Bandwidth estimation and Lync standard bandwidth management

MsSipLibrary uses the Microsoft specified bandwidth estimation technique and also integrated an Eyeball's statistical bandwidth estimation method with it, which ensures better voice and video quality.

EnableBandwidthManagement ( bEnableBWM)

Enable or disable bandwidth management.

bEnableBWM:

True to enable, false to disable.

SetBandwidthForMedia (iMedia, iMin, iMax)

Set the bandwidth for a media channel.

iMedia:

0 for audio, 1 for video, 2 for appshare.

iMin:

Minimum bandwidth.

iMax:


Maximum bandwidth.

StartBandwidthEstimationForRemoteUser ( iLine)

Start RTCP packet train for bandwidth estimation between the pair.

iLine:


SendModalitySendBandwidthLimit (iLine, iBandwidthLimit)

Send Modality Send Bandwidth Limit in RTCP iLine:


iBandwidthLimit:

The maximum outbound bandwidth in bits per second available for the specified modality type.

Modality is for video only.

SendPolicyServerBandwidthProfile (iLine, iMedia, iBandwidthPolicyProfile)

Send Policy server bandwidth policy profile for the media in RTCP.

iLine:


iMedia:



iBandwidthPolicyProfile:

The max bandwidth supported by policy server for this media.

SendTURNServerSupportedBandwidth ( iLine, iMedia, iMaxBandwidth)

Send TURN server max supported bandwidth for the media in RTCP. iLine:


iMedia:


iMaxBandwidth:

The max bandwidth supported by TURN for this media.


4.1.9 HD video negotiation and other microsoft profile specific extension feature

In an ongoing call the video resolution of a remote peer can be changed through the MsSipLibrary.

Microsoft's other profile specific extension like picture loss indication, packet loss notification, network congestion, video source request, audio healer matrix, etc are also available and accessible through the following APIs.

SendVideoResolutionPreference (iLine, iWidth, iHeight, iBitRate, iFrameRate)

Send preferred video resolution to remote client for a video call in RTCP.

iLine:


iWIdth:

The preferred width in pixel for video.

iHeight:

The preferred height in pixel for video.

iBitRare:

Unused.

iFrameRate:


Unused.

SendPacketLossNotification ( iLine, iPacketNumber)

Send packet loss notification to remote client if the packet loss occurred in RTCP.

iLine:


iPacketNumber:

The sequence number of the packet.

SendNetworkCongestionNotification ( iLine)

Send network congestion information to remote client in RTCP iLine:


SendRTCPVideoSourceRequest( iLine, iPayloadType, iUCConfigMode, iFlags, iAspectRatioBitMask, iMaximumWidth, iMaximumHeight, uiMinimumBitRate, uiReserve, uiBitratePerLevel, usiaBitRateHistogram, uiFrameRateBitMask, iNumberofMUSTInstances, iNumberofMAYInstances, usiaQualityReportHistogram, uiMaximumNumberofPixels)

Send RTCP Video Source Request in RTCP iLine:



iPayloadType:

Is the media Payload Type

iUCConfigMode:

Is the UC configuration Mode

iFlags:

Flags for VSR .

iAspectRatioBitMask:

Is the bit mask of aspect ratio of video source.

iMaximumWidth:

Maximum width of video.

iMaximumHeight:

Maximum height of video

uiMinimumBitRate:

Minimum bitrate of video

uiReserve:

Reserve

uiBitratePerLevel:

Bitrate per level for video

usiaBitRateHistogram:

pointer of BitRateHistogram array of length 10.

uiFrameRateBitMask:

Bit mask of frame rate.

iNumberofMUSTInstances:


Number of MUST instances of video source.

iNumberofMAYInstances:

Number of MAY instances of video source.

usiaQualityReportHistogram:

Quality report histogram array of length 8.

uiMaximumNumberofPixels:

Vector of maximum number of pixels.

SendRTCPGoodBye( iLine, iMedia)

Send RTCP Goodbye iLine:


iMedia:


SendDominantSpeaker ( iLine)

Send dominant speaker in RTCP.

iLine:


SendDominantSpeakerHistory( iLine)

Send dominant speaker history in RTCP.


iLine:


SendReceiverReport( iLine)

Send Receiver Report for a Line with RTCP.

iLine:


SendPictureLossIndication (iLine, iRequestId, iSFR[]) Send picture loss indication.

iLine:


iRequestId:

Uniquely identifies the PLI.

iSFR[]:

The integer array list of Sync frame request of length.

SendAudioHealerMetrics(iLine, iConcealedFrames, iStretchedFrames, iCompressedFrames, iTotalFrames, iReceiveQualityState, iFECdistanceRequest)

Send audio healer metrics.

iLine:


The line number for which the video capabilities will be set.

iConcealedFrames:

The total number of concealed audio frames that have been generated during the call.

iStretchedFrames:

The total number of stretched frames that have been generated during the call.

iCompressedFrames:

The total number of compressed frames that have been generated during the call.

iTotalFrames:

The total number of frames that have been generated during the call.

iReceiveQualityState:

The received audio quality so far in the call.

iFECdistanceRequest:

The the FEC distance requested by the receiver from the sender.

SetTrustedAppDomainCertificate(

int iApplicationAccount,

const std::string &sCertificatePath);


4.2 MS-SIP Notification Events

Notification Events

The following notification events are supported by the SIP Communicator.

OnSipCompressionNegotiationResponse(iAccount, bSuccess)

Fired upon reception of response for SIP compression negotiation request.

iAccount:

The account number.

bSuccess:

True if SIP compression has been enabled successfully, false otherwise

OnLoginResponse(eLoginResponse, iAccount)

Fired upon login response.

eLoginResponse:

ELoginResponseSuccess, ELoginResponseFailure, ELoginResponseTimeout, ELoginResponseAuthenticationError .


iAccount:

The account number.

OnAddTrustedApplicationEndpointComplete(iApplicationAccount, iAccount, iSuccess, isDefault)

Fired upon negotiation completion of trusted application endpoint.


The account of the trusted application.

iAccount:

The account number of the trusted application endpoint.

iSuccess:

Status of new endpoint addition.

isDefault:

True if this is an default endpoint.

OnTrustedApplicationConnectionLost(iApplicationAccount)

Fired when connection of trusted application listening port becomes INVALID.


The application account number of trusted application.

All of the added endpoint also becomes INVALID.

OnTrustedApplicationRemoveComplete(iApplicationAccount, iSuccess)


Fired when connection of trusted application listening port becomes INVALID.


The application account number of trusted application.

iSuccess:

Status of the application remove operation.

OnIncomingCall(iLine, &sCaller, bVideo, bAppShare, bIM, bConf, iAccount, iApplicationAccount, &sMsg, &sConversationId, isDefaultRouted)

Fired upon incoming call iLine:

The line at which the call request has been received.

sCaller:

Caller uri.

bVideo:

True for audio-video call, false for audio only call.

bAppShare:

True for application share call.

bIM:

True for chat session call.

bConf:

True if the call is to be put into a conference, false for 1-1 call

iAccount:

The account number.



The account of the trusted application.

sMsg:

The SIP message of the incoming call request.

sConversationId:

The conversation id.

isDefaultRouted:

TRUE if default route used.

OnSendingCallRequest(iLine, &sMsg)

Fired when INVITE message has been created and can be edited by the client application before it is sent.

iLine:

The line that will be used for the call.

sMsg:

The SIP message of the outgoing call request.

OnReinviteRequest(iLine, bVideo, &sMsg)

Fired upon reinvite request iLine:


bVideo:

True if remote user want to add video, false if he wants to remove video.


sMsg:

The SIP message of the reinvite request.

RespondReinvite() must be called upon reception of this event.

OnReinviteResponse(iLine, bVideo)

Fired upon response to reinvite request iLine:


bVideo:

True if remote user want to add video, false if he wants to remove video.

OnEndCall(iLine)

Fired upon call ending.

iLine:

The line on which call has been ended.

OnCallResponse(iLine, bResponse, bVideo, bAppShare, bIM, bConf, &sMsg)

Fired upon response to a call request.

iLine:


bResponse:

True for success, false for failure.


bVideo:

True for video, false for audio only call.

bAppShare:

True for application share call.

bIM:

True for chat session call.

bConf:

True if callee wants to be put into conference, false for 1-1 call.

sMsg:

Response for invite message

OnSDPAvailable(iLine, &sSDP)

Fired when SDP has been created and can be edited by the client application if required before sending the SIP message.

iLine:


sSDP:

The SDP which can be modified by the client application.

OnReceivedSipMessage(iAccount, iLine, &sMsg, *bHandled)

Fired when a SIP message has been received. This can be edited by the client application if required before it is processed by the library. iAccount:

The account number of the received SIP message.


iLine:

The line in which the call is going on, or -1 if the message isn’t related to a call dialog.

sMsg:

The SIP message

bHandled:

Set to TRUE if MSLib should not parse and handle the SIP message, or FALSE if MSLib should parse and handle the SIP message.

OnSendingSipMessage(iAccount, iLine, &sMsg)

Fired when a SIP message has been created and can be edited by the client application if required before it is sent.

iAccount:

The account number.

iLine:


sMsg:

The SIP message which can be modified by the client application.

OnLogoutComplete( iAccount)

Fired upon logout process completion.

iAccount:

The Account number.

OnConnectionLost( iAccount)


Fired upon connection to SIP server gets lost.

iAccount:

The Account number.

OnReceivedReceiverReportForRemoteUser(iLine, uiSSRC, fractionLost, uiCumulativePacketsLost, uiExtendedHighestSequence, uiInterarrivalJitter, uiLastSR, uidelayLastSR)

Fired when receiver report is found.

iLine:


uiSSRC:

SSRC of source.

fractionLost:

Fraction lost .

uiCumulativePacketsLost:

Cumulative number of packets lost.

uiExtendedHighestSequence:

Extended highest sequence number received.

uiInterarrivalJitter:

Inter-arrival jitter.

uiLastSR:

Last Sender Report (LSR).

uidelayLastSR:


Delay since last Sender Report (DLSR).

OnReceivedBandwidthEstimationForRemoteUser(iLine, iEstimatedBandwidth)

Fired when bandwidth estimation between the pair is found. iLine:


iEstimatedBandwidth:

Is the remote end estimated bandwidth for use

OnSendingBandwidthEstimationToRemoteUser(iLine, *pulEstimatedBandwidth)

Fired when bandwidth estimation between the pair is computed and ready to send. iLine:


pulEstimatedBandwidth:

Is the estimated bandwidth which can be modified by the application.

OnReceivedPacketLossNotification( iLine, iPacketNumber)

Fired upon packet loss notification received

iLine:


iPacketNumber:

Is the sequence number of the packet.


OnReceivedVideoResolutionPreference( iLine, iWidth, iHeight)

Fired upon reception of preferred video resolution of remote client for a video. iLine:


iWidth:

Is the preffered width in pixel for video.

iHeight:


OnReceivedPolicyServerBandwidthProfile(iLine,iMedia, iBandwidthPolicyProfile)

Fired upon reception of Policy server's bandwidth policy profile. iLine:


iMedia:


iBandwidthPolicyProfile:

Is the max bandwidth supported by policy server for this media.

OnReceivedTURNServerSupportedBandwidth(iLine,iMedia, iMaxBandwidth)

Fired upon reception of TURN server max supported bandwidth.


iLine:


iMedia:


iMaxBandwidth:

Is the max bandwidth supported by TURN for this media.

OnReceivedNetworkCongestionNotification(iLine, iCongestionState)

Fired upon reception of network congestion info. iLine:


iCongestionState:

Is the network state.

OnReceivedModalitySendBandwidthLimit(iLine, iBandwidthLimit)

Fired upon reception of Modality Send Bandwidth Limit.

iLine:


iBandwidthLimit:

the maximum outbound bandwidth in bits per second available for the specified modality type.

Only supported modality video.


OnRTCPVideoSourceRequest(iLine, iNumberofEntries, viPayloadType, viUCConfigMode, viFlags, viAspectRatioBitMask, viMaximumWidth,viMaximumHeight, vuiMinimumBitRate, vuiReserve, vuiBitratePerLevel, vusiaBitRateHistogram, vuiFrameRateBitMask, viNumberofMUSTInstances, viNumberofMAYInstances, vusiaQualityReportHistogram, vuiMaximumNumberofPixels)

Fired upon reception of RTCP Video Source Request.

iLine:


iNumberofEntries:

Number of entries.

viPayloadType:

Vector of PayloadType.

viUCConfigMode:

Vector of UCConfigMode.

viFlags:

Vector of Flags.

viAspectRatioBitMask:

Vector of AspectRatioBitMask.

viMaximumWidth:

Vector of MaximumWidth.

viMaximumHeight:

Vector of MaximumHeight.


vuiMinimumBitRate:

Vector of MinimumBitRate.

vuiReserve:

Vector of Reserve.

vuiBitratePerLevel:

Vector of BitratePerLevel.

vusiaBitRateHistogram:

pointer vector of BitRateHistogram array.

vuiFrameRateBitMask:

Vector of FrameRateBitMask.

viNumberofMUSTInstances:

Vector of NumberofMUSTInstances.

viNumberofMAYInstances:

Vector of NumberofMAYInstances.

vusiaQualityReportHistogram:

Vector of QualityReportHistogram array.

vuiMaximumNumberofPixels:

Vector of MaximumNumberofPixels.

OnReceivedRTCPGoodByeRequest(iLine, iMediaType)

Fired upon reception of RTCP GoodBye request

iLine:



iMedia:

Type of media. 0 for Audio , 1 for Video and 2 for appshare.

OnReceivedDominantSpeaker(iLine, &sUser)

Fired upon reception of dominant speakers.

iLine:


sUser:

The dominant speaker.

OnReceivedDominantSpeakerHistory(iLine, sDominantSpeakerHist)

Fired upon reception of dominant speaker history.

iLine:


sDominantSpeakerHist:

Is the list of Dominant speaker Ascending order separated by space

OnReceivedPictureLossIndication(iLine, iRequestId, SFR[])

Fired upon reception of picture loss indication.

iLine:


iRequestId:


That uniquely identifies the PLI

SFR[]:

Is the integer array list of Sync frame request of length 8

OnReceivedAudioHealerMetrics(iLine, iConcealedFrames, iStretchedFrames, iCompressedFrames, iTotalFrames, iReceiveQualityState, iFECdistanceRequest)

Fired upon reception of audio healer metrics.

iLine:

The line on which the info received

iConcealedFrames:

Is the total number of concealed audio frames that have been generated during the call.

iStretchedFrames:

Is the total number of stretched frames that .

iCompressedFrames:

The total number of compressed frames that have been generated during the call.

iTotalFrames:

Is the total number of frames that have been generated during the call.

iReceiveQualityState:

Is the received audio quality so far in the call.

iFECdistanceRequest:

Is the FEC distance requested by the receiver from the sender.


OnCategoryDataChanged( iAccount, &vUri, &vCategoryName, &vCategoryValue )

Fired upon change in remote buddies' category data.

iAccount:

The account number.

vUri:

List of sip Uri of whose category data changed

vCategoryName:

List of category name

vCategoryValue:

List of category value.

vCategoryValue contains sequential category value according to vCategoryName.

OnSubscriberAdded( iAccount, &vSubscriber)

Fired upon change in remote buddies' category data.

iAccount:

The account number.

vSubscriber:

List of new subscriber URIs

OnUpdateContactList( iAccount)

Fired when the contact list in available for the logged in user


iAccount:

The account number.

OnUpdateSubscriberList( iAccount)

Fired when the subscriber list (the remote users who have subscribed for the logged in user) in available for the logged in user iAccount:

The account number.

GetSubscriberList() should be called after receiving this event to get the list of subscribers

OnReceivedChatMessage( iLine, &sContentType, &sMessage)

Fired upon incoming chat message received.

iLine:

The line on which the chat message received.

sContentType:

The content type of received chat message.

sMessage:

The content of the received chat message.

OnReceivedApplicationData(iLine, *pRtpHeader, *pData, iLen, iCSRCCount)

Fired upon incoming application data received in application share session. iLine:

The line on which the share is going on.


pRtpHeader:

the RTP header

pData:

The data

iLen:

Length of the data

iCSRCCount:

Number of CSRC

Length of the RTP header would be (12 + iCSRCCount * 4)

OnUpdateCallStatus( iLine, bHold)

Fired when call is held/resumed iLine:


bHold:

True if call is held, false if it's resumed

HandleAudioCallback( iLine, *pRtpHeader, *pData, iLen, iCSRCCount)

Fired when data is received on the audio RTP channel iLine:


pRtpHeader:

the RTP header


pData:

The data

iLen:

Length of the data

iCSRCCount:

Number of CSRC


HandleVideoCallback( iLine, *pRtpHeader, *pData, iLen, iCSRCCount)

Fired when data is received on the video RTP channel iLine:


pRtpHeader:

the RTP header

pData:

The data

iLen:

Length of the data

iCSRCCount:

Number of CSRC



5. Legal and Contact Information

Legal and Contact Information


Confidential Information: This document contains confidential and proprietary information. The document has been provided to you in your capacity as a customer or evaluator of Eyeball Networks Inc.'s products. Unauthorized reproduction and distribution is prohibited unless specifically approved by Eyeball Networks Inc.

Eyeball, Eyeball.com, its logos, AnyBandwidthTM and AnyFirewall™ are trademarks of Eyeball Networks Inc. All other referenced companies and product names may or may not be trademarks of their respective owners.

For more information visit Eyeball Networks Inc. at http://www.eyeball.com.

Department E-mail

Sales [email protected]

Technical Support [email protected]

Corporate Headquarters:

730 - 1201 West Pender Street

Vancouver, BC V6E 2V2

Canada

Tel. +1 604.921.5993

Fax +1 604.921.5909

http://www.eyeball.com/

mailto:[email protected]

mailto:[email protected]

eyeball ms-sip library v10.0 developer reference guide

Software