AudioVideoCall

  • 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.

An AudioVideoCall object represents an SDP-based audio/video session between a local participant and a remote participant. An AudioVideoCall object cannot exist on its own and must be associated with a Conversation object.

The AudioVideoCall class handles the “audio” and “video” media types.

AudioVideoCall State Transitions – Outbound Calls

The AudioVideoCall state transitions for an outbound call are shown in the following illustration.

Dd253385.97408643-ef57-4d3f-84ee-088d8a2383e5(en-us,office.13).jpg

  1. The transition from Idle to Establishing occurs when the application calls BeginEstablish() on the call.

  2. The transition from Establishing to Establishing occurs when the application receives the first ringing notification from the remote side while the call is in the Establishing state.

  3. The transition from Establishing to Terminating occurs when BeginEstablish fails, or when the application calls BeginTerminate() on the call, or when the application calls BeginTerminate on the conversation that contains this call.

  4. The transition from Establishing to Established occurs when EndEstablish() completes successfully.

  5. The transition from Established to Transferring occurs when the application calls BeginTransfer on the call.

  6. The transition from Transferring to Established occurs when BeginTransfer is unsuccessful.

  7. The transition from Established to Terminating occurs when the application calls BeginTerminate on the call, or when the remote side terminates the call, or when the application calls BeginTerminate on the conversation that contains this call.

  8. The transition from Idle to Terminating occurs when the application calls BeginTerminate on the call, or when the application calls BeginTerminate on the conversation that contains this call.

  9. The transition from Transferring to Terminating occurs when the transfer operation completes successfully, or when the application calls BeginTerminate on the call, or when the application calls BeginTerminate on the conversation that contains this call.

  10. The transition from Terminating to Terminated occurs when EndTerminate() completes.

AudioVideoCall State Transitions – Inbound Calls

The AudioVideoCall state transitions for an inbound call are shown in the following illustration.

Dd253385.39b62dcb-fba1-4758-bf28-ab30879f8b35(en-us,office.13).jpg

  1. The transition from Incoming to Establishing occurs when the application calls BeginEstablish on the call.

  2. The transition from Establishing to Terminating occurs when the call is not accepted, or when the application calls BeginTerminate, or when the application calls BeginTerminate on the conversation that contains this call.

  3. The transition from Establishing to Established occurs when the call is accepted (when BeginAccept() returns successfully).

  4. The transition from Established to Transferring occurs when the application calls BeginTransfer() on the call.

  5. The transition from Transferring to Established occurs when BeginTransfer is unsuccessful.

  6. The transition from Established to Terminating occurs when the application calls BeginTerminate on the call, or when the remote side terminates the call, or when the application calls BeginTerminate on the conversation that contains this call.

  7. The transition from Incoming to Terminating occurs when the application calls Decline, Forward, or BeginTerminate on the call, or when the application calls BeginTerminate on the conversation that contains this call, or when the remote side cancels its call request.

  8. The transition from Transferring to Terminating occurs when the application calls BeginTerminate, or when the transfer operation completes successfully, or when the application calls BeginTerminate on the conversation that contains this call.

  9. The transition from Terminating to Terminated occurs when EndTerminate completes.

AudioVideoCall Constructors

The AudioVideoCall class has the following constructor.

// Initializes the call based on the conversation and the signaling session.
public AudioVideoCall(Conversation conversation);

AudioVideoCall Properties

The following are the public properties on the AudioVideoCall class.

// Gets or sets the default media type for this call. For an AudioVideo call, the default media type is Audio.  
public override string DefaultMediaType {get; set;}

// Gets a list of the supported media names,
// which are acceptable m-lines in an SDP offer/answer. 
// For InstantMessagingCall Message is the only supported MediaType.
public override IEnumerable<string> SupportedMediaTypes {get;}

// Gets the audio video flow associated with this call.
public AudioVideo.AudioVideoFlow Flow {get;}

AudioVideoCall Methods

The following are the public methods on the AudioVideoCall class.

// Initiates a transfer request to the remote participant to transfer
// the current call to the given transfer target in Attended or Unattended mode.
// In Unattended mode, the call is terminated as soon as the transfer request is accepted by the remote participant.
// In Attended mode, the call monitors the success/failure
// notifications from the remote regarding how the transfer is being carried out. 
// If the transfer succeeds, this call is terminated;
// otherwise, the call is not affected.
public IAsyncResult BeginTransfer(
    String targetUri,
    AsyncCallback userCallback,
    object state);

// Initiates a transfer request to the remote participant to transfer
// the current call to the given transfer target in Attended or Unattended mode.
// In Unattended mode, the call is terminated as soon as the transfer request is accepted by the remote participant.
// In Attended mode, the call monitors the success/failure
// notifications from the remote regarding how the transfer is being carried out.
// If the transfer succeeds, this call is terminated;
// otherwise, the call is not affected.
public new IAsyncResult BeginTransfer(
     String targetUri,
     CallTransferOptions callTransferOptions,
     AsyncCallback userCallback,
     object state);

// Initiates a transfer request to the remote participant
// of the current call to replace another existing call in Attended mode.
// This is a Supervised transfer since the operation involves another
// call. This method waits for success/failure notifications from the
// remote regarding how the transfer is being carried out at the remote side.
// When the transfer by the existing remote participant
// succeeds, the current call is terminated. If the transfer fails,
// the call is not affected.
// If callToReplace is passed as the instance of the call that
// initiates the transfer, this is considered a self-transfer.
public IAsyncResult BeginTransfer(
    Call callToReplace,
    AsyncCallback userCallback,
    object state);

// Initiates a transfer request to the remote participant
// of the current call to replace another existing call in Attended mode
// This is a Supervised transfer since the operation involves another
// call. This method waits for success/failure notifications from the
// remote regarding how the transfer is being carried out at the remote side.
// When the transfer by the existing remote participant
// succeeds, the current call is terminated. If the transfer fails,
// the call is not affected.
// If callToReplace is passed as the instance of the call that
// initiates the transfer, this is considered a self-transfer.
public IAsyncResult BeginTransfer(
    Call callToReplace,
    CallTransferOptions callTransferOptions
    AsyncCallback userCallback,
    object state);

// Waits for the BeginTransfer operation to complete.
    public new CallMessageData EndTransfer(IAsyncResult result);

// Forwards the call to the specified target URI with a response code 303.
// Redirect the audiovideo call to a different target. Forwarding is carried out by a proxy when supported.
    public new void Forward(String targetUri);

// Redirects the audiovideo call to a different target URI.
// This is similar to Forward(String) except that the forwarding
// is carried out by a proxy when supported.
// When forwardOptions is null, this call will be forwarded with a 303 response code.
public new void Forward(
    string targetUri,
    CallForwardOption forwardOptions);

// Sends a provisional reliable response with 183 response code.
// This method also creates an early dialog.
public IAsyncResult BeginEstablishEarlyMedia(
    AsyncCallback userCallback,
    object state);

// Sends a provisional reliable response with 183 response code.
// This method also creates an early dialog.
public IAsyncResult BeginEstablishEarlyMedia(
    CallProvisionalResponseOptions options,
    AsyncCallback userCallback,
    object state);

// Sends a provisional reliable response on the call.
// This method also creates an early dialog.
public IAsyncResult BeginEstablishEarlyMedia(
    int responseCode, 
    CallProvisionalResponseOptions options,
    AsyncCallback userCallback,
    object state);

// Completes the operation started by the BeginEstablishEarlyMedia().
public void EndEstablishEarlyMedia(IAsyncResult result);

// Sends a provisional response synchronously with optional support for early media. 
// A provisional response will always be sent on the primary signaling
// session of the call. A provisional response
// can be sent only for an incoming call, before the call is established.
public new void SendProvisionalResponse(int responseCode, CallProvisionalResponseOptions options);

AudioVideoCall Events

The following are the public events on the AudioVideoCall class.

// Raised when the current call is transferred.
public event EventHandler<AudioVideoCallTransferReceivedEventArgs> TransferReceived;

// Raised when the state of the transfer changes as notified by the remote
// participant. This event is raised when there is an outstanding Transfer
// operation initiated by the application.
public event EventHandler<TransferStateChangedEventArgs> TransferStateChanged;

// Raised when AudioVideoFlow is created. Applications can use this event to 
// register for flow-related events and optionally to set flow configuration.
// It is recommended that the application register an event handler for this event to 
// apply specific configuration settings on the flow object. Applications which wish to 
// configure the flow for the initial SDP negotiation must do so in the event handler.
public event EventHandler<AudioVideoFlowConfigurationRequestedEventArgs> AudioVideoFlowConfigurationRequested;

// Raised when the conversation for this call is changed.
public event EventHandler<ConversationChangedEventArgs> ConversationChanged; 

// Raised when the call is forwarded.
public event EventHandler<AudioVideoCallForwardedEventArgs> Forwarded;

Important

An event handler for the AudioVideoFlowConfigurationRequested event is called synchronously. A deadlock in application code can prevent the application from terminating the call or shutting down the platform.