Make an Outgoing Phone Call

  • Article

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

The essence of making an outgoing phone call is session creation, session participant creation, participant channel creation, and adding the session participant to the new session.

An outgoing call can be one of two types:

  • The user is making an outbound call where no other telephone call session exists.
  • The local user has an existing telephone call on hold and is making a second telephone call.

The programming patterns for the two call types are essentially the same with two exceptions. The following C# examples of the two call types create telephone calls of the two types, clearly illustrating the differences between the two programming patterns.

Making a Call

Making an outbound phone call amounts to the following:

  • Creating an audio session in which the local participant enables a proxy endpoint for the controlling telephone.
  • Advise for session and session participant collection events.
  • Creating a remote participant object with a TEL URI containing the call target's telephone number or the extension. If the telephone number is formatted as a GlobalPhoneNumber, the call is placed to the phone even when the phone called is not on a PBX. For example, a phone call can be placed to a user's cell phone by including the complete number formatted for a region's public switch telephone network.
  • Advise for session participant events. It is a good idea to catch the session participant collection event OnParticipantAdded and advise for session participant events here.
  • Creating a media channel on the session participant object specifying the media type of UCC_MEDIA_TYPES.UCCMT_AUDIO.
  • Advise for session participant media channel collection events (_IUccMediaChannelCollectionEvents). It is best to do this in the OnParticipantAdded event.
  • Adding the new media channel to the created session participant.
  • Adding the remote participant object to the audio session object. At this point, the called PSTN telephone begins to ring. In the event that the remote user is also a Unified Communications Client API client, an OnIncomingSession event is raised rather than ringing the telephone.

These are illustrated in the following C# code snippet.

// class declaration

/*
 * The dictionary is used here to cache all telephone sessions using
 * unique SIP as dictionary key. 
 */

private Dictionary<string, IUccSession> callSessions = new Dictionary<string, IUccSession>();
... // class code

string remoteTelUri = "sip:14055550100@contoso.com;user=phone";
protected IUccSession SessionOut = null; // class object with protected access
public void MakePhonecall(string remoteTelUri)
{
    if (remoteTelUri == string.Empty)
        return;
    //using session manager created in OnEnable callback function, create session and set session type to audio/video
    SessionOut = this.sm.CreateSession(
                      UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO,
                      null);
    //advise new session of session event handler (this)
    UCC_Advise<_IUccSessionEvents>(
                      SessionOut, 
                      this);
    //advise new session of session participant collection
    //event handler (this)
    UCC_Advise<_IUccSessionParticipantCollectionEvents>(
                      SessionOut, 
                      this);

    UccUriManager uriMgr = new UccUriManager();
    UccUri uri = uriMgr.ParseUri(remoteTelUri);

    //create a session participant using the passed SIP uri
    IUccSessionParticipant p = SessionOut.CreateParticipant(
                      uri,
                      null);


    IUccAudioVideoSessionParticipant avP = p as IUccAudioVideoSessionParticipant;
    IUccMediaChannel mc = avP.CreateChannel(
                    UCC_MEDIA_TYPES.UCCMT_AUDIO,
                    null);

    avP.AddChannel(mc);

    SessionOut.AddParticipant(
                    p,
                    null);
    //client should advise for session participant
    //events in _IUccSessionParticipantCollectionEvents.OnParticipantAdded
    //for clarity, advise is done here.
    UCC_Advise<_IUccSessionParticipantEvents>(
                      p, 
                      this);
    //advise for media channel collection events for 
    //the given session participant. This should be
    //done in _IUccSessionParticipantCollectionEvents.OnParticipantAdded
    UCC_Advise<_IUccMediaChannelCollectionEvents>(
                      avP, 
                      this);
}

After AddParticipant is called, the controlled telephone dials the specified number.

Making a Consultation Call

Making a consultation call amounts to creating a new audio/video call session and passing the existing telephone call session to the session manager in the second argument of the CreateSession method. The created context object must have a property whose key is the enumerated value UCC_PROXY_ENDPOINT_CONTEXT_EXTENSIONS.UCCPECE_PRINCIPAL_SESSION.

The client can maintain multiple remote call control sessions. Each successive session a user creates must pass the prior session in the context argument. When multiple remote call sessions exist, switching between sessions follows the normal pattern of placing a call on hold and activating a different remote call session. For information about placing an audio/video session on hold, see Holding and Transferring Sessions.

public void ConsultationPhonecall(string remoteTelUri)
{
    if (remoteTelUri == string.Empty)
        return;
    //using session manager created in OnEnable callback function, create session and set session type to audio/video
 
    //Create context object to pass existing telephone call
    //to session manager. 
    UccContext ctx = new UccContext();
    ctx.AddProperty(UCC_PROXY_ENDPOINT_CONTEXT_EXTENSIONS.UCCPECE_PRINCIPAL_SESSION, SessionOut.Session); 

    IUccSession consultCall = this.sm.CreateSession(
                      UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO,
                      ctx);
    UCC_Advise<_IUccSessionEvents>(
                      consultCall, 
                      this);
    UccUriManager uriMgr = new UccUriManager();
    UccUri uri = uriMgr.ParseUri(remoteTelUri);

    //create a session participant using the passed SIP uri
    IUccSessionParticipant p = consultCall.CreateParticipant(
                      uri,
                      null);

    UCC_Advise<_IUccSessionParticipantEvents>(
                      p, 
                      this);

    IUccAudioVideoSessionParticipant avP = p as IUccAudioVideoSessionParticipant;
    IUccMediaChannel mc = avP.CreateChannel(
                    UCC_MEDIA_TYPES.UCCMT_AUDIO,
                    null);

    avP.AddChannel(mc);

    consultCall.AddParticipant(
                    p,
                    null);
}

See Also

Concepts

Create and Enable a Proxy Endpoint
Answer an Incoming Phone Call