This documentation is archived and is not being maintained.

IMessengerContact::Status

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.

Retrieves the connection status of the contact associated with the IMessengerContact object. Scriptable.


HRESULT Status(
   [out,
   retval] MISTATUS* pMstate
);

pMstate

Pointer to the MISTATUS of the user, which can be one of the following MISTATUS constant values.

MISTATUS_BUSY

The remote client is connected to a server, but is busy (a user-selected state).

MISTATUS_OFFLINE

The remote client is not connected to a server.

MISTATUS_ONLINE

The remote client is connected to a server.

MISTATUS_BE_RIGHT_BACK

The remote client user is away from the computer for a short time (a user-selected state).

MISTATUS_IDLE

The remote client's computer has not detected mouse or keyboard input for a determined time. The user is most likely away from the computer (an automatic state). The user can select whether to transmit the idle state and idle time threshold.

MISTATUS_AWAY

The remote client user is away from the computer (a user-selected state).

MISTATUS_ON_THE_PHONE

The remote client user is on the phone (a user-selected state).

MISTATUS_OUT_TO_LUNCH

The remote client user is at lunch (a user-selected state).

MISTATUS_UNKNOWN

The state of the remote client is unknown.

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

pMstate is a null pointer.

Status information for a user is maintained by the server and must be kept synchronized in a client by checking for DMessengerEvents::OnContactStatusChange events through the event sink.

It is possible to create an MessengerContact object that represents the local client user and query it, but local client information is easier to obtain with the IMessengerService::MyStatus property.

The value of a remote client's status is reset automatically when events fire. The Messenger object receives the DMessengerEvents::OnContactStatusChange event and writes to the protected properties of the MessengerContact object that specify its state. However, client implementers must write code within a customized event handler to update any custom UI that displays user states. Because the event returns the previous status of the user before the change, the IMessengerContact::Status property should be called when each event is received so that the client can be updated.

Several other states (such as MISTATUS_LOCAL_CONNECTING_TO_SERVER) are temporary states that are valid for a local client, but are not usually passed as part of the Messenger protocol. These states are not possible values for a remote client's state.

MISTATUS_INVISIBLE is a state that can be selected by the user and appears as MISTATUS_OFFLINE to any subscribers. MISTATUS_INVISIBLE is never returned through the IMessengerContact::Status property.

All online MISTATUS results are grouped by a common factor in the constant. For more information, see MISTATUS.

The example code illustrates the method written to handle an DMessengerEvents::OnContactStatusChange event. The StringBuilder class is implemented here as the sb object. The application console displays the contact friendly name, old status, and current status. These values are read from the event arguments, pMContact and mStatus. The mStatus argument holds the old contact status while the pMContact represents the IMessengerContact interface object whose status has changed. The current status of the contact is obtained by reading the Status property of the pMContact object.

        void communicator_OnContactStatusChange(object pMContact, MISTATUS mStatus)
        {
            IMessengerContact imContact = (IMessengerContact)pMContact;
            StringBuilder sb = new StringBuilder();
            sb.Append(imContact.FriendlyName.Trim() + ": Status Changed EVENT: Old Status-" + mStatus.ToString());
            sb.Append("New Status:" + imContact.Status.ToString());
            Console.WriteLine(sb.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

Show: