IMessengerAdvanced::StartConversation

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

Starts a conversation with one or more other users using text, voice, video, or data. Not scriptable.

Syntax

HRESULT StartConversation(
   [in] CONVERSATION_TYPE ConversationType,
   [in] VARIANT vParticipants,
   [optional, in] VARIANT vContextualData,
   [optional, in] VARIANT vSubject,
   [optional, in] VARIANT vConversationIndex,
   [optional, in] VARIANT vConversationData,
   [optional, out, retval] VARIANT* pvWndHnd
);

Parameters

  • ConversationType
    A CONVERSATION_TYPE value, specifying the mode of the conversation as IM, AUDIO, VIDEO, PHONE, or PSTN. Only one mode can be specified per method call. A conversation of the VIDEO type includes audio automatically.
  • vParticipants
    A VARIANT value that can be an array of BSTR strings or IMessengerContact objects. The BSTR string must be a SIP, TEL, or SIPS URI. For example, "SIP:user@contoso.com", "TEL:123-456-7890", or "SIPS:user@contoso.com". A distribution list can be also used in the SIP or SIPS URI. Any other types of objects are ignored. When no participants are provided, a contact picker is used to prompt for the user input of participants.
  • vContextualData
    A VARIANT value for application-specific data required to start the conversation in the application's context.
  • vSubject
    A VARIANT value for the subject of the conversation, if it is provided.
  • vConversationIndex
    A VARIANT value used to provide a conversation ID shared by all participants of the conversation.
  • vConversationData
    A VARIANT value to hold a XML binary large object (BLOB) used to send data dependent on the chosen conversation type. For focus-based conference call, this parameter is used to pass in the conference URI as the content of a <ConfURI> element. For PSTN calls, the parameter contains an array of TEL URIs, as a <TelURIs> element.
  • pvWndHnd
    A pointer to a VARIANT value as the handle to the conversation window when the method returns successfully.

Return Value

Returns one of the following values. For managed code applications, these return values are received in the form of a COMException.

  • S_OK
    Success.
  • E_FAIL
    The method is called against the local user.
  • E_INVALIDARG
    An invalid argument for conversation type.
  • E_INVALIDCONVDATA
    An invalid conversation data provided in the XML blob.
  • MSGR_E_NOT_LOGGED_ON
    The user is not signed in to Communicator.
  • S_FALSE
    Could not create the conversation window.
  • E_TLSREQD
    A SIPS URI is passed to the method when the client is not in TLS mode.

Remarks

This method is not scriptable.

In a typical usage scenario, an application calls this method, specifying the conversation type, the participant list, subject, a conversation ID, and some application-specific contextual data. A conversation window is created and opened when the call returns successfully. The following table summarizes the behavior of the method by the conversation type.

  • Audio
    Opens a conversation window in the PHONE mode with the specified list of SIP, SIPS, or TEL URIs and contact objects in the roster and send a Voice over IP (VoIP) invite to all participants. MCU can be used, if necessary.
  • IM
    Opens a conversation window in the IM mode with the specified list of SIP, SIPS, or TEL URIs and contact objects in the roster.
  • Phone
    Opens a conversation window in the PHONE mode with the specified list of SIP, SIPS or TEL URIs and contact objects in the roster. TEL URI array specified in the vConversationData parameter are used to dial the specified participants as necessary.
  • PSTN
    Opens a conversation window in the PHONE mode with the specified list of SIP, SIPS, or TEL URIs and contact objects in the roster and sends a PSTN invite to all participants not identify by TEL URIs. The TEL URI array in the vConversationData parameter can be passed to instruct the Public Switched Telephone Network (PSTN) bridge to dial participants.
  • Video
    Opens a conversation window in VIDEO mode with the specified list of SIP, SIPS, or TEL URIs and contact objects in the roster and sends a VoIP plus Video INVITE message to all participants. MCU can be used, if necessary.

The method does not validate the URIs. So, if some participants are invalid, the invitation is still sent to the specified URIs, but they ultimately fail.

Example: Start an IM Conversation

Description

The following C# code snippet shows how to start an IM conversation with a group of participants as specified by an array of SIP URI strings.

Code

   object[] sipUris = { "jaya@contoso.com", "sam@contoso.com" };
   long windowHandle;

   CommunicatorAPI.IMessengerAdvanced msgrAdv = 
         communicator as CommunicatorAPI.IMessengerAdvanced;
   if (msgrAdv != null)
   {
      try
      {
         object obj = msgrAdv.StartConversation(
                    CONVERSATION_TYPE.CONVERSATION_TYPE_IM,
                    sipUris,
                    null,
                    "Testing",
                    "1",
                    null);
          windowHandle = long.Parse(obj.ToString());
       }
       catch (System.Runtime.InteropServices.COMException ex)
       {
           Console.WriteLine(string.Format("{0}", ex.Message));
       }
   }

The resultant window object is returned in a DMessengerEvents::OnIMWindowCreated event.

Example: Make a Computer-to-Phone Call

Description

The following code snippet shows how to call a PSTN phone.

Code

object[] telUri = { "tel:+12065551111" };
string data = "tel:+12065551111";
IMessengerAdvanced msgrAdv = messenger as IMessengerAdvanced;
msgrAdv.StartConversation(
       CONVERSATION_TYPE.CONVERSATION_TYPE_PHONE, 
       telUri, 
       null, 
       null, 
       null, 
       data);

Example: Make a Computer-to-Computer Call

Description

The following code snippet shows how to call computer-to-computer call.

Code

string sipUri = "sip:john@contoso.com";
IMessengerAdvanced msgrAdv = messenger as IMessengerAdvanced;
msgrAdv.StartConversation(
       CONVERSATION_TYPE.CONVERSATION_TYPE_AUDIO, 
       sipUri, 
       null, 
       null, 
       null, 
       null);

Requirements

  • Client
    Requires Microsoft DirectX 9.0, C Runtime libraries (msvcm80.dll) on Microsoft Windows© Vista, Microsoft Windows XP Service Pack 1 (SP1) or later, or Microsoft Windows 2000 with Service Pack 4 (SP4). Any Communicator-imposed restrictions apply. .
  • Server
    Requires Microsoft Office Communications Server 2007, AV MCU (for Media Support), Media Relay (for NAT/Firewall traversal) on Microsoft Office Communications Server 2007.
  • Product
    Microsoft Office Communicator 2007 Automation API
  • IDL file
    Msgrua.idl

See Also

Reference

IMessengerAdvanced
IMessengerConversationWndAdvanced::SendText