IMessengerContact::Status property

Article
05/31/2018

[Status is no longer available for use as of Windows Vista. See Windows Messenger for more information.]

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

This property is read-only.

Syntax

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

Property value

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.

Error codes

Returns one of the following values.

Name	Meaning
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 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 MyStatus.

The value of a remote client's status is reset automatically when events fire. The Messenger object receives the 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, 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 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.

Examples

The following Visual Basic example shows the use of this method.

Public WithEvents MsgrUIA As MessengerAPI.Messenger
Public MsgrContact As MessengerAPI.IMessengerContact

Private Sub btnStatus_Click()
    On Error Resume Next
    Dim strSigninName As String
    Dim strServiceID As String
    'Get selected contact
    strSigninName = ListContact.SelectedItem.SubItems(2)
    strServiceID = ListContact.SelectedItem.SubItems(5)
    Set MsgrContact = Nothing
    Set MsgrContact = MsgrUIA.GetContact(strSigninName, strServiceID)
    ErrorTrap ("GetContact")    'Error handling routine
    MsgBox("Contact Status: " & Module1.StatusLookup(MsgrContact.Status))
    ErrorTrap ("Contact.Status")    'Error handling routine
End Sub

Requirements


End of client support	Windows XP
End of server support	Windows Server 2003
Header	Msgrua.h
IDL	Msgrua.idl
DLL	Msgsc.dll

Share via