Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Eyeball MS-SIP Library V10.0 Developer Reference Guide

2,719 views

Published on

MS-SIP Library enables application developers to integrate Microsoft Lync presence, instant messaging, voice, video, and web conferencing into endpoints, servers, gateways, and services.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Eyeball MS-SIP Library V10.0 Developer Reference Guide

  1. 1. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Eyeball MSSIPLibrary v10.0 Developer Reference Guide Last Modified: October 2014 Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved.
  2. 2. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  3. 3. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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)
  4. 4. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  5. 5. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  6. 6. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 3. Using Eyeball MS-SIP Library
  7. 7. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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();
  8. 8. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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);
  9. 9. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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()); }
  10. 10. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  11. 11. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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:
  12. 12. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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)
  13. 13. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  14. 14. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  15. 15. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 making 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)
  16. 16. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Add the default and other additional endpoint to the related trusted application account. iAcccount: The account number provided by application (must be >= 0). iApplicationAccount: Is the trusted application account number. 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(iApplicationAcco unt, &sApplicationId, iListeningPort, &sApplicationGRUU, &sSipProxyAddress, iSipPort, &sApplicationDomain) Start trusted application negotiation with Lync server for provisioning. iApplicationAccount: 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:
  17. 17. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Domain of the created trusted application. RemoveTrustedApplication(iApplicationAccount) Remove trusted application with all of its endpoint. iApplicationAccount: Is the trusted application account number.
  18. 18. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  19. 19. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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)
  20. 20. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  21. 21. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  22. 22. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  23. 23. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 particular 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.
  24. 24. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  25. 25. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  26. 26. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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:
  27. 27. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. bUnused: Reserved. bVideo: True to add video, false to remove video. RespondCall ( iLine, bAccept, bConf, iReasonCode, &sReasonPhrase) Respond an incoming call request.
  28. 28. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. 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: The line on which the call is going on. This function must be called upon receiving OnReinviteRequest event. SendSipRequestInCall(iLine, &msgType, &contentType, &content)
  29. 29. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Send SIP request in dialog. iLine: The line on which the call is going on. 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: The line on which the call is going on. 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
  30. 30. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. SendAudioData( iLine, pRtpHeader, iRtpHeaderLength, pData, iDataLength)
  31. 31. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Send audio data. iLine: The line on which the call is going on. 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: The line on which the call is going on. PRtpHeader: The RTP header. iRtpHeaderLength: Length of the RTP header. pData: Data iDataLength:
  32. 32. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. The length of data SendApplicationData( iLine, pRtpHeader, iRtpHeaderLength, pData, iDataLength) Send application data in application sharing call. iLine: The line on which the call is going on. PRtpHeader: The RTP header. iRtpHeaderLength: Length of the RTP header. pData: Data iDataLength: The length of data SetAudioCallback ( iLine, pHandler) Set callback for audio data. iLine: The line on which the call is going on. pHandler: HandleAudioCallback method is fired when audio data is available, application must implement this method to handle received audio data.
  33. 33. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. SetVideoCallback ( iLine, pHandler) Set callback for video data. iLine: The line on which the call is going on. pHandler: HandleVideoCallback method is fired when video data is available, application must implement this method to handle received video data.
  34. 34. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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:
  35. 35. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Maximum bandwidth. StartBandwidthEstimationForRemoteUser ( iLine) Start RTCP packet train for bandwidth estimation between the pair. iLine: The line on which the call is going on. SendModalitySendBandwidthLimit (iLine, iBandwidthLimit) Send Modality Send Bandwidth Limit in RTCP iLine: The line on which the call is going on. 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: The line on which the call is going on. iMedia:
  36. 36. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 0 for audio, 1 for video, 2 for appshare. 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: The line on which the call is going on. iMedia: 0 for audio, 1 for video, 2 for appshare. iMaxBandwidth: The max bandwidth supported by TURN for this media.
  37. 37. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. iWIdth: The preferred width in pixel for video. iHeight: The preferred height in pixel for video. iBitRare: Unused. iFrameRate:
  38. 38. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Unused. SendPacketLossNotification ( iLine, iPacketNumber) Send packet loss notification to remote client if the packet loss occurred in RTCP. iLine: The line on which the call is going on. iPacketNumber: The sequence number of the packet. SendNetworkCongestionNotification ( iLine) Send network congestion information to remote client in RTCP iLine: The line on which the call is going on. SendRTCPVideoSourceRequest( iLine, iPayloadType, iUCConfigMode, iFlags, iAspectRatioBit Mask, iMaximumWidth, iMaximumHeight, uiMinimumB itRate, uiReserve, uiBitratePerLevel, usiaBitRateHisto gram, uiFrameRateBitMask, iNumberofMUSTInstances , iNumberofMAYInstances, usiaQualityReportHistogra m, uiMaximumNumberofPixels) Send RTCP Video Source Request in RTCP iLine:
  39. 39. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. The line on which the call is going on. 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:
  40. 40. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. iMedia: 0 for audio, 1 for video, 2 for appshare. SendDominantSpeaker ( iLine) Send dominant speaker in RTCP. iLine: The line on which the call is going on. SendDominantSpeakerHistory( iLine) Send dominant speaker history in RTCP.
  41. 41. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. iLine: The line on which the call is going on. SendReceiverReport( iLine) Send Receiver Report for a Line with RTCP. iLine: The line on which the call is going on. SendPictureLossIndication (iLine, iRequestId, iSFR[]) Send picture loss indication. iLine: The line on which the call is going on. 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:
  42. 42. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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);
  43. 43. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 .
  44. 44. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. iAccount: The account number. OnAddTrustedApplicationEndpointComplete(iApplicat ionAccount, iAccount, iSuccess, isDefault) Fired upon negotiation completion of trusted application endpoint. iApplicationAccount: 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(iApplicationAcc ount) Fired when connection of trusted application listening port becomes INVALID. iApplicationAccount: The application account number of trusted application. All of the added endpoint also becomes INVALID. OnTrustedApplicationRemoveComplete(iApplicationA ccount, iSuccess)
  45. 45. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Fired when connection of trusted application listening port becomes INVALID. iApplicationAccount: 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.
  46. 46. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. iApplicationAccount: 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: The line on which the call is going on. bVideo: True if remote user want to add video, false if he wants to remove video.
  47. 47. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. 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: The line on which the call is going on. bResponse: True for success, false for failure.
  48. 48. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. 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.
  49. 49. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. 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)
  50. 50. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. 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:
  51. 51. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Delay since last Sender Report (DLSR). OnReceivedBandwidthEstimationForRemoteUser(iLin e, iEstimatedBandwidth) Fired when bandwidth estimation between the pair is found. iLine: The line on which the call is going on. 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: The line on which the call is going on. pulEstimatedBandwidth: Is the estimated bandwidth which can be modified by the application. OnReceivedPacketLossNotification( iLine, iPacketNumber) Fired upon packet loss notification received iLine: The line on which the call is going on. iPacketNumber: Is the sequence number of the packet.
  52. 52. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. OnReceivedVideoResolutionPreference( iLine, iWidth, iHeight) Fired upon reception of preferred video resolution of remote client for a video. iLine: The line on which the call is going on. iWidth: Is the preffered width in pixel for video. iHeight: The line on which the call is going on. OnReceivedPolicyServerBandwidthProfile(iLine,iMedi a, iBandwidthPolicyProfile) Fired upon reception of Policy server's bandwidth policy profile. iLine: The line on which the call is going on. iMedia: 0 for audio, 1 for video, 2 for appshare. iBandwidthPolicyProfile: Is the max bandwidth supported by policy server for this media. OnReceivedTURNServerSupportedBandwidth(iLine,iM edia, iMaxBandwidth) Fired upon reception of TURN server max supported bandwidth.
  53. 53. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. iLine: The line on which the call is going on. iMedia: 0 for audio, 1 for video, 2 for appshare. iMaxBandwidth: Is the max bandwidth supported by TURN for this media. OnReceivedNetworkCongestionNotification(iLine, iCongestionState) Fired upon reception of network congestion info. iLine: The line on which the call is going on. iCongestionState: Is the network state. OnReceivedModalitySendBandwidthLimit(iLine, iBandwidthLimit) Fired upon reception of Modality Send Bandwidth Limit. iLine: The line on which the call is going on. iBandwidthLimit: the maximum outbound bandwidth in bits per second available for the specified modality type. Only supported modality video.
  54. 54. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. OnRTCPVideoSourceRequest(iLine, iNumberofEntries, viPayloadType, viUCConfigMode, vi Flags, viAspectRatioBitMask, viMaximumWidth,viMaxi mumHeight, vuiMinimumBitRate, vuiReserve, vuiBitratePerLevel, vusiaBitRateHistogram, vuiFrame RateBitMask, viNumberofMUSTInstances, viNumberof MAYInstances, vusiaQualityReportHistogram, vuiMaxi mumNumberofPixels) Fired upon reception of RTCP Video Source Request. iLine: The line on which the call is going on. 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.
  55. 55. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on.
  56. 56. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. iMedia: Type of media. 0 for Audio , 1 for Video and 2 for appshare. OnReceivedDominantSpeaker(iLine, &sUser) Fired upon reception of dominant speakers. iLine: The line on which the call is going on. sUser: The dominant speaker. OnReceivedDominantSpeakerHistory(iLine, sDominantSpeakerHist) Fired upon reception of dominant speaker history. iLine: The line on which the call is going on. sDominantSpeakerHist: Is the list of Dominant speaker Ascending order separated by space OnReceivedPictureLossIndication(iLine, iRequestId, SFR[]) Fired upon reception of picture loss indication. iLine: The line on which the call is going on. iRequestId:
  57. 57. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  58. 58. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  59. 59. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  60. 60. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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: The line on which the call is going on. 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: The line on which the call is going on. pRtpHeader: the RTP header
  61. 61. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. pData: The data iLen: Length of the data iCSRCCount: Number of CSRC Length of the RTP header would be (12 + iCSRCCount * 4) HandleVideoCallback( iLine, *pRtpHeader, *pData, iLen, iCSRCCount) Fired when data is received on the video RTP channel iLine: The line on which the call 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)
  62. 62. Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 5. Legal and Contact Information Legal and Contact Information Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 sales@eyeball.com Technical Support techsupport@eyeball.com Corporate Headquarters: 730 - 1201 West Pender Street Vancouver, BC V6E 2V2 Canada Tel. +1 604.921.5993 Fax +1 604.921.5909

×