[Search] [txt|pdfized|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]
Versions: 00 01                                                         
Network Working Group                                           B. Leiba
Internet Draft                           IBM T.J. Watson Research Center
Document: draft-leiba-imap-search-multiple-01.txt             March 2003
                                                  Expires September 2003
              IMAP4 SEARCHM Command for Multiple Mailboxes
Status of this Document
   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.
   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."
     The list of current Internet-Drafts can be accessed at
     http://www.ietf.org/ietf/1id-abstracts.txt
     The list of Internet-Draft Shadow Directories can be accessed at
     http://www.ietf.org/shadow.html.
   A revised version of this draft document will be submitted to the RFC
   editor as an Proposed Standard for the Internet Community.
   Discussion and suggestions for improvement are requested, and should
   be sent to ietf-imapext@imc.org.  This document will expire before 30
   September 2003.  Distribution of this memo is unlimited.
1. Abstract
   The IMAP4 specification allows the searching only of the selected
   mailbox.  A user often wants to search multiple mailboxes, and a
   client that wishes to support this must issue a series of SELECT and
   SEARCH commands, waiting for each to complete before moving on to the
   next.  This extension allows a client to search multiple mailboxes
   with one command, limiting the round-trips and waiting for various
   searches to complete.  This also introduces named searches, allowing
   a client to pipeline the searches if it chooses.
B. Leiba                Expires September 2003                 [Page 1]


Internet DRAFT    IMAP4 SEARCHM for Multiple Mailboxes     February 2001
2. Conventions used in this document
   In examples, "C:" indicates lines sent by a client that is connected
   to a server.  "S:" indicates lines sent by the server to the client.
   The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are
   used in this document as specified in RFC 2119 [Keywords].
3. The SEARCHM command
   The basic syntax if the SEARCHM command (see the formal grammar for
   the exact syntax) is
          tag SEARCHM "search-name" (options) (list of mailbox URLs)
            (search criteria)
   The mailbox URLs MUST be relative URLs that point to IMAP mailboxes
   on this server; this command does not do referrals.  The URLs MAY
   contain the IMAP mailbox wildcard characters.  The search criteria
   are the same as those specified in [IMAP].
   The search name is used to related the SEARCHM responses to the
   search performed, allowing the client to send multiple SEARCHM
   commands without having to wait for all responses.  The server MAY
   perform those searches in parallel; it MAY instead serialize them.
   The options control the operation of the SEARCHM command.  There is
   one option defined by this document: "depth".  The option "depth(n)"
   causes the SEARCHM command to traverse the hierarchy "n" levels down
   (including the current level).  Thus, "xyz*" with depth(2) and
   "xyz/*" with depth(1) will both match child mailboxes of "xyz", but
   will not match child mailboxes of those children (of course, the
   former will also match "xyzabc", while the latter will not).
   Other options may be defined by extensions.
   The server returns one untagged SEARCHM response for each mailbox
   that matches one or more of the URLs and that has messages that match
   the search criteria.  The server MUST NOT return a SEARCHM response
   that lists no message numbers.  There are also no errors that come
   from unmatched mailbox URLs.
   The command "UID SEARCHM" behaves in an analogous way to "UID SEARCH"
   (see [IMAP]), returning UIDs instead of message numbers.
B. Leiba                Expires September 2003                 [Page 2]


Internet DRAFT    IMAP4 SEARCHM for Multiple Mailboxes     February 2001
4. Example
   C: tag1 SEARCHM "unseen" (depth(1)) ("folder1" "folder2/*") (unseen)
   C: tag2 SEARCHM "chad" () ("folder1" "folder2/*") (subject "chad")
   S: * SEARCHM "unseen" "folder1" (1 3 5 7 9)
   S: * SEARCHM "chad" "folder1" (1 2 3 4 8)
   S: * SEARCHM "unseen" "folder2/banana" (2 4)
   S: * SEARCHM "unseen" "folder2/peach" (691)
   S: tag1 OK done
   S: * SEARCHM "chad" "folder2/dubya" (3 6 9 12)
   S: tag2 OK done
5. Formal Grammar
   Items not defined here are defined in the formal grammar of [IMAP].
   mailbox_list    ::= 1#mailbox_URL
   mailbox_URL     ::= ???
                       ;; relative URL -- see [IMAPURL]
                       ;; may contain list_wildcards
   searchm         ::= "SEARCHM" SPACE search_name
                                 SPACE "(" search_options ")"
                                 SPACE "(" mailbox_list ")"
                                 SPACE "(" search_criteria ")"
   search_criteria ::= ["CHARSET" SPACE astring SPACE] 1#search_key
   search_name     ::= string
   search_option   ::= "DEPTH(" number ")"
   search_options  ::= 0#search_option
                       ;; a given option may only appear once
6. Security Considerations
   This document describes an IMAP4 command similar to the SEARCH
   command, and has the same security considerations as that command.
   Those considerations are described in [IMAP].
7. References
   [IMAP]; Crispin, M.; "Internet Message Access Protocol - Version
   4rev1"; RFC 2060; University of Washington; December 1996.
   [IMAPURL]; Newman, C.; "IMAP URL Scheme"; RFC 2192; Innosoft;
   September 1997.
   [Keywords]; Bradner, S.; "Key words for use in RFCs to Indicate
B. Leiba                Expires September 2003                 [Page 3]


Internet DRAFT    IMAP4 SEARCHM for Multiple Mailboxes     February 2001
   Requirement Levels"; RFC 2119; Harvard University; March 1997.
8. Author's Address
   Barry Leiba
   IBM T.J. Watson Research Center
   30 Saw Mill River Road
   Hawthorne, NY  10532
   Phone: 1-914-784-7941
   Email: leiba@watson.ibm.com
B. Leiba                Expires September 2003                 [Page 4]