Skip to content

Commit f9d9c14

Browse files
nevansnevans
committed
Add and document flags from RFC9051
n.b. ruby/rdoc#345 means that the :section: documentation won't show up in the HTML rdoc output. 🙁
1 parent ff393a7 commit f9d9c14

File tree

1 file changed

+197
-25
lines changed

1 file changed

+197
-25
lines changed

‎lib/net/imap/flags.rb‎

Lines changed: 197 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,235 @@
33
module Net
44
class IMAP < Protocol
55

6-
# :category: Message Flags
6+
# -------------------------------------------------------------------------
7+
# :section: Message Flags: system flags
78
#
8-
# Flag indicating a message has been seen.
9+
# A message has a list of zero or more named tokens, known as "flags",
10+
# associated with it. A flag is set by its addition to this list and is
11+
# cleared by its removal. There are two types of flags in IMAP4rev2: system
12+
# flags and keywords. A flag of either type can be permanent or
13+
# session-only.
14+
#
15+
# A "system flag" is a message flag name that is predefined in the IMAP
16+
# specification and begins with "\". +Net::IMAP+ returns all system flags
17+
# as symbols, without the "\" prefix.
18+
#
19+
# The descriptions here were copied from the IMAP4rev2 specification:
20+
# [RFC-9051 § 2.3.2](https://www.rfc-editor.org/rfc/rfc9051.html#section-2.3.2)
21+
#
22+
# See [RFC-3501 § 2.3.2](https://www.rfc-editor.org/rfc/rfc3501.html#section-2.3.2)
23+
# for a description of the flags message attribute and system flag semantics
24+
# in IMAP4rev1.
25+
# -------------------------------------------------------------------------
26+
27+
# Flag indicating a message has been read.
928
SEEN = :Seen
1029

11-
# :category: Message Flags
12-
#
1330
# Flag indicating a message has been answered.
1431
ANSWERED = :Answered
1532

16-
# :category: Message Flags
17-
#
18-
# Flag indicating a message has been flagged for special or urgent
33+
# A message flag indicating a message has been flagged for special or urgent
1934
# attention.
35+
#
36+
# Also a mailbox special use attribute, which indicates that this mailbox
37+
# presents all messages marked in some way as "important". When this
38+
# special use is supported, it is likely to represent a virtual mailbox
39+
# collecting messages (from other mailboxes) that are marked with the
40+
# "\Flagged" message flag.
2041
FLAGGED = :Flagged
2142

22-
# :category: Message Flags
23-
#
2443
# Flag indicating a message has been marked for deletion. This
2544
# will occur when the mailbox is closed or expunged.
2645
DELETED = :Deleted
2746

28-
# :category: Message Flags
29-
#
3047
# Flag indicating a message is only a draft or work-in-progress version.
3148
DRAFT = :Draft
3249

33-
# :category: Message Flags
34-
#
3550
# Flag indicating that the message is "recent," meaning that this
3651
# session is the first session in which the client has been notified
3752
# of this message.
53+
#
54+
# This flag was defined by
55+
# IMAP4rev1 [RFC-3501](https://www.rfc-editor.org/rfc/rfc3501.html),
56+
# and has been deprecated by
57+
# IMAP4rev2 [RFC-9051](https://www.rfc-editor.org/rfc/rfc9051.html).
3858
RECENT = :Recent
3959

40-
# :category: Mailbox Flags
60+
# -------------------------------------------------------------------------
61+
# :section: Mailbox Name Attributes, Base attributes
62+
# Mailbox name attributes will be returned in LIST responses. Base
63+
# attributes must be returned according to the server's capabilities.
4164
#
42-
# Flag indicating that a mailbox context name cannot contain
43-
# children.
44-
NOINFERIORS = :Noinferiors
65+
# IMAP4 specifies that all mailbox name attributes, including future
66+
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
67+
# symbols, without the "\" prefix.
68+
#
69+
# The descriptions here were copied from the IMAP4rev2 specification:
70+
# [RFC9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
71+
#
72+
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
73+
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
74+
# -------------------------------------------------------------------------
75+
76+
# The "\NonExistent" attribute indicates that a mailbox name does not refer
77+
# to an existing mailbox. Note that this attribute is not meaningful by
78+
# itself, as mailbox names that match the canonical LIST pattern but don't
79+
# exist must not be returned unless one of the two conditions listed below
80+
# is also satisfied:
81+
#
82+
# 1. The mailbox name also satisfies the selection criteria (for example,
83+
# it is subscribed and the "SUBSCRIBED" selection option has been
84+
# specified).
85+
#
86+
# 2. "RECURSIVEMATCH" has been specified, and the mailbox name has at least
87+
# one descendant mailbox name that does not match the LIST pattern and
88+
# does match the selection criteria.
89+
#
90+
# In practice, this means that the "\NonExistent" attribute is usually
91+
# returned with one or more of "\Subscribed", "\Remote", "\HasChildren", or
92+
# the CHILDINFO extended data item.
93+
#
94+
# The client must treat the presence of the \NonExistent attribute as if the
95+
# \NoSelect attribute was also sent by the server
96+
NONEXISTENT = :NonExistent
4597

46-
# :category: Mailbox Flags
98+
# Mailbox attribute indicating it is not possible for any child levels of
99+
# hierarchy to exist under this name; no child levels exist now and none can
100+
# be created in the future children.
47101
#
48-
# Flag indicating that a mailbox is not selected.
102+
# The client must treat the presence of the \NoInferiors attribute as if the
103+
# \HasNoChildren attribute was also sent by the server
104+
NOINFERIORS = :Noinferiors
105+
106+
# Mailbox attribute indicating it is not possible to use this name as a
107+
# selectable mailbox.
49108
NOSELECT = :Noselect
50109

51-
# :category: Mailbox Flags
110+
# The presence of this attribute indicates that the mailbox has child
111+
# mailboxes. A server SHOULD NOT set this attribute if there are child
112+
# mailboxes and the user does not have permission to access any of them. In
113+
# this case, \HasNoChildren SHOULD be used. In many cases, however, a server
114+
# may not be able to efficiently compute whether a user has access to any
115+
# child mailboxes. Note that even though the \HasChildren attribute for a
116+
# mailbox must be correct at the time of processing the mailbox, a client
117+
# must be prepared to deal with a situation when a mailbox is marked with
118+
# the \HasChildren attribute, but no child mailbox appears in the response
119+
# to the LIST command. This might happen, for example, due to child
120+
# mailboxes being deleted or made inaccessible to the user (using access
121+
# control) by another client before the server is able to list them.
122+
#
123+
# It is an error for the server to return both a \HasChildren and a
124+
# \HasNoChildren attribute in the same LIST response. A client that
125+
# encounters a LIST response with both \HasChildren and \HasNoChildren
126+
# attributes present should act as if both are absent in the LIST response.
127+
HAS_CHILDREN = :HasChildren
128+
129+
# The presence of this attribute indicates that the mailbox has NO child
130+
# mailboxes that are accessible to the currently authenticated user.
131+
#
132+
# It is an error for the server to return both a \HasChildren and a
133+
# \HasNoChildren attribute in the same LIST response. A client that
134+
# encounters a LIST response with both \HasChildren and \HasNoChildren
135+
# attributes present should act as if both are absent in the LIST response.
136+
#
137+
# Note: the \HasNoChildren attribute should not be confused with the
138+
# \NoInferiors attribute, which indicates that no child mailboxes exist now
139+
# and none can be created in the future.
140+
HAS_NO_CHILDREN = :HasNoChildren
141+
142+
# The mailbox has been marked "interesting" by the server; the mailbox
143+
# probably contains messages that have been added since the last time the
144+
# mailbox was selected.
52145
#
53-
# Flag indicating that a mailbox has been marked "interesting" by
54-
# the server; this commonly indicates that the mailbox contains
55-
# new messages.
146+
# If it is not feasible for the server to determine whether or not the
147+
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
148+
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
149+
# and \Noselect for a single mailbox, and it MAY send none of these.
56150
MARKED = :Marked
57151

58-
# :category: Mailbox Flags
152+
# The mailbox does not contain any additional messages since the last time
153+
# the mailbox was selected.
59154
#
60-
# Flag indicating that the mailbox does not contains new messages.
155+
# If it is not feasible for the server to determine whether or not the
156+
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
157+
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
158+
# and \Noselect for a single mailbox, and it MAY send none of these.
61159
UNMARKED = :Unmarked
62160

161+
# The mailbox name was subscribed to using the SUBSCRIBE command.
162+
SUBSCRIBED = :Subscribed
163+
164+
# The mailbox is a remote mailbox.
165+
REMOTE = :Remove
166+
167+
# -------------------------------------------------------------------------
168+
# :section: Mailbox Name Attributes, Special Use
169+
# Mailbox name attributes will be returned in LIST responses. In addition
170+
# to the base mailbox name attributes defined above, an IMAP server MAY also
171+
# include any or all of the following attributes that denote "role" (or
172+
# "special-use") of a mailbox. These attributes are included along with base
173+
# attributes defined above. A given mailbox may have none, one, or more than
174+
# one of these attributes. In some cases, a special use is advice to a
175+
# client about what to put in that mailbox. In other cases, it's advice to a
176+
# client about what to expect to find there.
177+
#
178+
# IMAP4 specifies that all mailbox name attributes, including future
179+
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
180+
# symbols, without the "\" prefix.
181+
#
182+
# The descriptions here were copied from the IMAP4rev2 specification:
183+
# [RFC-9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
184+
#
185+
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
186+
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
187+
# -------------------------------------------------------------------------
188+
189+
# Mailbox attribute indicating that this mailbox presents all messages in
190+
# the user's message store. Implementations MAY omit some messages, such as,
191+
# perhaps, those in \Trash and \Junk. When this special use is supported, it
192+
# is almost certain to represent a virtual mailbox
193+
ALL = :All
194+
195+
# Mailbox attribute indicating that this mailbox is used to archive
196+
# messages. The meaning of an "archival" mailbox is server dependent;
197+
# typically, it will be used to get messages out of the inbox, or otherwise
198+
# keep them out of the user's way, while still making them accessible
199+
ARCHIVE = :Archive
200+
201+
# Mailbox attribute indicating that this mailbox is used to hold draft
202+
# messages -- typically, messages that are being composed but have not yet
203+
# been sent. In some server implementations, this might be a virtual
204+
# mailbox, containing messages from other mailboxes that are marked with the
205+
# "\Draft" message flag. Alternatively, this might just be advice that a
206+
# client put drafts here
207+
DRAFTS = :Drafts
208+
209+
# FLAGGED is defined with the system flags section.
210+
211+
# Mailbox attribute indicating that this mailbox is where messages deemed to
212+
# be junk mail are held. Some server implementations might put messages here
213+
# automatically. Alternatively, this might just be advice to a client-side
214+
# spam filter.
215+
JUNK = :Junk
216+
217+
# Mailbox attribute indicating that this mailbox is used to hold copies of
218+
# messages that have been sent. Some server implementations might put
219+
# messages here automatically. Alternatively, this might just be advice that
220+
# a client save sent messages here.
221+
SENT = :Sent
222+
223+
# Mailbox attribute indicating that this mailbox is used to hold messages
224+
# that have been deleted or marked for deletion. In some server
225+
# implementations, this might be a virtual mailbox, containing messages from
226+
# other mailboxes that are marked with the "\Deleted" message flag.
227+
# Alternatively, this might just be advice that a client that chooses not to
228+
# use the IMAP "\Deleted" model should use as its trash location. In server
229+
# implementations that strictly expect the IMAP "\Deleted" model, this
230+
# special use is likely not to be supported.
231+
TRASH = :Trash
232+
233+
# :section: Max flags
234+
63235
@@max_flag_count = 10000
64236

65237
# Returns the max number of flags interned to symbols.

0 commit comments

Comments
 (0)