IMessengerContact::Status Property

  • Article

Deprecated. Retrieves the connection status of the contact associated with the MessengerContact object.

Syntax

HRESULT IMessengerContact::get_Status(MISTATUS *pMstate);

Parameters

  • pMstate
    Pointer to the MISTATUS of the user. Can be one of the following MISTATUS constant values:
    MISTATUS_BUSY The remote client is connected to a server, but 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.

Return Value

Returns one of the following values: 

S_OK Success.
RPC_X_NULL_REF_POINTER pMstate is a NULL pointer.

Remarks

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 a MessengerContact object that represents the local client user and query it, but local client information is easier to obtain with IMessengerService::MyStatus.

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 user interface (UI) that displays user states. Because the event returns the previous status of the user before the change, IMessengerContact::Status should be called upon receipt of each event 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 will not be possible values for a remote client's state.

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

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

Note  This property is available for scripting languages.

Important  IMessengerContact::Status is no longer available in Windows Vista. See Windows Messenger for more information.