IMessage::SetReadFlag

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Sets or clears the MSGFLAG_READ flag in the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message and manages the sending of read reports.

HRESULT SetReadFlag(
  ULONG ulFlags
);

Parameters

  • ulFlags
    [in] Bitmask of flags that controls the setting of a message's read flag that is, the message's MSGFLAG_READ flag in its PR_MESSAGE_FLAGS property and the processing of read reports. The following flags can be set:

    • CLEAR_READ_FLAG
      The MSGFLAG_READ flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

    • CLEAR_NRN_PENDING
      The MSGFLAG_NRN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and a non-read report should not be sent.

    • CLEAR_RN_PENDING
      The MSGFLAG_RN_PENDING flag should be cleared in PR_MESSAGE_FLAGS and no read report should be sent.

    • GENERATE_RECEIPT_ONLY
      A read report should be sent if one is pending, but there should be no change in the state of the MSGFLAG_READ flag.

    • MAPI_DEFERRED_ERRORS
      Allows SetReadFlag to return successfully, possibly before the operation has completed.

    • SUPPRESS_RECEIPT
      A pending read report should be canceled if a read report had been requested and this call changes the state of the message from unread to read. If this call does not change the state of the message, the message store provider can ignore this flag.

Return Value

  • S_OK
    The message's read flag has been successfully set or cleared.

  • MAPI_E_NO_SUPPRESS
    The message store provider does not support the suppression of read reports.

  • MAPI_E_INVALID_PARAMETER
    One of the following combinations of flags is set in the ulFlags parameter:

    • SUPPRESS_RECEIPT | CLEAR_READ_FLAG

    • SUPPRESS_RECEIPT | CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

    • CLEAR_READ_FLAG | GENERATE_RECEIPT_ONLY

Remarks

The IMessage::SetReadFlag method sets or clears the message's MSGFLAG_READ flag in the PR_MESSAGE_FLAGS property and calls IMAPIProp::SaveChanges to save the message. Setting the MSGFLAG_READ flag marks a message as having been read, which does not necessarily indicate that the intended recipient has actually read the message.

SetReadFlags also manages the sending of read reports. A read report is sent only if the sender has requested one.

The read flag cannot be altered for:

  • Messages that do not exist.

  • Messages that have been moved elsewhere.

  • Messages that are open with read/write permission.

  • Messages that are currently submitted.

Notes to Callers

If none of the flags are set in the ulFlags parameter, the following rules apply:

  • If MSGFLAG_READ is already set, do nothing.

  • If MSGFLAG_READ is not set, set it and send any pending read reports if the PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested) property is set.

If both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, the PR_READ_RECEIPT_REQUESTED bit, if set, should be cleared and a read report should not be sent.

When the SUPPRESS_RECEIPT flag is set:

  • If MSGFLAG_READ is already set, do nothing.

  • If MSGFLAG_READ is not set, set it and cancel any pending read reports.

When the CLEAR_READ_FLAG flag is set, clear the MSGFLAG_READ flag in each message's PR_MESSAGE_FLAGS property and do not send any read reports.

When the GENERATE_RECEIPT_ONLY flag is set, send any pending read reports. Do not set or clear MSGFLAG_READ.

When both the SUPPRESS_RECEIPT and GENERATE_RECEIPT_ONLY flags are set, set the PR_READ_RECEIPT_REQUESTED property to FALSE if it is set and do not send a read report.

You can optimize report behavior by suppressing the generation of read reports under certain conditions. However, if you do not support the suppression of reports and a client calls SetReadFlag with the SUPPRESS_RECEIPT flag set, return MAPI_E_NO_SUPPRESS.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

FolderDlg.cpp

CFolderDlg::OnSetReadFlag

MFCMAPI uses theIMessage::SetReadFlag method to set read flags on selected messages.

See Also

Reference

IMAPIContainer::OpenEntry

IMAPIFolder::SetReadFlags

IMAPIProp::GetProps

IMAPIProp::SaveChanges

PidTagMessageFlags Canonical Property

IMessage : IMAPIProp

Concepts

MFCMAPI as a Code Sample