[MS-OXOSRCH]:
Search Folder List Configuration Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.
Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit
Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.
Revision Summary
Date / Revision History / Revision Class / Comments4/4/2008 / 0.1 / New / Initial Availability.
4/25/2008 / 0.2 / Minor / Revised and updated property names and other technical content.
6/27/2008 / 1.0 / Major / Initial Release.
8/6/2008 / 1.01 / Minor / Revised and edited technical content.
9/3/2008 / 1.02 / Minor / Updated references.
12/3/2008 / 1.03 / Minor / Updated IP notice.
2/4/2009 / 1.04 / Minor / Revised and edited technical content.
3/4/2009 / 1.05 / Minor / Revised and edited technical content.
4/10/2009 / 2.0 / Major / Updated applicable product releases.
7/15/2009 / 3.0 / Major / Revised and edited for technical content.
11/4/2009 / 3.0.1 / Editorial / Revised and edited the technical content.
2/10/2010 / 3.0.1 / None / Version 3.0.1 release
5/5/2010 / 3.1.0 / Minor / Updated the technical content.
8/4/2010 / 3.2 / Minor / Clarified the meaning of the technical content.
11/3/2010 / 3.3 / Minor / Clarified the meaning of the technical content.
3/18/2011 / 4.0 / Major / Significantly changed the technical content.
8/5/2011 / 4.0 / None / No changes to the meaning, language, or formatting of the technical content.
10/7/2011 / 4.0 / None / No changes to the meaning, language, or formatting of the technical content.
1/20/2012 / 5.0 / Major / Significantly changed the technical content.
4/27/2012 / 5.1 / Minor / Clarified the meaning of the technical content.
7/16/2012 / 5.2 / Minor / Clarified the meaning of the technical content.
10/8/2012 / 5.3 / Minor / Clarified the meaning of the technical content.
2/11/2013 / 6.0 / Major / Significantly changed the technical content.
7/26/2013 / 6.1 / Minor / Clarified the meaning of the technical content.
11/18/2013 / 6.1 / None / No changes to the meaning, language, or formatting of the technical content.
2/10/2014 / 6.1 / None / No changes to the meaning, language, or formatting of the technical content.
4/30/2014 / 6.1 / None / No changes to the meaning, language, or formatting of the technical content.
7/31/2014 / 6.1 / None / No changes to the meaning, language, or formatting of the technical content.
10/30/2014 / 7.0 / Major / Significantly changed the technical content.
3/16/2015 / 8.0 / Major / Significantly changed the technical content.
5/26/2015 / 9.0 / Major / Significantly changed the technical content.
9/14/2015 / 9.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/13/2016 / 9.0 / None / No changes to the meaning, language, or formatting of the technical content.
9/14/2016 / 9.0 / None / No changes to the meaning, language, or formatting of the technical content.
Table of Contents
1Introduction
1.1Glossary
1.2References
1.2.1Normative References
1.2.2Informative References
1.3Overview
1.4Relationship to Other Protocols
1.5Prerequisites/Preconditions
1.6Applicability Statement
1.7Versioning and Capability Negotiation
1.8Vendor-Extensible Fields
1.9Standards Assignments
2Messages
2.1Transport
2.2Message Syntax
2.2.1Search Folder Definition Message
2.2.1.1Common Properties
2.2.1.1.1PidTagMessageClass
2.2.1.1.2PidTagDisplayName
2.2.1.2Additional Properties
2.2.1.2.1PidTagSearchFolderId
2.2.1.2.2PidTagSearchFolderTemplateId
2.2.1.2.3PidTagSearchFolderTag
2.2.1.2.4PidTagSearchFolderLastUsed
2.2.1.2.5PidTagSearchFolderExpiration
2.2.1.2.6PidTagSearchFolderStorageType
2.2.1.2.7PidTagSearchFolderEfpFlags
2.2.1.2.8PidTagSearchFolderDefinition
2.2.1.2.8.1AddressList
2.2.1.2.8.1.1AddressEntry
2.2.1.2.8.1.1.1PropertyValue
2.2.1.2.8.2Restriction
2.2.1.2.9PidTagSearchFolderRecreateInfo
2.2.2Search Folder Container
2.2.2.1Common Properties
2.2.2.1.1PidTagContainerClass
2.2.2.1.2PidTagExtendedFolderFlags
2.2.3Search Templates
2.2.3.1Unread Messages
2.2.3.2Marked for Follow-Up
2.2.3.3Unread or Marked for Follow-Up
2.2.3.4Important Mail
2.2.3.5Conversations
2.2.3.6From a Specific Person
2.2.3.7Sent Directly to Me
2.2.3.8Sent to a Specific Distribution List
2.2.3.9Large Messages
2.2.3.10Old Mail
2.2.3.11With Attachments
2.2.3.12Mail Received This Week
2.2.3.13With Specific Words
2.2.3.14Categorized
2.2.3.15Custom
2.2.4Search Folder Definition Messages and Search Folder Containers
3Protocol Details
3.1Client Details
3.1.1Abstract Data Model
3.1.2Timers
3.1.3Initialization
3.1.4Higher-Layer Triggered Events
3.1.4.1Creating a Search Folder
3.1.4.1.1Obtaining Data
3.1.4.1.2Creating a New Search Folder Container
3.1.4.1.3Creating a New Definition Message
3.1.4.2Opening a Search Folder
3.1.4.3Modifying a Search Folder
3.1.4.4Deleting a Search Folder
3.1.4.5Current Time Exceeds the Specified Time
3.1.5Message Processing Events and Sequencing Rules
3.1.6Timer Events
3.1.7Other Local Events
3.2Server Details
3.2.1Abstract Data Model
3.2.2Timers
3.2.3Initialization
3.2.4Higher-Layer Triggered Events
3.2.5Message Processing Events and Sequencing Rules
3.2.6Timer Events
3.2.7Other Local Events
4Protocol Examples
4.1Search Folder Message Object
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Product Behavior
7Change Tracking
8Index
1Introduction
The Search Folder List Configuration Protocol enables a client to persist a user's search folders on the server. A search folder is a folder that is used to query for items that match specified criteria.
Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.
1.1Glossary
This document uses the following terms:
active search folder: A search folder that has a search folder container and is up-to-date with the correct search criteria.
big-endian: Multiple-byte values that are byte-ordered with the most significant byte stored in the memory location with the lowest address.
binary large object (BLOB): A discrete packet of data that is stored in a database and is treated as a sequence of uninterpreted bytes.
Common Views folder: A special folder that contains the data for default views that are standard for a message store and can be used by any user of a client that accesses the message store.
Coordinated Universal Time (UTC): A high-precision atomic time standard that approximately tracks Universal Time (UT). It is the basis for legal, civil time all over the Earth. Time zones around the world are expressed as positive and negative offsets from UTC. In this role, it is also referred to as Zulu time (Z) and Greenwich Mean Time (GMT). In these specifications, all references to UTC refer to the time at UTC-0 (or GMT).
Deleted Items folder: A special folder that is the default location for objects that have been deleted.
display name: A text string that is used to identify a principal or other object in the user interface. Also referred to as title.
distribution list: A collection of users, computers, contacts, or other groups that is used only for email distribution, and addressed as a single recipient.
Drafts folder: A special folder that is the default location for Message objects that have been saved but not sent.
FAI contents table: A table of folder associated information (FAI) Message objects that are stored in a Folder object.
folder associated information (FAI): A collection of Message objects that are stored in a Folder object and are typically hidden from view by email applications. An FAI Message object is used to store a variety of settings and auxiliary data, including forms, views, calendar options, favorites, and category lists.
Folder object: A messaging construct that is typically used to organize data into a hierarchy of objects containing Message objects and folder associated information (FAI) Message objects.
globally unique identifier (GUID): A term used interchangeably with universally unique identifier (UUID) in Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the value. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the GUID. See also universally unique identifier (UUID).
inactive search folder: A search folder that does not have a search folder container.
journal: A process that generates a Journal-Report for an original-message.
Junk Email folder: A special folder that is the default location for Message objects that are determined to be junk email by a Junk Email rule.
mailbox: A message store that contains email, calendar items, and other Message objects for a single recipient.
Message object: A set of properties that represents an email message, appointment, contact, or other type of personal-information-management object. In addition to its own properties, a Message object contains recipient properties that represent the addressees to which it is addressed, and an attachments table that represents any files and other Message objects that are attached to it.
message store: A unit of containment for a single hierarchy of Folder objects, such as a mailbox or public folders.
network byte order: The order in which the bytes of a multiple-byte number are transmitted on a network, most significant byte first (in big-endian storage). This may or may not match the order in which numbers are normally stored in memory for a particular processor.
Outbox folder: A special folder that contains Message objects that are submitted to be sent.
remote operation (ROP): An operation that is invoked against a server. Each ROP represents an action, such as delete, send, or query. A ROP is contained in a ROP buffer for transmission over the wire.
search criteria: A criteria used to determine which messages are included in a folder with specific characteristics. It is composed of a restriction, which is the filter to be applied, and a search scope, which are the folders that contain the content to search.
search folder: A Folder object that provides a means of querying for items that match certain criteria. The search folder includes the search folder definition message and the search folder container.
search folder container: A Folder object that is created according to the specifications in the definition message. It is in the Finder folder of the message database.
search folder definition message: A folder associated information (FAI) message that persists all the information that defines a search folder. It is in the associated contents table of the Common Views folder in the message database.
Sent Items folder: A special folder that is the default location for storing copies of Message objects after they are submitted or sent.
skip block: The block in a binary large object (BLOB) that acts as padding, reserving space that can be used by future versions to insert data. The block consists of a ULONG that describes how many additional ULONGs to skip ahead.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.
1.2.1Normative References
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information.
[MS-NSPI] Microsoft Corporation, "Name Service Provider Interface (NSPI) Protocol".
[MS-OXCDATA] Microsoft Corporation, "Data Structures".
[MS-OXCFOLD] Microsoft Corporation, "Folder Object Protocol".
[MS-OXCMSG] Microsoft Corporation, "Message and Attachment Object Protocol".
[MS-OXCPERM] Microsoft Corporation, "Exchange Access and Operation Permissions Protocol".
[MS-OXCPRPT] Microsoft Corporation, "Property and Stream Object Protocol".
[MS-OXCROPS] Microsoft Corporation, "Remote Operations (ROP) List and Encoding Protocol".
[MS-OXOABK] Microsoft Corporation, "Address Book Object Protocol".
[MS-OXOCAL] Microsoft Corporation, "Appointment and Meeting Object Protocol".
[MS-OXOCFG] Microsoft Corporation, "Configuration Information Protocol".
[MS-OXOCNTC] Microsoft Corporation, "Contact Object Protocol".
[MS-OXOJRNL] Microsoft Corporation, "Journal Object Protocol".
[MS-OXOMSG] Microsoft Corporation, "Email Object Protocol".
[MS-OXONOTE] Microsoft Corporation, "Note Object Protocol".
[MS-OXOSFLD] Microsoft Corporation, "Special Folders Protocol".
[MS-OXOTASK] Microsoft Corporation, "Task-Related Objects Protocol".
[MS-OXPROPS] Microsoft Corporation, "Exchange Server Protocols Master Property List".
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,
1.2.2Informative References
[MS-OXCSTOR] Microsoft Corporation, "Store Object Protocol".
1.3Overview
A search folder provides a means of querying for items that match certain criteria. To the user, a search folder appears in the client as a normal folder that populates itself when opened. A search folder uses one of the standard templates or a custom search created by the user to include specific search criteria.
This protocol enables a client to persist a user's search folders on the server, thereby allowing the user to access these folders when connecting via a client on another machine. The client maintains search folders within a mailbox by using search folder definition messages. To create a search folder, the client collects the data that is used to define the search criteria, creates a search folder container to contain the results of the search, and creates a search folder definition message to persist the information that defines the search folder. This information includes the search criteria. A search folder definition message is saved as a folder associated information (FAI) message in a hidden folder outside the root mailbox and is not directly visible to the user.
1.4Relationship to Other Protocols
The Search Folder List Configuration Protocol relies on other protocols as follows:
It relies on the Message and Attachment Object Protocol, which is described in [MS-OXCMSG], to create and delete messages containing search folder configuration data.
It relies on the Folder Object Protocol, which is described in [MS-OXCFOLD], to create search folder containers based on the configuration data.
It relies on the Property and Stream Object Protocol, which is specified in [MS-OXCPRPT], to read and write properties of messages containing search folder configuration data.
For conceptual background information and overviews of the relationships and interactions between this and other protocols, see [MS-OXPROTO].
1.5Prerequisites/Preconditions
This protocol assumes that the client has logged on to the message store, as described in [MS-OXCSTOR], with the ability to read and write Message objects, Folder objects, and their properties.
1.6Applicability Statement
This protocol is applicable for creating user-defined queries that are used for searching a mailbox. The queries can be saved for reuse. The saved queries can be modified or deleted.
1.7Versioning and Capability Negotiation
None.
1.8Vendor-Extensible Fields
None.
1.9Standards Assignments
None.
2Messages
2.1Transport
This protocol uses the same transport as that specified in [MS-OXCMSG], [MS-OXCFOLD], and [MS-OXCPRPT].
2.2Message Syntax
2.2.1Search Folder Definition Message
A search folder definition message is stored as an FAI message, as described in [MS-OXCMSG] section 1.3.2, in the FAI contents table, as specified in [MS-OXCFOLD] section 3.1.1.2, of the Common Views folder, as specified in [MS-OXOSFLD] section 2.2.1, within a message store. A search folder definition message is used to persist a search folder within a mailbox, thereby enabling the client to maintain the user's search folders across multiple machines and reliably re-create them if needed. A search folder ceases to exist if its search folder definition message is deleted. For more details about how a search folder definition message relates to a search folder and a search folder container, see section 2.2.4.
A search folder definition message has properties that describe the search criteria. These properties are specified in the following subsections.
2.2.1.1Common Properties
The following subsections provide details about properties that are common to most Message objects, including a search folder definition message. For general details about properties, see [MS-OXPROPS]. The property data types are defined in [MS-OXCDATA] section 2.11.1.
2.2.1.1.1PidTagMessageClass
Type: PtypString
The PidTagMessageClass property ([MS-OXCMSG] section 2.2.1.3) specifies the type of the Message object. The value of this property MUST be "IPM.Microsoft.WunderBar.SFInfo" to indicate that the Message object is a search folder definition message.
2.2.1.1.2PidTagDisplayName
Type: PtypString
The PidTagDisplayName property ([MS-OXCFOLD] section 2.2.2.2.2.5) specifies the name of the search folder. The client SHOULD use this property value as the display name of the search folder container.
2.2.1.2Additional Properties
The following subsections provide details about properties that are specific to a search folder definition message. For general details about properties, see [MS-OXPROPS]. The property data types are defined in [MS-OXCDATA] section 2.11.1.