Starts a Communicator conversation window to initiate a voice session with a particular contact, pending acceptance of the invitation. Not scriptable.

Syntax

HRESULT StartVoice(
   [in] VARIANT vContact,
   [out,
   retval] IDispatch** ppMWindow
);

Parameters

vContact

[in] A VARIANT that can take as its value either a VT_BSTR string or a VT_DISPATCH pointer to an existing IMessengerContact object. If the input value type is a string, this method creates a new MessengerContact object internally. The string should be the full sign-in name. If the input value type is a pointer to an existing MessengerContact object (should be type VT_DISPATCH), the existing object is used.

ppMWindow

[out, retval] A pointer to a pointer to the IDispatch interface on an IMessengerWindow object, which can be accessed through the IMessengerWindow interface that is used to call other automation-accessible properties, such as the IMessengerWindow::Height property, the IMessengerWindow::Width property, the IMessengerWindow::Top property, the IMessengerWindow::Left property, and the IMessengerWindow::Show method.

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_INVALIDARG

One of the following:

  • vContact is null, the wrong type, points to a null string, or points to a string that has a space as the first character.

  • vContact is a VT_BSTR that exceeded 129 characters.

  • vContact is a VT_BSTR and contains a carriage return or linefeed.

RPC_X_NULL_REF_POINTER

ppMWindow is a null pointer.

E_OUTOFMEMORY

The internal object copy failed.

MSGR_E_NOT_LOGGED_ON

The client is not signed in the primary service at the time this method is called.

E_FAIL

One of the following:

  • The message could not be initiated for some other reason.

  • Called this method against the local client user.

MSGR_E_POLICY_RESTRICTED

The local computer or local user policy does not allow users to start a voice communication.

Remarks

Calling this method invokes the initial dialog box but does not track further actions. Failure of a voice channel initiation after the initial creation of the UI returns an error to which the client and client user have to respond.

Both the sender and receiver clients must be capable of voice communication, which is potentially affected by firewalls, user preferences, routing, and so on. If no preexisting conversation window to this contact is sent, a new window is created on the local client. Voice communication can also be sent through an existing conversation window. It is not necessary to send text to initiate the voice communication exchange.

If successful, calling this method opens a new conversation window or sends an existing one to the foreground of the destination contact's computer. This might initially appear as a pop-up message on the system tray if the window is not in the foreground on the destination client. If a window is already open to a session with the user specified by vContact (and ppMWindow has not been released), no new window is displayed, no specific HRESULT is returned (returns S_OK), and the existing window instance is referenced by the IDispatch pointer in the return value.

All windows are closed if the client signs out. If the client goes offline, the MessengerWindow objects corresponding to those windows becomes dereferenced and should be released. Calling methods or properties on these objects is no longer valid.

A client cannot open a message or invitation to the local client user. This results in E_FAIL. In this case, check the IMessengerContact::IsSelf method or do a string comparison of vContact and the IMessenger::MySigninName method.

Like file transfers or invitations, voice communication requires the destination contact to accept or decline. However, there is no way to determine whether the destination contact is capable of voice communication, has accepted or declined, or is actually receiving the transmission. Because the voice communication features are integrated with a standard conversation window, the two parties can always communicate through text as a possible fallback.

Voice communication requires that both parties complete the Audio and Video Tuning Wizard to align input and output levels for audio hardware on their client computers. Calling this method on a client that has not set audio levels first displays the Audio and Video Tuning Wizard so that the user has a chance to set the levels at least once. ppMWindow should be released when it is no longer needed.

Example

The following example code instantiates an IMessengerContact object, foundContact, by calling IMessenger::GetContact. If the logged-on user attempts to start a voice conversation with himself, a COMException is raised and the voice conversation does not start. Checking the IMessengerContact::IsSelf boolean property for a false value prevents this exception.

The IMessenger::StartVoice method returns a pointer to the IDispatch interface on the IMessengerWindow object opened by the method call. The example code is using this object to display the HWND value of the IM window on the application console window.

Copy Code
IMessengerContact foundContact = communicator.GetContact("jaya@contoso.com", communicator.MyServiceId) as IMessengerContact; 	
if (foundContact != null && foundContact.IsSelf == false)
{
   try
   {
	 IMessengerWindow voiceWindow;
	 voiceWindow = (IMessengerWindow)communicator.StartVoice(foundContact);
	 Console.WriteLine("IM Window HWND: " + voiceWindow.HWND.ToString());
   }
   catch (COMException SVCE)
   {
	 Console.WriteLine(SVCE.ErrorCode.ToString());
   }
}

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