Called by the API to notify an application that the status of the local user has changed or that a status change was attempted, and returns the current status of the local user. Scriptable.

Syntax

HRESULT OnMyStatusChange(
   [in] LONG hr,
   [in] MISTATUS mMyStatus
);

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 meaningless, null, or otherwise invalid. Always check for a successful hr before attempting to use the other event parameters.

The possible values are:

  • S_OK. The local state is successfully changed.

  • MSGR_E_DISCONNECTED. The local user signed out between attempting to change the state and receiving the event.

  • 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 contacted but is unavailable for unspecified reasons.

mMyStatus

[in] The new local state as a member of the MISTATUS enumerated state. The possible values are:

  • MISTATUS_BUSY. The local client is connected to a server and the local user is in a user-selected busy state.

  • MISTATUS_INVISIBLE. The local client is connected to a server but the local user invisible to other users. (Some services might not support this status.)

  • MISTATUS_LOCAL_CONNECTING_TO_SERVER. The local client is connecting to the server.

  • MISTATUS_LOCAL_FINDING_SERVER. The local client is attempting to find the server.

  • MISTATUS_LOCAL_DISCONNECTING_FROM_SERVER. The local client is disconnecting from the server.

  • MISTATUS_LOCAL_SYNCHRONIZING_WITH_SERVER. The local client is synchronizing with the server.

  • MISTATUS_OFFLINE. The local client is not connected to a server.

  • MISTATUS_ONLINE. The local client is connected to a server.

  • MISTATUS_BE_RIGHT_BACK. The local user has stepped away from the computer for a short time. (This is a user-selected state.)

  • MISTATUS_IDLE. The local client has not detected mouse or keyboard input on the computer for a determined time. The user is most likely away from the computer.

  • MISTATUS_AWAY. The local user is away from the computer. (This is a user-selected state.)

  • MISTATUS_ON_THE_PHONE. The local user is on the phone. (This is a user-selected state.)

  • MISTATUS_OUT_TO_LUNCH. The local user is at lunch. (This is a user-selected state.)

Return Value

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

Remarks

This event is received on invoking the API or user-driven actions that change status, such as signing in to the service. If the API or user sets the local client status to the last known state value, the DMessengerEvents::OnMyStatusChange event still fires. On sign-in to the service, client implementations should handle this event to verify that the local client is MISTATUS. Do not assume that hr=0 for the DMessengerEvents::OnSignin event indicates that the local client is successfully online. The OnSignin event signifies that the Office Communicator is handling the users' sign in request. The OnMyStatusChange event indicates the result of that sign in request.

Unlike other events, such as DMessengerEvents::OnContactStatusChange, this event returns the local users' current, not previous, status.

Each change to a local client's transitional status, such as MISTATUS, generates another DMessengerEvents::OnMyStatusChange event. The state might briefly appear to be offline when the server is being contacted and the user's list information is being synchronized or retrieved.

The MISTATUS enumeration is set up in such a way that all possible online status codes have the MISTATUS bit set. The following can be used to determine whether a user is in any of the possible online states.

Copy Code 
pContact->get_Status(&uStatus);
if (MISTATUS_ONLINE &uStatus) { // pContact is online }

Example

The example C# code displays the received local client status and displays the string value in the application console window. The code snippet uses the presence properties array of the IMessengerContactAdvanced interface to get access to the local client user's presence information. A PRESENCE_PROPERTY enumerated value is supplied as the index to the presence object. The returned value is the availability value.

Copy Code 
void communicator_OnMyStatusChange(
	 int hr, 
	 MISTATUS mMyStatus)
{
	if (hr == 0)
	{
		object[] myPresenceProperties = (object[])localClientUser.PresenceProperties;
		if (mMyStatus == MISTATUS.MISTATUS_ONLINE)
		{
			Console.WriteLine(
				 "EVENT my Status Changed - Current Status: " +
				 mMyStatus.ToString() +
				 " Availability " +
				 myPresenceProperties[(int)PRESENCE_PROPERTY.PRESENCE_PROP_AVAILABILITY].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

DMessengerEvents