This documentation is archived and is not being maintained.

IMessengerContactAdvanced::PresenceProperties

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 presence properties of a contact. Not scriptable.


HRESULT get_PresenceProperties(
   [out,   retval] VARIANT* pvPresenceProperties);

HRESULT put_PresenceProperties(
   [in] VARIANT pvPresenceProperties);

vPresenceProperties

A VARIANT value holding a safe array of variants. The index of the array determines the property being passed. For details about supported presence properties, see the "Remarks" section.

An HRESULT of the following values. For managed code applications, these return values are received in the form of a COMException.

S_OK

The property value is retrieved or set successfully.

E_ACCESSDENIED

The method is only available for a local contact.

E_INVALIDARG

An argument is not valid.

E_INVALIDINDEX

Returned by the set function when the index is not in the range expected.

E_NOT_LOGGED_ON

The local client is not signed in.

E_INVALIDAVAILABILITY

Returned by the set function when an invalid custom presence state is passed in the array.

E_FAIL

Setting or getting presence failed.

Use fields defined in the PRESENCE_PROPERTY enumeration type as the index of the returned property array to retrieve individual elements of the property array. When reading presence property values, a null value is returned as an element of the resultant array if the corresponding presence property value is not set.

When the contact object is the user of the application, the application can set this property to publish the following presence status:

  • Availability: Set one of the following presence properties:
    • Set the PRESENCE_PROP_MSTATE property to empty or MISTATUS_UNKNOWN.
    • Set the PRESENCE_PROP_AVAILABILITY property to one of these values.
      Available

      3000

      Busy

      6000

      Do Not Disturb

      9000

      Be Right Back

      12000

      Away

      15000

      Appear Offline

      18000

  • System-defined activity: Set the PRESENCE_PROP_MSTATE to one of the following values:
    • MISTATUS_DO_NOT_DISTURB
    • MISTATUS_ONLINE
    • MISTATUS_BUSY
    • MISTATUS_BE_RIGHT_BACK
    • MISTATUS_AWAY
  • Presence status: Set one of the following:
    • Set the PRESENCE_PROP_MSTATE to MISTATUS_UNKNOWN.
    • Set the PRESENCE_PROP_AVAILABILITY to zero if PRESENCE_PROP_MSTATE is not set.

The presence properties can be set one at a time.

Bb787249.note(en-us,office.12).gifNote:
The PRESENCE_PROP_CUSTOM_STATUS_STRING and PRESENCE_PROP_PRESENCE_NOTE cannot be set using the OC Automation API. To set these property values, Unified Communications Client API can be used.

The example code calls the GetContact method on an IMessenger interface object, communicator. The returned IMessengerContact object is cast into an IMessengerContactAdvanced object to gain access to the PresenceProperties property of the contact. An object array, a_presenceProp, is declared and filled by reading the PresenceProperties property of the advanced contact object. If a contact property enumeration is deprecated in a future release, the catch() structure prevents an exception from being raised by this code.

//Read presence properties into a string.
private void ReadContactPresence()
{
   IMessengerContactAdvanced a_contact =    (IMessengerContactAdvanced)communicator.GetContact("john@contoso.com",
                                                   "");
   if (a_contact != null)
   {
       object[] c_pres = (object[])a_contact.PresenceProperties;
       StringBuilder sb = new StringBuilder();
       try
       {
         sb.Append("availability: " + c_pres   [(int)PRESENCE_PROPERTY.PRESENCE_PROP_AVAILABILITY].ToString());
         sb.Append(Environment.NewLine);
         sb.Append("Note: " +c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_PRESENCE_NOTE].ToString());
         sb.Append(Environment.NewLine);
         sb.Append("Custom Status: " + c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_CUSTOM_STATUS_STRING]);
         sb.Append(Environment.NewLine);
         sb.Append("Device Type: " + c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_DEVICE_TYPE]);
         sb.Append(Environment.NewLine);
         sb.Append("Blocked: " + c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_IS_BLOCKED]);
         sb.Append(Environment.NewLine);
         sb.Append("OOF: " + c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_IS_OOF]);
         sb.Append(Environment.NewLine);
         sb.Append("MSTATE: " + c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_MSTATE].ToString());
         sb.Append(Environment.NewLine);
         sb.Append("Tool Tip: " + c_pres [(int)PRESENCE_PROPERTY.PRESENCE_PROP_TOOL_TIP]);
         sb.Append(Environment.NewLine);
        }
        catch (COMException ce)
        {
          Console.WriteLine("COM Exception: " + 
                             ce.ErrorCode.ToString());
        }
        catch (ArgumentException AE)
        {
          Console.WriteLine("Argument Exception:" +
                             AE.Message.ToString().Trim());
        }
        catch (IndexOutOfRangeException IE)
        { 
            Console.WriteLine("Index out of range: " +
                               IE.Message.ToString());
        }
        finally
        {
           Console.WriteLine(sb.ToString());
        }
   }
}
//The following C# code snippet shows how to set presence properties for the user herself:
private void SetMyPresence()
{
    IMessengerContactAdvanced a_contact =
 (IMessengerContactAdvanced)communicator.GetContact("jane@contoso.com",
                                                   "");
    object[] mPP = new object[8];

    // Publish availability
    mPP [(int)PRESENCE_PROPERTY.PRESENCE_PROP_AVAILABILITY] = 6500;
    a_contact.PresenceProperties = (object)mPP;

    mPP [(int)PRESENCE_PROPERTY.PRESENCE_PROP_MSTATE] =
              MISTATUS.MISTATUS_INVISIBLE; 
    a_contact.PresenceProperties = (object)mPP;

    // Reset presence status
    mPP [(int)PRESENCE_PROPERTY.PRESENCE_PROP_MSTATE] =
              MISTATUS.MISTATUS_UNKNOWN;
    // or
    mPP [(int)PRESENCE_PROPERTY.PRESENCE_PROP_AVAILABILITY] = 0;
    a_contact.PresenceProperties = (object)mPP;
}

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: