IMessenger::GetContact Method

Deprecated. Creates a MessengerContact object that can be used to call methods of the Microsoft Windows Messenger interfaces, such as IMessenger, IMessengerContact, and IMessengerContacts.

Syntax

HRESULT GetContact(      
    BSTR bstrSigninName,
    BSTR bstrServiceId,
    IDispatch **ppMContact
);

Parameters

• bstrSigninName
  [in]  A BSTR that contains the sign-in name of the remote user to create as a local MessengerContact object.
• bstrServiceId
  [in] 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] 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

Returns one of the following values:

S_OK	Success.
RPC_X_NULL_REF_POINTER	ppMContact is a NULL pointer.
E_INVALIDARG	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.
MSGR_E_USER_NOT_FOUND	A MessengerContact object for a contact who is not in the contact list.
MSGR_E_NOT_LOGGED_ON	Client is not signed in. Client must be signed in to check this value.
E_FAIL	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 IMessenger::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 .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. IMessengerContact::Status will initially return MISTATUS_UNKNOWN and IMessengerContact::FriendlyName will return the sign-in name for the .NET Messenger Service.
• The initial bstrSigninName input value will be returned for IMessengerContact::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 DMessengerEvents::OnContactListAdd event. These properties will be refreshed, if necessary, upon each local client sign-in or on a DMessengerEvents::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 DMessengerEvents::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.

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

See Also

IMessengerContacts