Internet Message Access Protocol version 4 - LIST Command Extensions
Extracted elements (25)
'LSUB' and 'LIST (SUBSCRIBED)' are not the same thing: LSUB may return inaccurate attributes and overloads \NoSelect with a second meaning (not subscribed itself but has subscribed descendants), whereas LIST (SUBSCRIBED) returns accurate, complete attributes with no special meanings. Because of this additional cost, clients SHOULD continue to use LSUB unless they specifically want the extra information.
The CHILDREN return option was carried forward from the original Child Mailbox Extension (RFC 3348, by Gahrns and Cheng) to give clients a way to efficiently determine mailbox hierarchy without issuing wildcard LIST commands for every mailbox, enabling collapsed outline views in mail clients.
The LIST-EXTENDED extension was created to avoid exponential growth in specialized list commands. Each new extension previously had to add its function to both LIST and LSUB, and combining extensions required yet more commands; LIST-EXTENDED consolidates these into mutually compatible options on a single command.
The new extended LIST syntax is backward compatible with the original LIST command. The extended syntax is in use only when: (1) the first word after the command begins with '('; (2) the second word after the command begins with '('; or (3) the LIST command has more than 2 parameters.
A server MUST respond to options it does not recognize with a BAD response. The client SHOULD NOT specify any option more than once; if it does, the server MUST act as if the option was received only once.
All clients that support LIST-EXTENDED MUST treat an attribute with a stronger meaning as implying any attribute that can be inferred from it: \NoInferiors implies \HasNoChildren, and \NonExistent implies \NoSelect.
Any extended LIST command (extended in any of the three ways described) MUST NOT treat the empty mailbox name as the special request to return the hierarchy delimiter and root name. If multiple mailbox names are provided and one is the empty string, the empty string MUST be ignored for matching purposes.
Extended data item tags MUST be registered with IANA. Names beginning with 'V-' are reserved for vendor-specific options/extended data items, and each vendor-specific name MUST start with the vendor-token registered in the ACAP vendor subtree registry.
The CHILDINFO extended data item MUST NOT be returned unless the client has specified the RECURSIVEMATCH selection option. Servers SHOULD suppress redundant CHILDINFO responses (i.e., SHOULD only return it when at least one matching child is not also being returned directly).
The CHILDREN return option MUST be supported by all servers. When present, the server MUST return \HasChildren and \HasNoChildren attributes even if their computation is expensive.
The RECURSIVEMATCH option MUST NOT occur as the only selection option (or only with REMOTE), as it only makes sense when other selection options are also present. The server MUST return a BAD tagged response in such cases.
The server MUST NOT return any extended data item unless the client has expressed its ability to support extended LIST responses (e.g., by using an extended LIST command). The client MUST ignore all extended fields it does not recognize.
When multiple selection options are specified, the server MUST return information about mailbox names that satisfy every selection option, unless a particular option prescribes special rules (such as RECURSIVEMATCH).
The CHILDINFO extended data item is returned in a LIST response when RECURSIVEMATCH is specified; it describes the selection criteria that caused the parent to be returned and indicates that the mailbox has at least one descendant matching those criteria. It carries the selection criteria as a parenthesized list of quoted option names.
The \HasChildren attribute indicates that a mailbox has child mailboxes. A server SHOULD NOT set this attribute if the user has no access to any child mailbox; \HasNoChildren SHOULD be used instead. It is an error to return both \HasChildren and \HasNoChildren in the same LIST response.
The LIST-EXTENDED capability string identifies this extension. Any future extension requiring a specialized form of LIST MUST refer to this document and MUST add its function through command options as described herein.
The \NonExistent attribute indicates that a mailbox name does not refer to an existing mailbox. It implies \NoSelect, MUST be supported, and MUST be accurately computed. It is only returned when the mailbox also satisfies selection criteria or has qualifying descendants under RECURSIVEMATCH.
The RECURSIVEMATCH selection option forces the server to return parent mailboxes that do not match other selection options but have descendant mailboxes that do. The matching child information is reported via the CHILDINFO extended data item.
The REMOTE selection option causes LIST to include remote mailboxes as well as local ones, replacing the RLIST command and, combined with SUBSCRIBED, the RLSUB command. It has no corresponding return option because it expands rather than restricts the set of returned mailboxes.
The SUBSCRIBED selection option causes LIST to list subscribed names rather than existing mailboxes, including names that may not exist. It implies the SUBSCRIBED return option, and the \Subscribed attribute MUST be accurately computed when this option is specified.
IANA created two new registries: one for LIST-EXTENDED options (selection and return) and one for LIST-EXTENDED extended data item tags. Initial registrations include SUBSCRIBED (selection and return), REMOTE (selection), RECURSIVEMATCH (selection), CHILDREN (return), and the CHILDINFO extended data item tag.
When the \HasChildren attribute is returned for a mailbox whose children are inaccessible to the authenticated user, more information about the mailbox hierarchy is conveyed than intended. Servers SHOULD respond with \HasNoChildren in such cases, but may not be able to efficiently compute access to all children. The CHILDINFO extended data item carries the same concern.
The childinfo-extended-item is encoded as: 'CHILDINFO' SP '(' list-select-base-opt-quoted *(SP list-select-base-opt-quoted) ')'. The selection options inside CHILDINFO are always returned quoted, unlike their specification in the extended LIST command.
The extended LIST command syntax is: LIST [SP list-select-opts] SP mailbox SP mbox-or-pat [SP list-return-opts], where list-select-opts is a parenthesized list of selection options and list-return-opts uses the keyword RETURN followed by a parenthesized list of return options.
The mailbox-list response is extended with an optional mbox-list-extended field: '(' [mbox-list-extended-item *(SP mbox-list-extended-item)] ')'. Each mbox-list-extended-item consists of a tag (astring conforming to eitem-standard-tag or eitem-vendor-tag) followed by SP and a tagged-ext-val.