IMessenger2::StartVideo method
[StartVideo is no longer available for use as of Windows Vista. See Windows Messenger for more information.]
Launches a conversation window to initiate a video session with a particular contact, pending acceptance of the invitation.
Syntax
HRESULT StartVideo(
[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 an "at" sign (@) 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 for contact information.
-
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 video communication. |
Remarks
Calling this API invokes the initial Start a Video Conversation dialog box, but does not track further actions. Failure of a voice channel initiation after the initial UI creation will generate an error that will require a response from the client and client user.
Both the sender and receiver clients must be capable of video communication, which is potentially affected by firewalls, user preferences, routing, and so on. If no preexisting Messenger client window has been sent to this contact, a new one is created on the local client. Video communication can also be sent through an existing Messenger client window. Sending text to initiate the video communication exchange is not required.
If successful, calling this method will either open a new Messenger client window or send an existing one to the foreground on the destination contact's computer. If the Messenger client window is not in the foreground on the destination client, this may initially appear as a toast message on the system tray. If a Messenger client 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.
Note that except in rare cases where the Messenger object becomes unavailable, all MMessenger client windows will be closed if the client logs off. If the client goes offline, the MessengerWindow objects corresponding to those Messenger client windows will become dereferenced and should be released. Calling APIs on these objects is no longer valid.
A client cannot open an instant 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, video communication requires the destination contact to accept or decline. However, there is no way to determine whether the destination contact is video-capable, has accepted or declined, or is actually receiving the transmission. Because the video communication features are integrated with a standard Messenger client window, the two parties can always communicate through text as a fallback.
Video communication requires that both parties have completed 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.
To detect whether the local client has run this wizard, check to see whether 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 |
|