Export (0) Print
Expand All

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.


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

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.

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.

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.

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());
}

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

Community Additions

ADD
Show:
© 2015 Microsoft