Skip to content

Using recon

Jump to bottom
Scott Godin edited this page Mar 5, 2021 · 1 revision

Table of Contents

Conversation Manager Methods

ConversationHandle createConversation()

Creates an empty conversation to which participants can be added.

destroyConversation(ConversationHandle)

Destroys conversation and ends all participants that solely belong to this conversation.

ParticipantHandle createRemoteParticipant(ConversationHandle, DestAddress, ContributionSetting, MediaMask, ForkSelectMode)

Creates a new remote participant in the specified conversation. This remote participant is attempted to be reached at the specified address. For SIP the address is a SIP URI. The ContributionSetting includes settings like sendonly, receive only and send/receive. MediaMask specifies which types of media we would like to accept (ie. audio/video). ForkSelectMode can be set to either automatic or manual. When ForkSelectMode is set to auto the conversation manager will automatically dispose of any related conversations that were created, due to forking. 

 Note:  The ContributionSetting and MediaMask are currently not implemented.

ParticipantHandle createMediaResourceParticipant(ConversationHandle, URL)

Creates a new media resource participant in the specified conversation. Media is played from a source specified by the url and may be a local audio file, audio file fetched via HTTP or tones. The URL can contain parameters that specify properties of the media playback, such as number of repeats. Note: We could have a version of this that does not take a conversation handle as input, the Participant must then be manually added to a conversation via addParticipant - this might be useful for long term playing, such as a music on hold source. 

 Note:  Fetching media from http source has been deprecated in the latest sipXtapi branch, and does not currently function.

Media Urls are of the following format:

  • tone:<tone></tone> - Tones can be any DTMF digit 0-9,*,#,A-D or a special tone: dialtone, busy, fastbusy, ringback, ring, backspace, callwaiting, holding, or loudfastbusy
  • file:<filepath></filepath> - If filename only, then reads from application directory (Use | instead of : for drive specifier)
  • http:<http-url></http-url> - Standard HTTP url that reference an audio file to be fetched
  • cache:<cache-name></cache-name> - You can play from a memory buffer/cache any items you have added with the addBufferToMediaResourceCache api.
 optional arguments are: [;duration=&lt;duration&gt;&lt;/duration&gt;][;local-only][;remote-only][;repeat][;prefetch]

Notes:

  • 'repeat' option only makes sense for file and http URLs
  • 'prefetch' option only makes sense for http URLs
  • audio files may be AU, WAV or RAW formats. Audiofiles should be 16bit mono, 8khz, PCM to avoid runtime conversion.
  • http referenced audio files must be WAV files, 16 or 8bit, 8Khz, Mono.
Sample mediaUrls:
  • tone:0 - play DTMF tone 0 until participant is destroyed
  • tone:*;duration=1000 - play DTMF tone 1 for 1000ms, then automatically destroy participant
  • tone:dialtone;local-only - play special tone "Dialtone" to local speaker only, until participant is destroyed
  • tone:ringback;remote-only - play special tone "Ringback" to remote participants only, until participant is destroyed
  • cache:welcomeprompt;local-only - plays a prompt from the media cache with key/name "welcomeprompt" to the local speaker only
  • file://ringback.wav;local-only - play the file ringback.wav to local speaker only, until completed (automatically destroyed) or participant is manually destroyed
  • file://ringback.wav;duration=1000 - play the file ringback.wav for 1000ms (or until completed, if shorter), then automatically destroy participant
  • file://ringback.wav;repeat - play the file ringback.wav, repeating when complete until participant is destroyed
  • file://hi.wav;repeat;duration=9000 - play the file hi.wav for 9000ms, repeating as required, then automatically destroy the participant
  • http://www.wav.com/test.wav;repeat - play the file test.wav, repeating when complete until participant is destroyed
  • http://www.wav.com/test.wav;prefetch - play the file test.wav, ensure that some audio is pre-fetched in order to assure smooth playback, until completed (automatically destroyed) or participant is manually destroyed

ParticipantHandle createLocalParticipant(SourceId, SinkId)

Creates a new local participant. A local participant is a representation of the local source (speaker) and sink (microphone). The local participant is generally only created once and is added to conversations in which the local speaker and/or microphone should be involved. The SourceId and SinkId are application specific identification tags that are used to differentiate between multiple speakers or microphones. 

 Note:  Source and Sink Id's are currently not implemented.

alertParticipant(ParticipantHandle, earlyFlag, MediaMask)

Signal to the participant that it should provide ringback. Only applicable to RemoteParticipants. For SIP this causes a 180 to be sent. The early flag indicates if we are sending early media or not. (ie. For SIP - SDP in 180). Media mask is only required if the early flag is enabled. MediaMask specifies which types of media we would like to accept (ie. audio/video). 

 Note:  The MediaMask parameter is currently not implemented.

answerParticipant(ParticipantHandle, MediaMask)

Signal to the participant that the call is answered. Only applicable to RemoteParticipants. For SIP this causes a 200 to be sent. MediaMask specifies which types of media we would like to accept (ie. audio/video). 

 Note:  The MediaMask parameter is currently not implemented.

rejectParticipant(ParticipantHandle, rejectCode)

Rejects an incoming remote participant with the specified code. Can also be used to reject an outbound participant request (due to REFER).

redirectParticipant(ParticipantHandle, Address)

Redirects the participant to another endpoint. For SIP this would either be a 302 response or would initiate blind transfer (REFER) request, depending on the state. redirectToParticipant(ParticipantHandle, DestParticipantHandle) This is used for attended transfer scenarios where both participants are no longer managed by the conversation manager – for SIP this will send a REFER with embedded Replaces header. Note: Replace option cannot be used with early dialogs in SIP.

destroyParticipant(ParticipantHandle partHandle)

Ends connections to the participant and removes it from all active conversations.

addParticipant(ConversationHandle convHandle, ParticipantHandle partHandle, ContributionSetting, MediaMask)

Adds the specified participant to the specified conversation. ContributionSetting includes settings like sendonly, receive only and send/receive. MediaMask specifies which types of media we would like to accept (ie. audio/video). 

 Note:  The ContributionSetting and MediaMask parameters are currently not implemented.

removeParticipant(ConversationHandle convHandle, ParticipantHandle partHandle)

Removes a participant from the specified conversation. The participants media to/from the conversation is stopped. If the participant no longer exists in any conversation, then they are destroyed (local participants exempt). For a remote participant this means the call will be released.

moveParticipant(ParticipantHandle, SourceConversationHandle, DestConversationHandle)

Removes participant from old conversation and adds them to the new conversation.

copyParticipant(ParticipantHandle, ConversationHandle, ContributionSetting)

Puts a participant into another conversation, leaving it in any existing conversations. The ContributionSetting includes settings like sendonly, receive only and send/receive. 

 Note:  This is currently not implemented.  This is really the same as addParticipant.

replaceParticipant(ConversationHandle, ExistingParticipantHandle, NewParticipantHandle)

Removes the existing participant from a conversation and replaces it with the new participant. For remotely mixed conversations/conferences this entails sending a REFER with embedded replaces header to the NewParticipant. For locally mixed conversations the NewParticipant is simply added to the Conversation and ExistingParticipant is removed. 

 Note:  This is currently not implemented.

joinConversation(SrcConversationHandle, DestConversationHandle)

Joins all participants from source conversation into destination conversation and destroys source conversation.

modifyParticipantContribution(ConversationHandle, ParticipantHandle, sendGain, receiveGain)

Modifies how the participant contributes to the particular conversation. The send and receive gain can be set to a number between 0 and 100. 






Conversation Manager Events








onIncomingParticipant(ParticipantHandle, ParticipantInfo)





Notifies an application about a new remote participant that is attempting to contact it.  ParticipantInfo includes information about the caller such as name, address, and other information such as whether auto-answer has been requested.



 Note:  ParticipantInfo is currently implemented as passing the entire SIP Invite message.  This should be generalized.







onRequestOutgoingParticipant(ParticipantHandle, ParticipantInfo)





Notifies an application about a new remote participant that is trying to be contacted.  This event is required to notify the application if a call request has been initiated by a signaling mechanism other than the application such as an out-of-dialog REFER request.



 Note:  ParticipantInfo is currently implemented as passing the entire SIP Invite message.  This should be generalized.







onParticipantTerminated(ParticipantHandle, Reason)





Notifies an application about a disconnect by a remote participant.  For SIP this could be a BYE or a CANCEL request.





onParticipantAlerting(ParticipantHandle)





Notifies an application that a remote participant call attempt is alerting the remote party.  





onParticipantConnected(ParticipantHandle)





Notifies an application that a remote participant call attempt is now connected.





onRelatedConversation(relatedConversationHandle, relatedParticipantHandle, origConversationHandle, origParticipantHandle)





Notifies an application that a outbound remote participant request has forked.  A new Related Conversation and Participant are created.  Both new handles and original handles are conveyed to the application so it can track related conversations.





onParticipantRedirectSuccess(ParticipantHandle)





Notifies an application that a redirect request has succeeded.  Indicates blind transfer or attended transfer status.





onParticipantRedirectFailure(ParticipantHandle, StatusCode)





Notifies an application that a redirect request has failed.  Indicates blind transfer or attended transfer status.





onDTMFEvent(ParticipantHandle, tone, duration, up?)





Notifies an application when an RFC2833 DTMF event is received from a particular participant.





onConversationDestroyed(ConversationHandle)





Notifies an application when a conversation has been destroyed.  This is useful for tracking conversations that get created when forking occurs, and are destroyed when forked call is answered or ended.





onParticipantDestroyed(ParticipantHandle)





Notifies an application when a Participant has been destroyed.  This is useful for tracking when audio playback via MediaResourceParticipants has stopped.






Use Cases







Non-mixing cases:







2-party call received






 onIncomingParticipant(part)
 conv = createConversation
 addParticipant(conv, localParticipant)
 addParticipant(conv, part)
 alertParticipant(part)
 // Phone rings
 answerParticipant(part)






2-party call initiated with early media - no forking






 conv = createConversation
 addPartcipant(conv, localParticipant)
 part = createRemoteParticipant(conv, dest)
 onParticipantAlerting(part)
 onParticipantConnected(part)






call initiated with forking






 conv1 = createConversation
 addPartcipant(conv1, localParticipant)
 part1 = createRemoteParticipant(conv1, dest, forkSelectAuto)
 onParticipantAlerting(part1)
 onRelatedConversation(conv2, part2, conv1, part1) // part2 is forked leg
 onParticipantAlerting(part2)
 onParticipantConnected(part2) // conv1 and part1 are automatically destroyed






Unattended Transfer






 // on 2-party call..
 redirectParticipant(part, dest)
 onRedirectSuccess(part)
 destroyConversation(conv)






Attended transfer






 // on 2-party call
 conv2 = createConversation // for transfer destination
 moveParticipant(localParticipant, conv1, conv2) // holds old call
 part2 = createRemoteParticipant(conv2, dest)
 onParticpantAlerting(part2)
 onParticipantConnected(part2)
 redirectToParticipant(part1, part2)
 onRedirectSuccess(part1)
 destroyConversation(conv1)
 destroyConversation(conv2)






OOD Refer Request






 // received OOD Refer Request
 onRequestOutgoingParticipant(part1)
 conv = createConversation
 addParticipant(conv, localParticipant) // signals acceptance of request and starts call
 addParticipant(conv, part1)
 onParticpantAlerting(part1)
 onParticipantConnected(part1)






Call waiting











Mixing cases:







3-way calling






 // on 2-party call
 modifyParticipantContribution // hold call
 createParticipant
 onParticpantAlerting
 onParticipantConnected
 addParticipant // add new participant to existing conversation
 modifyParticpantContribution // unhold original call






3-way join after call waiting






 // on 2-party call
 onIncomingParticpant(part2)
 alertParticipant(part2)
 mediaPart = createMediaResourceParticipant(conv1, "tone:callwaiting;local-only")
 onParticipantTerminated(mediaPart) // tone finished
 // hookflash
 addParticipant(conv1, part2) // add participant to original conversation






Barge-in






 // on 2-party call
 addParticipant






Whisper






 // on 2-party call
 addParticipant(conv1, whisperSrc, sendOnly)






Call center coaching






 // on 2-party call
 conv2 = createConversation
 addParticipant(conv2,  Supervisor)
 copyParticipant(Agent, conv1, conv2, sendRecv)  // supervisor can hear agent and vice versa
 copyParticipant(Customer, conv1, conv2, sendOnly) //  supervisor can hear customer






Small conference with out-calling, drop and mute






 // existing multiparty conversation
 createRemoteParticipant and later add to existing conversation - out-calling
 destroyParticipant // drop
 modifyParticipantContribution // mute






Larger conference with floor control






 // existing multiparty conversation
 modifyParticipantContribution is used to control who hears what (needs more thought)






Conference with internal sidebar






 // existing multiparty conversation
 createConversation // sidebar conversation
 copyParticipant(conv1, part1, conv2, sendRecv)
 modifyParticipantContribution // use this as necessary to stop copied participants from contributing audio to both conversations (needs more thought)
 // repeat for each part to be in sidebar






Conference with external sidebar






 // existing multiparty conversation
 createConversation – sidebar conversation
 copyParticipant(conv1, part1, conv2, sendRecv)
 modifyParticipantContribution // use this as necessary to stop copied participants from contributing audio to both conversations (needs more thought)
 // repeat for each part to be in sidebar
 // reach additional external participant
 addParticipant(conv2) // add external participant to sidebar conversation











Conversation Manager Threading





The following threads are present in the conversation, along with a brief description:








    

  1. SIP Stack Thread - processes SIP transport sockets and provides SIP Transaction state processing.  Also provides asynchronous DNS resolution.
    2. 

  2. Application (UserAgent) Thread - responsible for calling UserAgent::process
    3. 

  3. sipX Speaker Thread - thread to process audio data to be sent to the speaker driver
    4. 

  4. sipX Microphone Thread - thread to process audio received from the microphone driver
    5. 

  5. sipX Media Thread - thread responsible for the movement of media through the sipX filters and mixers.
    6. 

  6. sipX Network In Thread - thread responsible for reading RTP packets from the Flow Manager layer.
    7. 

  7. Flow Manager Thread - thread that implements the asio::io_service::run() loop and provides processing cycles for all sending/receiving of RTP/SRTP/DTLS-SRTP/STUN and TURN traffic to/from the network interfaces.
    8. 

  8. ASIO Utility Threads - entirely abstracted behind the Flow Manager Thread (io_service thread).  Provides OS specific asynchronous socket capabilities of the ASIO library.
    9. 



              


          



  
          

            

              

                

                  

                    


















                  

                

              


            
Clone this wiki locally