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 invitations is still sent to the specified URIs, but they ultimately fail.

Example

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

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

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