IMessenger::GetContact

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Gets an IMessengerContact object for given IMessengerContact::SigninName. Scriptable.

Syntax

HRESULT GetContact(
   [in] BSTR bstrSigninName,
   [in] BSTR bstrServiceId,
   [out,
   retval] IDispatch** ppMContact
);

Parameters

• bstrSigninName
  [in]  A BSTR that contains the sign-in name of the remote user to create as a local IMessengerContact object.

• bstrServiceId
  in] A BSTR that contains the globally unique identifier (GUID) service ID. If this parameter is not used, by passing in an empty string, the method searches the local user's contact list and not the services. The only valid service ID is the Live Communications Service ID.

• ppMContact
  [out, retval] A pointer to a pointer to the IDispatch interface on the new (or existing) IMessengerContact object. The new object can now be accessed through the IMessengerContact interface.

Return Value

Returns one of the following values. For managed code applications, these return values are received in the form of a COMException.

• S_OK
  Success.

• RPC_X_NULL_REF_POINTER
  ppMContact is a null pointer.

• E_INVALIDARG
  One of the following:

  • bstrSigninName exceeded 129 characters.
  • bstrSigninName contains spaces, a carriage return, or linefeed.
  • bstrServiceId exceeded 38 characters.
  • bstrServiceId contains spaces, a carriage return, or linefeed.

• MSGR_E_USER_NOT_FOUND
  A MessengerContact object for a contact that is not in the contact list.

• MSGR_E_NOT_LOGGED_ON
  The client is not signed in. It must be signed in to check this value.

• E_FAIL
  One of the following:

  bstrSigninName is a null string.

  bstrServiceId is a null string.

Remarks

Service-specific variations in the MessengerContact object might 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.

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 the IMessenger::GetContact method is invoked more than once using the same bstrSigninName input string, the same pointer is returned each time as long as ppMContact is not released or otherwise destroyed.

If you are creating a MessengerContact object for a contact that is not in the contact list, be aware of the following considerations:

• The MessengerContact object is not 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. The IMessengerContact::Status property initially returns MISTATUS_UNKNOWN and the IMessengerContact::FriendlyName property returns the sign-in name.
• The initial bstrSigninName input value is returned for the IMessengerContact::SigninName property.
• These properties are populated initially when a DMessengerEvents::OnContactStatusChange event is received for the contact and is updated whenever there are changes with another DMessengerEvents::OnContactStatusChange event.

Creating a MessengerContact object for a user or contact that does not exist in the server-side user store initially returns S_OK. Attempting to add this unverified MessengerContact object to the contact list, however, results in a MSGR_E_USER_NOT_FOUND error on the DMessengerEvents::OnContactListAdd event.

Example

The code in the example is retrieving an IMessengerContact object by making a call to the GetContact method of the IMessenger interface. If no valid IMessengerContact object is returned because of an error, an exception is thrown to this calling code. If a valid IMessengerContact is returned, the properties of the contact are used to build a string that is displayed at the console.

IMessengerContact foundContact;
StringBuilder sb = new StringBuilder();
try
{
  foundContact = communicator.GetContact("jaya@contoso.com", communicator.MyServiceId) as IMessengerContact;
  sb.Append("Friendly Name: " + foundContact.FriendlyName.Trim());
  sb.Append(Environment.NewLine);
  sb.Append("Blocked: " + foundContact.Blocked.ToString());
  sb.Append(Environment.NewLine);
  sb.Append("Signin Name: " + foundContact.SigninName.ToString());
  sb.Append(Environment.NewLine);
  sb.Append("Status: " + foundContact.Status.ToString());
  Console.WriteLine(sb.ToString());
}
catch (COMException CE)
{
   Console.WriteLine(CE.ErrorCode.ToString());
}

Requirements

• Client
  Requires Microsoft DirectX 9.0, C Runtime libraries (msvcm80.dll) on Microsoft Windows© Vista, Microsoft Windows XP Service Pack 1 (SP1) or later, or Microsoft Windows 2000 with Service Pack 4 (SP4). Any Communicator-imposed restrictions apply. .

• Server
  Requires Microsoft Office Communications Server 2007, AV MCU (for Media Support), Media Relay (for NAT/Firewall traversal) on Microsoft Office Communications Server 2007.

• Product
  Microsoft Office Communicator 2007 Automation API

• IDL file
  Msgrua.idl

See Also

Reference

IMessengerContacts