1 files changed, 339 insertions, 0 deletions
diff --git a/imap/docs/rfc/rfc3348.txt b/imap/docs/rfc/rfc3348.txt
new file mode 100644
index 00000000..500871cc
--- /dev/null
+++ b/imap/docs/rfc/rfc3348.txt
@@ -0,0 +1,339 @@
+
+
+
+
+
+
+Network Working Group                                          M. Gahrns
+Request for Comments: 3348                                      R. Cheng
+Category: Informational                                        Microsoft
+                                                               July 2002
+
+
+             The Internet Message Action Protocol (IMAP4)
+                        Child Mailbox Extension
+
+Status of this Memo
+
+   This memo provides information for the Internet community.  It does
+   not specify an Internet standard of any kind.  Distribution of this
+   memo is unlimited.
+
+Copyright Notice
+
+   Copyright (C) The Internet Society (2002).  All Rights Reserved.
+
+Abstract
+
+   The Internet Message Action Protocol (IMAP4) CHILDREN extension
+   provides a mechanism for a client to efficiently determine if a
+   particular mailbox has children, without issuing a LIST "" * or a
+   LIST "" % for each mailbox.
+
+1. Conventions used in this document
+
+   In examples, "C:" and "S:" indicate lines sent by the client and
+   server respectively.  If such lines are wrapped without a new "C:" or
+   "S:" label, then the wrapping is for editorial clarity and is not
+   part of the command.
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in [RFC-2119].
+
+2. Introduction and Overview
+
+   Many IMAP4 [RFC-2060] clients present to the user a hierarchical view
+   of the mailboxes that a user has access to.  Rather than initially
+   presenting to the user the entire mailbox hierarchy, it is often
+   preferable to show to the user a collapsed outline list of the
+   mailbox hierarchy (particularly if there is a large number of
+   mailboxes).  The user can then expand the collapsed outline hierarchy
+   as needed.  It is common to include within the collapsed hierarchy a
+
+
+
+
+
+Gahrns, et al.               Informational                      [Page 1]
+
+RFC 3348             IMAP4 Child Mailbox Extension             July 2002
+
+
+   visual clue (such as a "+") to indicate that there are child
+   mailboxes under a particular mailbox.  When the visual clue is
+   clicked the hierarchy list is expanded to show the child mailboxes.
+
+   Several IMAP vendors implemented this proposal, and it is proposed to
+   document this behavior and functionality as an Informational RFC.
+
+   There is interest in addressing the general extensibility of the IMAP
+   LIST command through an IMAP LIST Extension draft.  Similar
+   functionality to the \HasChildren and \HasNoChildren flags could be
+   incorporated into this new LIST Extension.  It is proposed that the
+   more general LIST Extension draft proceed on the standards track with
+   this proposal being relegated to informational status only.
+
+   If the functionality of the \HasChildren and \HasNoChildren flags
+   were incorporated into a more general LIST extension, this would have
+   the advantage that a client could then have the opportunity to
+   request whether or not the server should return this information.
+   This would be an advantage over the current draft for servers where
+   this information is expensive to compute, since the server would only
+   need to compute the information when it knew that the client
+   requesting the information was able to consume it.
+
+3. Requirements
+
+   IMAP4 servers that support this extension MUST list the keyword
+   CHILDREN in their CAPABILITY response.
+
+   The CHILDREN extension defines two new attributes that MAY be
+   returned within a LIST response.
+
+   \HasChildren - The presence of this attribute indicates that the
+   mailbox has child mailboxes.
+
+   Servers SHOULD NOT return \HasChildren if child mailboxes exist, but
+   none will be displayed to the current user in a LIST response (as
+   should be the case where child mailboxes exist, but a client does not
+   have permissions to access them.)  In this case, \HasNoChildren
+   SHOULD be used.
+
+   In many cases, however, a server may not be able to efficiently
+   compute whether a user has access to all child mailboxes, or multiple
+   users may be accessing the same account and simultaneously changing
+   the mailbox hierarchy.  As such a client MUST be prepared to accept
+   the \HasChildren attribute as a hint.  That is, a mailbox MAY be
+   flagged with the \HasChildren attribute, but no child mailboxes will
+   appear in a subsequent LIST response.
+
+
+
+
+Gahrns, et al.               Informational                      [Page 2]
+
+RFC 3348             IMAP4 Child Mailbox Extension             July 2002
+
+
+   Example 3.1:
+   ============
+
+   /*** Consider a server that has the following mailbox hierarchy:
+
+   INBOX
+   ITEM_1
+      ITEM_1A
+   ITEM_2
+      TOP_SECRET
+
+   Where INBOX, ITEM_1 and ITEM_2 are top level mailboxes.  ITEM_1A is a
+   child mailbox of ITEM_1 and TOP_SECRET is a child mailbox of ITEM_2
+   that the currently logged on user does NOT have access to.
+
+   Note that in this case, the server is not able to efficiently compute
+   access rights to child mailboxes and responds with a \HasChildren
+   attribute for mailbox ITEM_2, even though ITEM_2/TOP_SECRET does not
+   appear in the list response.  ***/
+
+   C: A001 LIST "" *
+   S: * LIST (\HasNoChildren) "/" INBOX
+   S: * LIST (\HasChildren) "/" ITEM_1
+   S: * LIST (\HasNoChildren) "/" ITEM_1/ITEM_1A
+   S: * LIST (\HasChildren) "/" ITEM_2
+   S: A001 OK LIST Completed
+
+   \HasNoChildren - The presence of this attribute indicates that the
+   mailbox has NO child mailboxes that are accessible to the currently
+   authenticated user.  If a mailbox has the \Noinferiors attribute, the
+   \HasNoChildren attribute is redundant and SHOULD be omitted in the
+   LIST response.
+
+   In some instances a server that supports the CHILDREN extension MAY
+   NOT be able to determine whether a mailbox has children.  For example
+   it may have difficulty determining whether there are child mailboxes
+   when LISTing mailboxes while operating in a particular namespace.
+
+   In these cases, a server MAY exclude both the \HasChildren and
+   \HasNoChildren attributes in the LIST response.  As such, a client
+   can not make any assumptions about whether a mailbox has children
+   based upon the absence of a single attribute.
+
+   It is an error for the server to return both a \HasChildren and a
+   \HasNoChildren attribute in a LIST response.
+
+
+
+
+
+
+Gahrns, et al.               Informational                      [Page 3]
+
+RFC 3348             IMAP4 Child Mailbox Extension             July 2002
+
+
+   It is an error for the server to return both a \HasChildren and a
+   \NoInferiors attribute in a LIST response.
+
+   Note: the \HasNoChildren attribute should not be confused with the
+   IMAP4 [RFC-2060] defined attribute \Noinferiors which indicates that
+   no child mailboxes exist now and none can be created in the future.
+
+   The \HasChildren and \HasNoChildren attributes might not be returned
+   in response to a LSUB response.  Many servers maintain a simple
+   mailbox subscription list that is not updated when the underlying
+   mailbox structure is changed.  A client MUST NOT assume that
+   hierarchy information will be maintained in the subscription list.
+
+   RLIST is a command defined in [RFC-2193] that includes in a LIST
+   response mailboxes that are accessible only via referral.  That is, a
+   client must explicitly issue an RLIST command to see a list of these
+   mailboxes.  Thus in the case where a mailbox has child mailboxes that
+   are available only via referral, the mailboxes would appear as
+   \HasNoChildren in response to the LIST command, and \HasChildren in
+   response to the RLIST command.
+
+5. Formal Syntax
+
+   The following syntax specification uses the augmented Backus-Naur
+   Form (BNF) as described in [ABNF].
+
+   Two new mailbox attributes are defined as flag_extensions to the
+   IMAP4 mailbox_list response:
+
+   HasChildren = "\HasChildren"
+
+   HasNoChildren = "\HasNoChildren"
+
+6. Security Considerations
+
+   This extension provides a client a more efficient means of
+   determining whether a particular mailbox has children.  If a mailbox
+   has children, but the currently authenticated user does not have
+   access to any of them, the server SHOULD respond with a
+   \HasNoChildren attribute.  In many cases, however, a server may not
+   be able to efficiently compute whether a user has access to all child
+   mailboxes.  If such a server responds with a \HasChildren attribute,
+   when in fact the currently authenticated user does not have access to
+   any child mailboxes, potentially more information is conveyed about
+   the mailbox than intended.  A server designed with such levels of
+   security in mind SHOULD NOT attach the \HasChildren attribute to a
+   mailbox unless the server is certain that the user has access to at
+   least one of the child mailboxes.
+
+
+
+Gahrns, et al.               Informational                      [Page 4]
+
+RFC 3348             IMAP4 Child Mailbox Extension             July 2002
+
+
+7. References
+
+   [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version
+              4rev1", RFC 2060, December 1996.
+
+   [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC-2234] Crocker, D. and P. Overell, Editors, "Augmented BNF for
+              Syntax Specifications: ABNF", RFC 2234, November 1997.
+
+   [RFC-2193] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, September
+              1997.
+
+8.  Acknowledgments
+
+   The authors would like to thank the participants of several IMC Mail
+   Connect events for their input when this idea was originally
+   presented and refined.
+
+9. Author's Address
+
+   Mike Gahrns
+   Microsoft
+   One Microsoft Way
+   Redmond, WA, 98052
+   Phone: (425) 936-9833
+   EMail: mikega@microsoft.com
+
+   Raymond Cheng
+   Microsoft
+   One Microsoft Way
+   Redmond, WA, 98052
+   Phone: (425) 703-4913
+   EMail: raych@microsoft.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Gahrns, et al.               Informational                      [Page 5]
+
+RFC 3348             IMAP4 Child Mailbox Extension             July 2002
+
+
+10. Full Copyright Statement
+
+   Copyright (C) The Internet Society (2002).  All Rights Reserved.
+
+   This document and translations of it may be copied and furnished to
+   others, and derivative works that comment on or otherwise explain it
+   or assist in its implementation may be prepared, copied, published
+   and distributed, in whole or in part, without restriction of any
+   kind, provided that the above copyright notice and this paragraph are
+   included on all such copies and derivative works.  However, this
+   document itself may not be modified in any way, such as by removing
+   the copyright notice or references to the Internet Society or other
+   Internet organizations, except as needed for the purpose of
+   developing Internet standards in which case the procedures for
+   copyrights defined in the Internet Standards process must be
+   followed, or as required to translate it into languages other than
+   English.
+
+   The limited permissions granted above are perpetual and will not be
+   revoked by the Internet Society or its successors or assigns.
+
+   This document and the information contained herein is provided on an
+   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+   Funding for the RFC Editor function is currently provided by the
+   Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Gahrns, et al.               Informational                      [Page 6]
+