IMessenger::StartVoice Method

Deprecated. Launches a Messenger conversation window to initiate a voice message session with a particular contact, pending acceptance of the invitation.

Syntax

HRESULT StartVoice(      
    VARIANT vContact,
    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 MessengerContact 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. For a Microsoft .NET Messenger Service contact, this should include the "@" symbol and domain 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 a MessengerWindow object, which can be accessed through the IMessengerWindow interface that is used to call other automation-accessible properties, such as IMessengerWindow::Height, IMessengerWindow::Width, IMessengerWindow::Top, IMessengerWindow::Left, and IMessengerWindow::Show.

Return Value

Returns one of the following values: 

S_OK	Success.
E_INVALIDARG	vContact is NULL, the wrong type, points to a NULL string, or points to a string that has a space as the first character. - or - vContact is a VT_BSTR that exceeded 129 characters. - or - vContact is a VT_BSTR and contains a carriage return or linefeed.
RPC_X_NULL_REF_POINTER	ppMWindow is a NULL pointer.
E_OUTOFMEMORY	Internal object copy failed.
MSGR_E_NOT_LOGGED_ON	Client was not signed in the primary service at the time this method was called.
E_FAIL	Message could not be initiated for some other reason. - or - Called this method against the local client user.
MSGR_E_POLICY_RESTRICTED	Microsoft Windows Messenger 5.0 and later. The local computer or local user policy does not allow users to start a voice communication.

Remarks

Calling this API invokes the initial dialog box but does not track further actions. Failure of a voice channel initiation after the initial creation of the user interface (UI) will return an error to which the client and client user will 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 has been 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 in order to initiate the voice communication exchange.

If successful, calling this method will either open a new conversation window or send an existing one to the foreground of the destination contact's computer. This may 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 will be referenced by the IDispatch pointer in the return value.

All windows will be closed if the client signs out. If the client goes offline, the MessengerWindow objects corresponding to those windows will become dereferenced and should be released. Calling APIs on these objects is no longer valid.

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

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 yet set audio levels will first display the Audio and Video Tuning wizard so that the user has a chance to set the levels at least once. For more information, see IMessenger::MediaWizard. It may be possible to detect whether the local client has run this wizard by checking to see if the registry keys HKEY_CURRENT_USER\Software\Microsoft\MessengerService\WaveIn Device ID and HKEY_CURRENT_USER\Software\Microsoft\MessengerService\WaveOut Device ID have been established. These key locations may vary in different operating systems.

ppMWindow should be released when it is no longer needed.

Note  This method is not available for scripting languages.

Important  IMessenger::StartVoice is no longer available in Windows Vista. See Windows Messenger for more information.

See Also

IMessenger::InstantMessage, IMessenger::InviteApp, IMessenger::SendFile