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.
|
Value |
Base R,G,B |
Color name |
|---|---|---|
|
-1 |
255, 255,255 |
No color |
|
0 |
214, 37, 46 |
Red |
|
1 |
240, 108, 21 |
Orange |
|
2 |
255, 202, 76 |
Peach |
|
3 |
255, 254, 61 |
Yellow |
|
4 |
74, 182, 63 |
Green |
|
5 |
64, 189, 149 |
Teal |
|
6 |
133, 154, 82 |
Olive |
|
7 |
50, 103, 184 |
Blue |
|
8 |
97, 61, 180 |
Purple |
|
9 |
163, 78, 120 |
Maroon |
|
10 |
196, 204, 221 |
Steel |
|
11 |
140, 156, 189 |
Dark steel |
|
12 |
196, 196, 196 |
Gray |
|
13 |
165, 165, 165 |
Dark gray |
|
14 |
28, 28, 28 |
Black |
|
15 |
175, 30, 37 |
Dark red |
|
16 |
177, 79, 13 |
Dark orange |
|
17 |
171, 123, 5 |
Dark peach |
|
18 |
153, 148, 0 |
Dark yellow |
|
19 |
53, 121, 43 |
Dark green |
|
20 |
46, 125, 100 |
Dark teal |
|
21 |
95, 108, 58 |
Dark olive |
|
22 |
42, 81, 145 |
Dark blue |
|
23 |
80, 50, 143 |
Dark purple |
|
24 |
130, 55, 95 |
Dark maroon |
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).
|
Value |
Shortcut key |
|---|---|
|
0 |
None |
|
1 |
CTRL+F2 |
|
2 |
CTRL+F3 |
|
3 |
CTRL+F4 |
|
4 |
CTRL+F5 |
|
5 |
CTRL+F6 |
|
6 |
CTRL+F7 |
|
7 |
CTRL+F8 |
|
8 |
CTRL+F9 |
|
9 |
CTRL+F10 |
|
10 |
CTRL+F11 |
|
11 |
CTRL+F12 |
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.