2.2.5.2.2 Category List

A category list is a type of configuration data, as specified in section 2.2.5, that contains a list of textual labels (or categories) with associated data, such as color. Other attributes of a category include a shortcut key that can be used to apply a category, a usage counter, the last time the category was applied or used by the user, and a GUID.

If the client or server supports configuration data, as specified in section 2.2.2, it MUST store the settings that are specified in this section in a category list stream. The application MUST store the category list stream in an FAI message that is contained in the Calendar special folder.

The message MUST have the PidTagMessageClass property ([MS-OXCMSG] section 2.2.1.3) set. The value of the property MUST be "IPM.Configuration.CategoryList".

The XML document that is stored in the PidTagRoamingXmlStream property (section 2.2.2.3) MUST conform to the following XSD.

 <?xml version="1.0"?>
 <xs:schema targetNamespace="CategoryList.xsd"
            xmlns="CategoryList.xsd"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:simpleType name="colorType">
     <xs:restriction base="xs:int">
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="keyboardShortcutType">
     <xs:restriction base="xs:unsignedInt">
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="dateTimeRestrictedType">
     <xs:restriction base="xs:dateTime">
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="renameOnFirstUseType">
     <xs:restriction base="xs:int">
       <xs:enumeration value="0"/>
       <xs:enumeration value="1"/>
     </xs:restriction>
   </xs:simpleType>
  
   <xs:simpleType name="guidType">
     <xs:restriction base="xs:string">
       <xs:pattern value="^\{[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}\}$"/>
     </xs:restriction>
   </xs:simpleType>
  
   <xs:element name="categories">
     <xs:complexType>
       <xs:sequence>
         <xs:element maxOccurs="unbounded"
                     name="category">
           <xs:complexType>
             <xs:attribute name="name"
                           type="xs:string"
                           use="required" />
             <xs:attribute name="color"
                           type="colorType"
                           use="required" />
             <xs:attribute name="keyboardShortcut"
                           type="keyboardShortcutType"
                           use="required" />
             <xs:attribute name="usageCount"
                           type="xs:unsignedInt"
                           use="optional" />
             <xs:attribute name="lastTimeUsedNotes"
                           type="dateTimeRestrictedType"
                           use="optional" />
             <xs:attribute name="lastTimeUsedJournal"
                           type="dateTimeRestrictedType"
                           use="optional" />
             <xs:attribute name="lastTimeUsedContacts"
                           type="dateTimeRestrictedType"
                           use="optional" />
             <xs:attribute name="lastTimeUsedTasks"
                           type="dateTimeRestrictedType"
                           use="optional" />
             <xs:attribute name="lastTimeUsedCalendar"
                           type="dateTimeRestrictedType"
                           use="optional" />
             <xs:attribute name="lastTimeUsedMail"
                           type="dateTimeRestrictedType"
                           use="optional" />
             <xs:attribute name="lastTimeUsed"
                           type="dateTimeRestrictedType"
                           use="required" />
             <xs:attribute name="lastSessionUsed"
                           type="xs:int"
                           use="required" />
             <xs:attribute name="guid"
                           type="guidType"
                           use="required" />
             <xs:attribute name="renameOnFirstUse"
                           type="renameOnFirstUseType"
                           use="optional" />
           </xs:complexType>
         </xs:element>
       </xs:sequence>
       <xs:attribute name="default"
                     type="xs:string"
                     use="required" />
       <xs:attribute name="lastSavedSession"
                     type="xs:int"
                     use="required" />
       <xs:attribute name="lastSavedTime"
                     type="dateTimeRestrictedType"
                     use="required" />
     </xs:complexType>
     <xs:unique name="uniqueName">
       <xs:selector xpath="category" />
       <xs:field xpath="@name" />
     </xs:unique>
   </xs:element>
 </xs:schema>

colorType: A simpleType based on an integer. For possible values, see the description of the color attribute later in this section.

keyboardShortcutType: A simpleType based on an unsigned integer. For possible values, see the description of the keyboardShortcut attribute later in this section.

dateTimeRestrictedType: A simpleType based on a dateTime type as specified in [XMLSCHEMA2] section 3.2.7. Elements with this type have the following restrictions:

• The year MUST be between 1601 and 30827.

• The time 24:00:00 is not valid.

• Fractional seconds SHOULD have 3-digit precision (that is, milliseconds). The application can include additional digits. The application SHOULD<6> handle any extra digits if they are included.

• The application MUST specify the time in UTC. The application MAY append a Z for the time zone identifier. The application MUST ignore any other time zone identifier and interpret the time using UTC.

renameOnFirstUseType: A simpleType based on an integer. For possible values, see the description of the renameOnFirstUse attribute later in this section.

guidType: A simpleType based on a string. For possible values, see the description of the guid attribute later in this section.

categories: The top-level element in the XML document. This element MUST exist. The application specifies the XML namespace on this element as "CategoryList.xsd". This element MUST contain the category element.

category: This element MUST exist and contains the name, color, keyboardShortcut, usageCount, lastTimeUsedNotes, lastTimeUsedJournal, lastTimeUsedContacts, lastTimeUsedTasks, lastTimeUsedCalendar, lastTimeUsedMail, lastTimeUsed, lastSessionUsed, guid, and renameOnFirstUse attributes.

name: An attribute on the category element that describes the name of the category. A valid category name:

• MUST be unique in the category list (case insensitive).

• MUST NOT be empty.

• MUST NOT be longer than 255 characters.

• MUST NOT contain the comma character (,).

• SHOULD NOT contain the characters (;) (\x061B) (\xFE54) (\xFF1B).

It is also recommend that a category name not be in the form of the string representation of a GUID, as specified in the description of the guid attribute in this section.<7>

color: An attribute on the category element that describes the color of the category. The application SHOULD use a value from -1 to 24. If any other value is used, the application MUST interpret that value as if it were -1 (no color). The RGB values provided here are the basic colors for the category. Applications can choose to display the color category differently.

keyboardShortcut: An attribute on the category element that describes the keyboard shortcut of the category.<8> The application SHOULD use a value from 0 to 11. If any other value is used, the application MUST interpret that value as if it were 0 (no shortcut).

usageCount: An attribute on the category element. Reserved. Applications can write 0. Applications MAY<9> write the usage count and periodically apply an algorithm to reduce the usage count to facilitate creating a most frequently used list.

lastTimeUsedNotes (optional): An attribute on the category element. This attribute contains the last time the category was applied to a Note object.

lastTimeUsedJournal (optional): An attribute on the category element. This attribute contains the last time the category was applied to a Journal object.

lastTimeUsedContacts (optional): An attribute on the category element. This attribute contains the last time the category was applied to a Contact object.

lastTimeUsedTasks (optional): An attribute on the category element. This attribute contains the last time the category was applied to a Task object.

lastTimeUsedCalendar (optional): An attribute on the category element. This attribute contains the last time the category was applied to a Calendar object.

lastTimeUsedMail (optional): An attribute on the category element. This attribute contains the last time the category was applied to an E-mail object.

lastTimeUsed: An attribute on the category element. This attribute contains the last time the category was used. See section 3.1.4.2.3 for more details.

lastSessionUsed: An attribute on the category. Reserved. Applications SHOULD<10> write 0, but can write the last session that this category was applied or changed by the user.

guid: An attribute on the category element that describes a GUID that identifies the category and does not change if the user renames the category. The GUID MUST be stored in a string in the form of "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}", where X is any hexadecimal digit.

renameOnFirstUse: An attribute on the category element. If set to "1", an application SHOULD<11> prompt the user to rename the category when it is first applied to a message, as specified in section 3.1.4.7. If the user renames the category before applying it to a message, this attribute can be set to 0. If this attribute is missing, the application MUST use a default value of 0.

default: An attribute on the categories element that specifies the name of a category in the category list that is to be applied, as specified in section 3.1.4.7, if the application provides a one-click method to apply a category.

lastSavedSession: An attribute on the categories element. Reserved. Applications SHOULD write 0<12> but can choose to increment this number at every new session.

lastSavedTime: An attribute on the categories element. The value MUST be set to the time in UTC when the category list was saved.