Managing Telephone Calls

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 Unified Communications Client Platform considers a public switch telephone network (PSTN) enabled telephone call to be an audio session. The PSTN audio session originates from a proxy endpoint. The session is said to be a remote call. The telephone handset used locally for the remote call is a PSTN-enabled telephone. The PSTN telephone must be connected to an organization PBX on the network.

Before a Unified Communications Client API client can manage a telephone call, it must accomplish several tasks:

• Create and initialize a platform object. The platform object is the foundation of all other Unified Communications Client API functionality. For more information, see Creating and Initializing a Platform Object.
• Create and enable an endpoint. For more information, see Create a Principal Endpoint.
• Create and initialize a proxy endpoint.
  The proxy endpoint exposes a property called SignalingCapabilities. This property allows you to determine the call control capabilities of your telephone. For more information, see Create and Enable a Proxy Endpoint.
• Create a session manager on the proxy endpoint. The session manager is the origin of all session-related events and the factory object responsible for creating a session.

Originating a Telephone Call

In Unified Communications Client API, the proxy endpoint must be created to enable a remote audio call session. The CreateProxyEndpoint method requires a reference to an instantiated SIP endpoint in the first parameter position. This is why the SIP endpoint must be created prior to creating the proxy endpoint. Managing remote phone calls using a PSTN phone involves manipulating an IUccSession object containing the controlling SIP endpoint and the controlled proxy endpoint. To make a telephone call, the application creates an IUccSession object by calling the CreateSession method on the proxy endpoint session manager. The application then creates and adds to the session a remote participant representing the called telephone. The Uri of the added participant must be formatted as a SIP telephone number. Adding the participant to the session triggers the dialing of the remote telephone number.

Programming Pattern

The following is a general programming pattern for originating a telephone call:

• If an endpoint is not instantiated, create an endpoint from the client platform using CreateEndpoint.
• Call CreateProxyEndpoint to create the required proxy endpoint for controlling the PSTN telephone.
• Advise for events on both the endpoint and proxy endpoint.
• Create an IUccSessionManager object by casting from the proxy endpoint.
• Advise for session manager events. To receive telephone calls, you must handle OnIncomingSession in your session manager event callback function.
• Create an IUccSession by calling CreateSession on the session manager. The creation of a session implicitly creates a participant representing the local user. Therefore, it is not acceptable to explicitly create a local session participant for the session in application code. If an existing remote call control session exists on the local computer, it is necessary to pass the existing session as a context property argument when creating a second session.
• Advise for session events.
• Using the session object, create a participant.
• Advise for the session participant events. A session participant can disconnect from a session without terminating a session when there are multiple active participants such as in an audio conference. A disconnecting participant raises a session participant event called OnStateChanged.
• Cast the session participant to the IUccAudioVideoSessionParticipant interface to create and add media channels to the participant.
• Call CreateChannel and specify the media type of UCC_MEDIA_TYPES.UCCMT_AUDIO.
• Add the new audio channel to the participant by calling AddChannel.
• Send the call invitation to the remote user by calling AddParticipant on the created session.
• A local PSTN speaker phone begins to broadcast the ringing tone of the call from the phone speaker. The local user can pick up the handset at that point to participate in the call session.

When a session manager is created, it can be used for all further telephone calls that are originated locally. The session manager is also used to listen for incoming sessions such as remote telephone calls.

Receiving a Telephone Call

To receive a telephone call, you must register for session manager events on the proxy endpoint instantiated. An incoming telephone call generates an OnIncomingSession event that must be accepted or rejected by the local user.

The application answers the telephone call by calling the Accept method on the IUccIncomingSessionEvent object passed in as the event parameter. Answering a telephone call amounts to accepting the incoming IUccSession invitation.

Programming Pattern

The following is a general programming pattern for accepting an incoming telephone call. The pattern is the same as that of originating a telephone call up to and including the creation of a session manager and advising for session manager events.

• In the OnIncomingSession callback function, call the Accept method on the callback function EventData parameter.
• Determine the session type (IM, audio/video, or application) by reading the Type property of the EventData.Session. If the type is UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO, the incoming session can be a telephone call. You must examine the channel media type of the incoming session participant to determine whether the session is audio only (telephone) or audio/video.
• Create a new IUccSession object from the Session property of the EventData object.
• Advise for session events on received sessions.
• Iterate on the session participant collection and cast each individual participant to the IUccAudioVideoSessionParticipant interface to gain access to participant channels. A call originated from a telephone can only contain a media channel of type UCC_MEDIA_TYPES.UCCMT_AUDIO.
• When the incoming telephone call is accepted, a UC-enabled telephone goes off-hook. The speaker and microphone are activated and the local user can participate in the call session.

The received IUccSession object can be cast to the IUccSessionCallControl object to access the advanced PBX-like operational features such as blind transfer, consultative transfer, alternate, and reconnect. Using the media channels of the remote participant, the call can be placed on hold or removed from hold.

In This Section

• Answer an Incoming Phone Call
• Make an Outgoing Phone Call

See Also

Concepts

Create an Audio Session
Invite a Participant to an Audio/Video Session
Handle Audio Session Events
End an Audio/Video Session
Displaying Video in an Audio/Video Session
Report Audio/Video Call Metrics
Providing Session Call Control