IMessenger::GetContact method
[GetContact is no longer available for use as of Windows Vista. See Windows Messenger for more information.]
Creates a MessengerContact object that can be used to call methods of the Windows Messenger interfaces, such as IMessenger, IMessengerContact, and IMessengerContacts.
Syntax
HRESULT GetContact(
[in] BSTR bstrSigninName,
[in] BSTR bstrServiceId,
[out, retval] IDispatch **ppMContact
);
Parameters
-
bstrSigninName [in]
-
Type: BSTR
A BSTR that contains the sign-in name of the remote user to create as a local MessengerContact object.
-
bstrServiceId [in]
-
Type: BSTR
A BSTR that contains the GUID service ID of the remote user being created. Clients with secondary services can potentially create MessengerContact objects for any currently supported service. If this parameter is used, the method will search the specified service for a person whose name matches bstrSigninName by calling CreateUser on the service. If this parameter is not used, by passing in an empty string, the method will search the local user's contact list and not the services.
-
ppMContact [out, retval]
-
Type: IDispatch**
A pointer to a pointer to the IDispatch interface on the new (or existing) MessengerContact object. The new object can now be accessed through the IMessengerContact interface.
Return value
Type: HRESULT
Returns one of the following values.
| Return code | Description |
|---|---|
|
Success. |
|
ppMContact is a NULL pointer. |
|
bstrSigninName exceeded 129 characters. - or - bstrSigninName contains spaces, a carriage return, or linefeed. - or - bstrServiceId exceeded 38 characters. - or - bstrServiceId contains spaces, a carriage return, or linefeed. |
|
A MessengerContact object for a contact who is not in the contact list. |
|
Client is not signed in. Client must be signed in to check this value. |
|
bstrSigninName is a NULL string. - or - bstrServiceId is a NULL string. |
Remarks
Service-specific variations in the MessengerContact object may include the initial defaults for property values in cases in which the object is created but no update is possible because the contact is offline or not in the contact list. For Microsoft .NET Messenger Service and Instant Messaging Service (IM), the behavior is identical.
ppMContact should be released when it is no longer needed. Even if you remove the MessengerContact object from all lists, the reference count does not reach zero until you release the pointer.
If GetContact is invoked more than once using the same bstrSigninName input string, the same pointer will be returned each time as long as ppMContact was not released or otherwise destroyed.
Syntax of the BSTR used to specify the sign-in name varies between services. For the Microsoft .NET Messenger Service, sign-in names are expected to contain an "at" sign (@) and a domain name. Other services have different requirements.
Creating a MessengerContact object for a contact who is not in the contact list is not well supported by the architecture and should be avoided. If you are creating a MessengerContact object for a contact who is not in the contact list, be aware of the following considerations:
- The MessengerContact object will not be fully valid initially. It is an object in the Component Object Model (COM) sense, but not a fully working object from the perspective of the properties it stores. Status will initially return MISTATUS_UNKNOWN and FriendlyName will return the sign-in name for the Microsoft .NET Messenger Service.
- The initial bstrSigninName input value will be returned for SigninName.
- The missing properties will not be filled in until the MessengerContact object is successfully added to the local client's contact list and the local client receives the OnContactListAdd event. These properties will be refreshed, if necessary, upon each local client sign-in or on a OnContactStatusChange event.
- Creating a MessengerContact object for a user or contact that does not exist in the server-side user store will initially return S_OK. Attempting to add this unverified MessengerContact object to the contact list, however, will result in a MSGR_E_USER_NOT_FOUND error on the OnContactListAdd event.
Note
The following remarks apply to scripting languages.
- This method is scriptable.
- You should not return MSGR_E_NOT_LOGGED_ON to avoid an exception.
- Clear the value returned to the user.
Requirements
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| IDL |
|
| DLL |
|