IMessenger::StartVoice method
[StartVoice is no longer available for use as of Windows Vista. See Windows Messenger for more information.]
Launches a Messenger conversation window to initiate a voice message session with a particular contact, pending acceptance of the invitation.
Syntax
HRESULT StartVoice(
[in] VARIANT vContact,
[out, retval] IDispatch **ppMWindow
);
Parameters
-
vContact [in]
-
Type: VARIANT
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]
-
Type: IDispatch**
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 Height, Width, Top, Left, and Show.
Return value
Type: HRESULT
Returns one of the following values.
| Return code | Description |
|---|---|
|
Success. |
|
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. |
|
ppMWindow is a NULL pointer. |
|
Internal object copy failed. |
|
Client was not signed in the primary service at the time this method was called. |
|
Message could not be initiated for some other reason. - or - Called this method against the local client user. |
|
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 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 IsSelf or do a string comparison of vContact and 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 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.
Requirements
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| IDL |
|
| DLL |
|