IMessenger::InviteApp method
[InviteApp is no longer available for use as of Windows Vista. See Windows Messenger for more information.]
Issues an invitation to a user to use a specified application.
Syntax
HRESULT InviteApp(
[in] VARIANT vContact,
[in] BSTR bstrAppID,
[out, retval] IDispatch **ppMWindow
);
Parameters
-
vContact [in]
-
Type: VARIANT
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]
-
Type: BSTR
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]
-
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. |
|
ppMWindow is a NULL pointer. |
|
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. |
|
Could not allocate memory for the new string. |
|
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. |
|
Cannot be called from script. |
|
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 UI. Check IsSelf or do a string comparison of vContact and 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.
Requirements
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| IDL |
|
| DLL |
|