DMessengerEvents::OnMyStatusChange Event

  • Article

Deprecated. Indicates that the status of the local client has changed or that a status change was attempted, and returns the current status of the local client.

Syntax

void OnMyStatusChange(      
    LONG hr,
    MISTATUS mMYStatusOE
);

Parameters

  • hr
    [in] 

    Success or error code as a LONG. For a table of the MSGR_E_* constants, see MSGRConstants.

    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.

    Possible values are as follows:

    • S_OK
      The local state was successfully changed.
    • MSGR_E_DISCONNECTED
      The client signed out between attempting to change the state and receiving the event.
    • MSGR_E_UNEXPECTED
      The server has 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 was contacted, but was unavailable for unspecified reasons.

  • mMYStatusOE
    [in] The new local state as a member of the MISTATUS enumerated state. Possible values are as follows:

    • MISTATUS_BUSY
      The local client is connected to a server and in a user-selected busy state.
    • MISTATUS_INVISIBLE
      The local client is connected to a server but is 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 client 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 client user is away from the computer. (This is a user-selected state.)
    • MISTATUS_ON_THE_PHONE
      The local client user is on the phone. (This is a user-selected state.)
    • MISTATUS_OUT_TO_LUNCH
      The local client user is at lunch. (This is a user-selected state.)

Return Value

No return value.

Event DISPID

DISPID_MUAE_ONMYSTATECHANGE

The DISPID for this event is defined in msgrua.h. Use this value to identify the event handler when implementing IDispatch::Invoke.

Remarks

This event is received upon successfully invoking IMessenger::MyStatus or through API or user-driven actions that change status, such as signing in to the service. If the API or user set the local client status to the last known state value, the DMessengerEvents::OnMyStatusChange event still fires. Upon sign-in to the service, client implementations should handle this event to verify that the local client is MISTATUS_ONLINE. Do not assume that hr=MSGR_S_OK for the DMessengerEvents::OnSignin event indicates that the local client is successfully online.

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

Each change to a local client's transitional status, such as MISTATUS_LOCAL_FINDING_SERVER, generates another DMessengerEvents::OnMyStatusChange event. The state may 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_ONLINE bit set. The following can be used to determine whether a user is in any of the possible online states:

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

Note  This event is available for scripting languages.

Important  DMessengerEvents::OnMyStatusChange is no longer available in Windows Vista. See Windows Messenger for more information.