Share via


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.

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:

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