IMessenger::InviteApp Method

Deprecated. Issues an invitation to a user to use a specified application.

Syntax

HRESULT InviteApp(      
    VARIANT vContact,
    BSTR bstrAppID,
    IDispatch **ppMWindow
);

Parameters

• vContact
  [in] A VARIANT that designates a particular contact. This VARIANT should be either:

  • A VT_BSTR VARIANT that contains the sign-in name of the contact.
  • A VT_DISPATCH VARIANT that contains a pointer to a MessengerContact object that has already been established for a particular contact.

• bstrAppID
  [in] The GUID in BSTR form used to register the application that the remote user is being invited to share. This corresponds to the values set in the system registry during the installation of that application.

  Important  To parse the GUID, you must include the curly braces { } on either side as part of this string. This parameter is a string, not a GUID structure, so it works in scripting.

• 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.
RPC_X_NULL_REF_POINTER	ppMWindow is a NULL pointer.
E_INVALIDARG	NULL object or an empty string given for bstrAppID. - or - vContact is NULL, 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.
S_OUTOFMEMORY	Could not allocate memory for the new string.
E_FAIL	Client was not signed in to the primary service at the time this method was called. - or - Called this method against the local client user.
E_NOTIMPL	Cannot be called from script.
MSGR_E_POLICY_RESTRICTED	Microsoft Windows Messenger 5.0 and later. The local computer or local user policy does not allow user to share applications.

Remarks

This interface is supported for contacts on Microsoft .NET Messenger Service as well as Microsoft Exchange Instant Messaging Service (IM).

If a conversation 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.

This interface issues the invitation request only. The application to be used as an invite application must be compatible with Microsoft DirectPlay. The inviting client must have the application specified in the invitation installed. The API cannot determine whether the invitee's client has the application. Acceptance of the invitation will ultimately be a requirement for the full application invite sequence to succeed.

All windows will be closed if the client signs out. If the client goes offline, the MessengerWindow objects that correspond 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. This is also enforced by the user interface (UI). Check IMessengerContact::IsSelf or do a string comparison of vContact and IMessenger::MySigninName.

To determine valid applications on the inviting client, Windows Messenger code scans the registry and checks for DirectPlay compatibility associated with the given GUID. Currently, the only application not compatible with DirectPlay that can be used for invitations is Microsoft NetMeeting. Use the Windows 95 Active Setup GUID, {44BBA842-CC51-11CF-AAFA-00AA00B6015C}, even if the client platform is Microsoft Windows NT or Windows 2000 (which normally registers a Windows NT-specific GUID for NetMeeting).

ppMWindow should be released when it is no longer needed.

Note  This method is not available for scripting languages.

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