3.1.5.6 StartCategoryScan
Synopsis:
Clients can perform update synchronization that is limited to a set of update categories by using the SyncUpdates operation. The StartCategoryScan method enables the client to obtain the preferred set of categories that the server expects as part of the SyncUpdates method parameters. It also allows the client to obtain any requested categories that are not recognized by the server.
When a client is performing limited update synchronization of a category, it MUST call the StartCategoryScan method before calling the SyncUpdates method. The client MUST NOT call this method if the "ProtocolVersion" ConfigurationProperty from the GetConfig response (section 2.2.2.2.1) is less than "3.2". This method SHOULD NOT exist on servers that return a "ProtocolVersion" less than "3.2".
Request Validation:
|
Parameter |
Validation conditions |
Error code |
|---|---|---|
|
requestedCategories |
MUST be present |
InvalidParameters |
The server SHOULD limit the number of categories being requested as an optimization.<45>
Data Processing:
The input to this method is an array of CategoryRelationship elements as specified in section 2.2.2.2.8.
The server MUST follow the rules specified below to compute the PreferredCategoryList and ErrorList:
For each CategoryRelationship element, if the server does not recognize the category identified by the CategoryId GUID, it places that CategoryID in the ErrorList. In addition, the group of CategoryRelationship elements that are identified by the same IndexOfAndGroup value is removed from the input.
For each of the remaining CategoryRelationship groups:
If the group contains one CategoryID that identifies a product category, that CategoryID is added to the PreferredCategoryList.
If the group contains two CategoryIDs, one of which identifies a product category and the other identifies an update classification category, only the CategoryID of the product category is added to the PreferredCategoryList.
All other cases are not allowed, in which case, the PreferredCategoryList is cleared of any existing entries and processing stops.
Results:
If no faults occur during this operation, the server MUST return a StartCategoryScanResponse message to the client (section 2.2.2.2.8). It MUST generate the response as follows:
StartCategoryScanResponse.preferredCategoryIds: This MUST be populated with the list of category GUIDs from the PreferredCategoryList, which is computed as specified previously.
StartCategoryScanResponse.requestedCategoryIdsInError: This MUST be populated with the category GUIDs from the ErrorList, which is computed as specified previously.