3.2.5.12.1 Behavior Common to Both Private Mailbox and Public Folder Logon

Messages that are modified receive a new change number (CN) and hence fall out of the set of read messages. The user will see these modified messages marked as unread. If the user marks a message as read, the current value of that message's PidTagChangeNumber property ([MS-OXPROPS] section 2.632) is added to the change number set (CNSET). If the user marks a message as unread, the current value of that message's PidTagChangeNumber property is removed from the CNSET.

The change number set MUST be serialized into a binary large object (BLOB) that is formatted as a serialized IDSET with REPLGUID structure, as specified in [MS-OXCFXICS] section 2.2.2.4.2. The server then returns the BLOB in the Data field of the response.

The size of the BLOB can potentially exceed the maximum amount of data that can be communicated in a single RopReadPerUserInformation response (section 2.2.1.12.2). For this reason, the RopReadPerUserInformation ROP ([MS-OXCROPS] section 2.2.3.12) is designed to stream the data to the client by having the client invoke the ROP multiple times. In other words, the client can send multiple RopReadPerUserInformation requests (section 2.2.1.12.1) to retrieve the BLOB in segments.

On each invocation of RopReadPerUserInformation, the server inspects the value of the MaxDataSize field of the RopReadPerUserInformation request because the value can be different in each request. In certain cases, the server MUST adjust the value of MaxDataSize. For more details about inspecting and adjusting the value, see the summary in this section. After the server has inspected and, if necessary, adjusted the value of MaxDataSize, the server compares the value to the size of the remaining BLOB segment. If the adjusted MaxDataSize value is less than the size of the remaining BLOB segment, then the server MUST set HasFinished field to FALSE to indicate to the client that some data remains to be retrieved.

The DataOffset field in the request contains an index into the BLOB. In other words, the value of DataOffset specifies the position within the BLOB of the first byte of data to be returned to the client. The value of DataOffset is zero in the first RopReadPerUserInformation request. The client updates DataOffset based on the number of bytes received in the previous response so that DataOffset points to the first byte of the next BLOB segment to be returned. If the value of the DataOffset field is less than zero, the server SHOULD<45> fail the operation with 0x80004005 (ecError) in the ReturnValue field. If the value of the DataOffset field is greater than the size of the next BLOB segment to be returned, the server MUST fail the operation with 0x80004005 (ecError) in the ReturnValue field.

Summary:

1. The MaxDataSize field of the request specifies the maximum number of bytes that can be returned in a single RopReadPerUserInformation response. The server MUST adjust the MaxDataSize value in certain cases, as specified in item 2 of this summary.

2. When the client retrieves a BLOB in segments, the client can set MaxDataSize to a different value in each RopReadPerUserInformation request that is used to retrieve the BLOB. Therefore, the server examines the value of MaxDataSize on each invocation of RopReadPerUserInformation as follows.

   1. The server compares the value of MaxDataSize to zero. If MaxDataSize equals 0, then the server MUST adjust the value of MaxDataSize to a suitable default value, which is determined by the implementation.<46>

   2. The server SHOULD compare the value of MaxDataSize to some suitable maximum value, as determined by the implementation. If MaxDataSize > [server's suitable maximum], then the server SHOULD adjust the value of MaxDataSize to the suitable maximum value.<47>

   3. The server compares the adjusted value of MaxDataSize to the size of the remaining BLOB segment. If [size of remaining BLOB segment] > [adjusted MaxDataSize], then the server MUST set HasFinished to FALSE to indicate to the client that additional requests are necessary to retrieve all of the remaining portions of the BLOB. The size of the remaining BLOB segment is equal to the size of the entire BLOB minus the value of DataOffset.

3. The DataSize field specifies the actual number of bytes that are returned in the response. The value of DataSize MUST NOT exceed the adjusted value of the MaxDataSize field. For details about adjusting MaxDataSize, see item number 2 of this summary. The server MUST set DataSize to the lesser of the following two values:

   1. The adjusted value of MaxDataSize.

   2. The size of the remaining BLOB segment. This is the size of the portion of the BLOB that remains to be sent to the client and is equal to the size of the entire BLOB minus the value of DataOffset.

4. The server MUST set HasFinished to TRUE if DataOffset plus DataSize equals the size of the entire BLOB. In other words, when the server sends the last segment of the BLOB, HasFinished MUST be set to TRUE.

The following specific error codes apply to this ROP. Other possible error codes are specified in [MS-OXCDATA] section 2.4.