Indicates that a contact in the client's contact list has changed the friendly name. Scriptable locally for scripts not running from a Web page.

Syntax

HRESULT OnContactFriendlyNameChange(
   [in] LONG hr,
   [in] IDispatch* pMContact,
   [in] BSTR bstrPrevFriendlyName
);

Parameters

hr

[in] Success or error code as a LONG.

An error result that is not S_OK can result in all other event parameters being meaningless, null, or otherwise invalid. Always check for a successful hr before attempting to use the other event parameters.

pMContact

[in] Pointer to an IDispatch interface on the IMessengerContact object that corresponds to a contact whose friendly name has changed.

bstrPrevFriendlyName

[in] A BSTR that contains the user's previous friendly name.

Return Value

The implementer of this event handler will determine what value should be returned.

Remarks

After receiving this event, the event handler can access the new contact friendly name by reading the IMessengerContact::FriendlyName property on the contact event parameter.

The previous friendly name is permanently lost if it is not returned in the events. It can be used to qualify the code that might traverse a list or UI in a client to ensure that the old friendly name has been removed.

The friendly name is set by the client that corresponds to the remote contact. If the friendly name was changed while the local client was offline, the event is issued on sign-in.

If the user is not in the contact list, the application handling this event might not be notified of subsequent changes of the property value after the IMessengerContact instance representing the user is first created. To refresh the property value, the handler must release and recreate the IMessengerContact instance.

Example

The example code casts the generic pMContact object into an IMessengerContact object to access the properties and methods available. In this case, the FriendlyName property is read. The previous friendly name and the current friendly name are then displayed in the application console window.

Copy Code 
void communicator_OnContactFriendlyNameChange(
	 int hr, 
	 object pMContact, 
	 string bstrPrevFriendlyName)
{
	if (hr == 0)
	{
		IMessengerContact imContact = (IMessengerContact)pMContact;
		StringBuilder sb = new StringBuilder();
		sb.Append(
		 " CONTACT FRIENDLY NAME CHANGE: HRESULT-" +
		 formReturnErrors.returnComError(hr));

		sb.Append(
		 " New Contact Name:" +
		 imContact.FriendlyName);

		sb.Append(
		 " Old Contact Name:" +
		 bstrPrevFriendlyName);

		Console.WriteLine(
			 "EVENT: " +
			 sb.ToString());

	 myContactList.updateContactStatus(
					 imContact,
					 imContact.Status);
}
}

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