IMAPIFolder::SetMessageStatus

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Sets the status associated with a message (for example, whether that message is marked for deletion).

HRESULT SetMessageStatus(
  ULONG cbEntryID,
  LPENTRYID lpEntryID,
  ULONG ulNewStatus,
  ULONG ulNewStatusMask,
  ULONG FAR * lpulOldStatus
);

Parameters

  • cbEntryID
    [in] The byte count in the entry identifier pointed to by the lpEntryID parameter.

  • lpEntryID
    [in] A pointer to the entry identifier for the message whose status is set.

  • ulNewStatus
    [in] The new status to be assigned.

  • ulNewStatusMask
    [in] A bitmask of flags that is applied to the new status and indicates the flags to be set. The following flags can be set:

    • MSGSTATUS_DELMARKED
      The message has been marked for deletion.

    • MSGSTATUS_HIDDEN
      The message is not to be displayed.

    • MSGSTATUS_HIGHLIGHTED
      The message is to be displayed highlighted.

    • MSGSTATUS_REMOTE_DELETE
      The message has been marked for deletion at the remote message store without downloading to the local client.

    • MSGSTATUS_REMOTE_DOWNLOAD
      The message has been marked for downloading from the remote message store to the local client.

    • MSGSTATUS_TAGGED
      The message has been tagged for a client-defined purpose.

  • lpulOldStatus
    [out] A pointer to the previous status of the message.

Return Value

  • S_OK
    The message status was successfully set.

Remarks

The IMAPIFolder::SetMessageStatus method sets the message status to the value that is stored in its PR_MSG_STATUS (PidTagMessageStatus) property.

Notes to Implementers

How the message status bits are set, cleared, and used depends completely on your implementation, except that bits 0 through 15 are reserved and must be zero.

A remote transport provider's implementation of this method must follow the semantics described here. There are no special considerations. Clients use this method to set the MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE bits to indicate that a particular message is to be downloaded or deleted from the remote message store. A remote transport provider does not have to implement the related IMAPIFolder::GetMessageStatus method. Clients must look in the folder's contents table to determine the status of a message.

Notes to Callers

You can use the PR_MSG_STATUS property of a message to negotiate a message lockout operation with other clients. Designate a bit as the lockout bit. To determine whether the lockout bit was set, examine the previous value for message status in the lpulOldStatus parameter. Use the other bits in the ulNewStatus parameter to track message status without interfering with the lockout bit.

See Also

Reference

IMAPIFolder::GetMessageStatus

PidTagMessageStatus Canonical Property

IMAPIFolder : IMAPIContainer