Retrieves the connection status of the contact associated with the IMessengerContact object. Scriptable.
Syntax
HRESULT Status( [out, retval] MISTATUS* pMstate ); |
Parameters
- 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.
Return Value
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.
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 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.
Example
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.
Copy Code | |
---|---|
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()); } |
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