IMessenger2::StartVideo Method

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

Syntax

HRESULT StartVideo(      
    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 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] 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 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 user interface (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 IMessengerContact::IsSelf or do a string comparison of vContact and IMessenger::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 IMessenger::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.

Important  IMessenger2::StartVideo is no longer available in Windows Vista. See Windows Messenger for more information.

See Also

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