Indicates the result of an attempt to add to the Messenger object's contact list. Scriptable.

Syntax

HRESULT OnContactListAdd(
   [in] LONG hr,
   [in] IDispatch* pMContact
);

Parameters

hr

[in]  Success or error code as a LONG. For a table of the MSGR_E_* constants, see Error Codes. An error result for hr might result in all other event parameters being null or otherwise invalid. Always check for a successful hr before attempting to use the other event parameters.

  • S_OK. A contact is successfully added.

  • MSGR_E_LIST_FULL. The server determined that the contact list is already at capacity. This is a server-determined limit.

  • MSGR_E_ALREADY_IN_LIST. The server determined that the user to be added is already in the contact list.

  • MSGR_E_USER_NOT_FOUND. The user specified to be added does not exist.

  • MSGR_E_UNEXPECTED. The server returned an unexpected error code.

  • MSGR_E_SERVER_TOO_BUSY. The server is not processing requests or not accepting new connections.

  • MSGR_E_SERVER_UNAVAILABLE. The server is able to be contacted, but is unavailable for unspecified reasons.

  • E_INVALIDARG. An invalid value is passed into the pMContact parameter.

pMContact

[in] Pointer to an IDispatch interface on the IMessengerContact object where a change in block value was attempted.

Return Value

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

Remarks

If you attempt to add a user who is already in a list, you receive MSGR_E_ALREADY_IN_LIST in response. If you receive a value indicating that the server is busy at the time the request is made to add the contact, use this event handler to trigger the request again. It is best to keep a counter for the number of attempts to add the contact. If the maximum number of attempts is reached (a number determined by your application), your application should stop attempting to add the contact.

Example

The example code examines the HRESULT value returned in the hr parameter. A non-zero value indicates a failure to add the contact.

If the contact is added, the 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 newly added contact displayed in the application console window.

Copy Code 
void communicator_OnContactListAdd(int hr, object pMContact)
{
  if (hr == 0) //0 is equated to S_OK
  {
	 IMessengerContact imContact = (IMessengerContact)pMContact;
	 StringBuilder sb = new StringBuilder();
	 sb.Append("CONTACT ADDED TO LIST: HRESULT-" + hr.ToString());
	 sb.Append("Contact:" + imContact.FriendlyName);
	 Console.WriteLine("EVENT: " + sb.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