IMessenger::UnreadEmailCount Property

  • Article

Deprecated. Retrieves the current number of unread e-mail messages in the Inbox assigned to the currently signed-in client user.

Syntax

HRESULT IMessenger::get_UnreadEmailCount(MUAFOLDER mFolder, LONG *plCount);

Parameters

  • mFolder
    A value of the MUAFOLDER enumeration. Allowed values are:
    Constant Value Description
    MUAFOLDER_INBOX 0 Query the MSN Hotmail Inbox.
    MUAFOLDER_ALL_OTHER_FOLDERS 1 Not currently implemented. Do not use.
  • plCount
    A pointer to a LONG that provides the total number of unread e-mail messages in the client user's e-mail Inbox. This value is determined upon initial client sign-in. If a user accesses the Hotmail Inbox and reads those messages, an DMessengerEvents::OnUnreadEmailChange event will be issued; the client should use the value of the cUnreadEmail parameter in the event to get the new unread message count.

Return Value

For a table of MSGR_E_* constants, see MSGRConstants.

Returns one of the following values:

S_OK Success.
S_FALSE No Inbox is available. This may be the result for Microsoft .NET Messenger Service users whose sign-in names are not in the hotmail.com domain. If this is the case, plCount will be -1 to differentiate it from the following second case.

- or -

Returned for scripting only. Client not signed in.
RPC_X_NULL_REF_POINTER plCount is a NULL pointer.
E_FAIL Attempted to specify mFolder as a value other than MUAFOLDER_INBOX
MSGR_E_NOT_LOGGED_ON Returned for Microsoft Visual Basic and Microsoft Visual C++ only. Client is not signed in. Client must be signed in to check this value. If this error result is returned, plCount will be returned as -1.

Remarks

When this method is invoked on a Microsoft Exchange Instant Messaging Service (IM) client, Exchange through Microsoft Outlook will always be invoked as the mail client. Calling this method will not determine the unread e-mail count in that client or account. If a .NET Messenger Service is signed in as a primary or secondary service to the Exchange IM service, this method will return the number of unread e-mail messages from the Hotmail Inbox.

At sign-in, the Messenger client internally flags whether the .NET Messenger Service user has a Hotmail Inbox. If so, the count is determined from the Hotmail Inbox.

If the user does not have a Hotmail Inbox, no value can be returned (will return -1). For information about why not all Hotmail service users have Inboxes, see IMessenger::OpenInbox.

To use this method in Microsoft Windows Messenger, you must install an add-in component that supports e-mail integration.

Currently, this is a Hotmail Inbox. Only users with @hotmail.com sign-in names have Hotmail Inboxes; users with @passport.com sign-in names do not.

For users who are not signed in, calling this method will not return a plCount value at all (VT_EMPTY, not zero) and will not result in an error.

Note  The following remarks apply for scripting languages.

  • This property is scriptable.
  • You should not return MSGR_E_NOT_LOGGED_ON to avoid an exception.
  • Clear the value returned to the user.

Important  IMessenger::UnreadEmailCount is no longer available in Windows Vista. See Windows Messenger for more information.