diff options
author | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-08-05 14:48:33 +0000 |
---|---|---|
committer | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-08-05 14:48:33 +0000 |
commit | e6c23c67e9ef9b7b0607d0272bf10c99bb0c46a8 (patch) | |
tree | 7794230716c8a9ad1eb65fee57cf873b57d5b4ea /lib/net | |
parent | de20b0bf59e766b1aad7ca62bdca8b2bcfb6c649 (diff) |
RDoc updated by William Webber
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@4334 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/net')
-rw-r--r-- | lib/net/imap.rb | 339 |
1 files changed, 204 insertions, 135 deletions
diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 8902378e61..a84f5637ef 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -7,8 +7,128 @@ # You can freely distribute/modify this library. #++ # -# Client functionality for the IMAP mail protocol. -# See the Net::IMAP class for details and examples of use. +# == IMAP OVERVIEW +# +# An IMAP client connects to a server, and then authenticates +# itself using either #authenticate() or #login(). Having +# authenticated itself, there is a range of commands +# available to it. Most work with mailboxes, which may be +# arranged in an hierarchical namespace, and each of which +# contains zero or more messages. How this is implemented on +# the server is implementation-dependent; on a UNIX server, it +# will frequently be implemented as a files in mailbox format +# within a hierarchy of directories. +# +# To work on the messages within a mailbox, the client must +# first select that mailbox, using either #select() or (for +# read-only access) #examine(). Once the client has successfully +# selected a mailbox, they enter _selected_ state, and that +# mailbox becomes the _current_ mailbox, on which mail-item +# related commands implicitly operate. +# +# Messages have two sorts of identifiers: message sequence +# numbers, and UIDs. +# +# Message sequence numbers number messages within a mail box +# from 1 up to the number of items in the mail box. If new +# message arrives during a session, it receives a sequence +# number equal to the new size of the mail box. If messages +# are expunged from the mailbox, remaining messages have their +# sequence numbers "shuffled down" to fill the gaps. +# +# UIDs, on the other hand, are permanently guaranteed not to +# identify another message within the same mailbox, even if +# the existing message is deleted. UIDs are required to +# be assigned in ascending (but not necessarily sequential) +# order within a mailbox; this means that if a non-IMAP client +# rearranges the order of mailitems within a mailbox, the +# UIDs have to be reassigned. An IMAP client cannot thus +# rearrange message orders. +# +# == EXAMPLES OF USAGE +# +# === List sender and subject of all recent messages in the default mailbox +# +# imap = Net::IMAP.new('mail.example.com') +# imap.authenticate('LOGIN', 'joe_user', 'joes_password') +# imap.examine('INBOX') +# imap.search(["RECENT"]).each do |message_id| +# envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"] +# puts "#{envelope.from[0].name}: \t#{envelope.subject}" +# end +# +# === Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03" +# +# imap = Net::IMAP.new('mail.example.com') +# imap.authenticate('LOGIN', 'joe_user', 'joes_password') +# imap.select('Mail/sent-mail') +# if not imap.list('Mail/', 'sent-apr03') +# imap.create('Mail/sent-apr03') +# end +# imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id| +# imap.copy(message_id, "Mail/sent-apr03") +# imap.store(message_id, "+FLAGS", [:Deleted]) +# end +# imap.expunge +# +# == THREAD-SAFENESS +# +# Net::IMAP supports concurrent threads. For example, +# +# imap = Net::IMAP.new("imap.foo.net", "imap2") +# imap.authenticate("cram-md5", "bar", "password") +# imap.select("inbox") +# fetch_thread = Thread.start { imap.fetch(1..-1, "UID") } +# search_result = imap.search(["BODY", "hello"]) +# fetch_result = fetch_thread.value +# imap.disconnect +# +# This script invokes the FETCH command and the SEARCH command concurrently. +# +# == ERRORS +# +# An IMAP server can send three different types of responses to indicate +# failure: +# +# NO:: the attempted command could not be successfully completed. For +# instance, the username/password used for logging in are incorrect; +# the selected mailbox does not exists; etc. +# +# BAD:: the request from the client does not follow the server's +# understanding of the IMAP protocol. This includes attempting +# commands from the wrong client state; for instance, attempting +# to perform a SEARCH command without having SELECTed a current +# mailbox. It can also signal an internal server +# failure (such as a disk crash) has occurred. +# +# BYE:: the server is saying goodbye. This can be part of a normal +# logout sequence, and can be used as part of a login sequence +# to indicate that the server is (for some reason) unwilling +# to accept our connection. As a response to any other command, +# it indicates either that the server is shutting down, or that +# the server is timing out the client connection due to inactivity. +# +# These three error response are represented by the errors +# Net::IMAP::NoResponseError, Net::IMAP::BadResponseError, and +# Net::IMAP::ByeResponseError, all of which are subclasses of +# Net::IMAP::ResponseError. Essentially, all methods that involve +# sending a request to the server can generate one of these errors. +# Only the most pertinent instances have been documented below. +# +# Because the IMAP class uses Sockets for communication, its methods +# are also susceptible to the various errors that can occur when +# working with sockets. These are generally represented as +# Errno errors. For instance, any method that involves sending a +# request to the server and/or receiving a response from it could +# raise an Errno::EPIPE error if the network connection unexpectedly +# goes down. See the socket(7), ip(7), tcp(7), socket(2), connect(2), +# and associated man pages. +# +# Finally, a Net::IMAP::DataFormatError is thrown if low-level data +# is found to be in an incorrect format (for instance, when converting +# between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is +# thrown if a server response is non-parseable. +# # # == References # @@ -39,6 +159,10 @@ # [[RFC-2086]] # Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. # +# [[RFC-2195]] +# Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP AUTHorize Extension +# for Simple Challenge/Response", RFC 2195, September 1997. +# # [[SORT-THREAD-EXT]] # Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - SORT and THREAD # Extensions", draft-ietf-imapext-sort, May 2003. @@ -48,6 +172,10 @@ # # [[RSSL]] # http://savannah.gnu.org/projects/rubypki +# +# [[UTF7]] +# Goldsmith, D. and Davis, M., "UTF-7: A Mail-Safe Transformation Format of +# Unicode", RFC 2152, May 1997. require "socket" require "monitor" @@ -62,128 +190,7 @@ module Net # Net::IMAP implements Internet Message Access Protocol (IMAP) client # functionality. The protocol is described in [IMAP]. # - # == IMAP OVERVIEW - # - # An IMAP client connects to a server, and then authenticates - # itself using either #authenticate() or #login(). Having - # authenticated itself, there is a range of commands - # available to it. Most work with mailboxes, which may be - # arranged in an hierarchical namespace, and each of which - # contains zero or more messages. How this is implemented on - # the server is implementation-dependent; on a UNIX server, it - # will frequently be implemented as a files in mailbox format - # within a hierarchy of directories. - # - # To work on the messages within a mailbox, the client must - # first select that mailbox, using either #select() or (for - # read-only access) #examine(). Once the client has successfully - # selected a mailbox, they enter _selected_ state, and that - # mailbox becomes the _current_ mailbox, on which mail-item - # related commands implicitly operate. - # - # Messages have two sorts of identifiers: message sequence - # numbers, and UIDs. - # - # Message sequence numbers number messages within a mail box - # from 1 up to the number of items in the mail box. If new - # message arrives during a session, it receives a sequence - # number equal to the new size of the mail box. If messages - # are expunged from the mailbox, remaining messages have their - # sequence numbers "shuffled down" to fill the gaps. - # - # UIDs, on the other hand, are permanently guaranteed not to - # identify another message within the same mailbox, even if - # the existing message is deleted. UIDs are required to - # be assigned in ascending (but not necessarily sequential) - # order within a mailbox; this means that if a non-IMAP client - # rearranges the order of mailitems within a mailbox, the - # UIDs have to be reassigned. An IMAP client cannot thus - # rearrange message orders. - # - # == EXAMPLES OF USAGE - # - # === List sender and subject of all recent messages in the default mailbox - # - # imap = Net::IMAP.new('mail.example.com', 143) - # imap.authenticate('LOGIN', 'joe_user', 'joes_password') - # imap.examine('INBOX') - # imap.search(["RECENT"]).each do |message_id| - # envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"] - # puts "#{envelope.from[0].name}: \t#{envelope.subject}" - # end - # - # === Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03" - # - # imap = Net::IMAP.new('mail.example.com', 143) - # imap.authenticate('LOGIN', 'joe_user', 'joes_password') - # imap.select('Mail/sent-mail') - # if not imap.list('Mail/', 'sent-apr03') - # imap.create('Mail/sent-apr03') - # end - # imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id| - # imap.copy(message_id, "Mail/sent-apr03") - # imap.store(message_id, "+FLAGS", [:Deleted]) - # end - # imap.expunge - # - # == THREAD-SAFENESS - # - # Net::IMAP supports concurrent threads. For example, - # - # imap = Net::IMAP.new("imap.foo.net", "imap2") - # imap.authenticate("cram-md5", "bar", "password") - # imap.select("inbox") - # fetch_thread = Thread.start { imap.fetch(1..-1, "UID") } - # search_result = imap.search(["BODY", "hello"]) - # fetch_result = fetch_thread.value - # imap.disconnect - # - # This script invokes the FETCH command and the SEARCH command concurrently. - # - # == ERRORS - # - # An IMAP server can send three different types of responses to indicate - # failure: - # - # NO:: the attempted command could not be successfully completed. For - # instance, the username/password used for logging in are incorrect; - # the selected mailbox does not exists; etc. - # - # BAD:: the request from the client does not follow the server's - # understanding of the IMAP protocol. This includes attempting - # commands from the wrong client state; for instance, attempting - # to perform a SEARCH command without having SELECTed a current - # mailbox. It can also signal an internal server - # failure (such as a disk crash) has occurred. - # - # BYE:: the server is saying goodbye. This can be part of a normal - # logout sequence, and can be used as part of a login sequence - # to indicate that the server is (for some reason) unwilling - # to accept our connection. As a response to any other command, - # it indicates either that the server is shutting down, or that - # the server is timing out the client connection due to inactivity. - # - # These three error response are represented by the errors - # Net::IMAP::NoResponseError, Net::IMAP::BadResponseError, and - # Net::IMAP::ByeResponseError, all of which are subclasses of - # Net::IMAP::ResponseError. Essentially, all methods that involve - # sending a request to the server can generate one of these errors. - # Only the most pertinent instances have been documented below. - # - # Because the IMAP class uses Sockets for communication, its methods - # are also susceptible to the various errors that can occur when - # working with sockets. These are generally represented as - # Errno errors. For instance, any method that involves sending a - # request to the server and/or receiving a response from it could - # raise an Errno::EPIPE error if the network connection unexpectedly - # goes down. See the socket(7), ip(7), tcp(7), socket(2), connect(2), - # and associated man pages. - # - # Finally, a Net::IMAP::DataFormatError is thrown if low-level data - # is found to be in an incorrect format (for instance, when converting - # between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is - # thrown if a server response is non-parseable. - # + # See comment to the file imap.rb for examples of usage. class IMAP include MonitorMixin if defined?(OpenSSL) @@ -256,7 +263,15 @@ module Net return @@debug = val end - # Adds an authenticator for Net::IMAP#authenticate. + # Adds an authenticator for Net::IMAP#authenticate. +auth_type+ + # is the type of authentication this authenticator supports + # (for instance, "LOGIN"). The +authenticator+ is an object + # which defines a process() method to handle authentication with + # the server. See Net::IMAP::LoginAuthenticator and + # Net::IMAP::CramMD5Authenticator for examples. + # + # If +auth_type+ refers to an existing authenticator, it will be + # replaced by the new one. def self.add_authenticator(auth_type, authenticator) @@authenticators[auth_type] = authenticator end @@ -268,8 +283,16 @@ module Net @sock.close end - # Sends a CAPABILITY command, and returns a listing of - # capabilities that the server supports. + # Sends a CAPABILITY command, and returns an array of + # capabilities that the server supports. Each capability + # is a string. See [IMAP] for a list of possible + # capabilities. + # + # Note that the Net::IMAP class does not modify its + # behaviour according to the capabilities of the server; + # it is up to the user of the class to ensure that + # a certain capability is supported by a server before + # using it. def capability synchronize do send_command("CAPABILITY") @@ -291,7 +314,24 @@ module Net # Sends an AUTHENTICATE command to authenticate the client. # The +auth_type+ parameter is a string that represents # the authentication mechanism to be used. Currently Net::IMAP - # supports "LOGIN" and "CRAM-MD5" for the +auth_type+. For example: + # supports authentication mechanisms: + # + # LOGIN:: login using cleartext user and password. + # CRAM-MD5:: login with cleartext user and encrypted password + # (see [RFC-2195] for a full description). This + # mechanism requires that the server have the user's + # password stored in clear-text password. + # + # For both these mechanisms, there should be two +args+: username + # and (cleartext) password. A server may not support one or other + # of these mechanisms; check #capability() for a capability of + # the form "AUTH=LOGIN" or "AUTH=CRAM-MD5". + # + # Authentication is done using the appropriate authenticator object: + # see @@authenticators for more information on plugging in your own + # authenticator. + # + # For example: # # imap.authenticate('LOGIN', user, password) # @@ -312,7 +352,9 @@ module Net end # Sends a LOGIN command to identify the client and carries - # the plaintext +password+ authenticating this +user+. + # the plaintext +password+ authenticating this +user+. Note + # that, unlike calling #authenticate() with an +auth_type+ + # of "LOGIN", #login() does *not* use the login authenticator. # # A Net::IMAP::NoResponseError is raised if authentication fails. def login(user, password) @@ -755,6 +797,14 @@ module Net return thread_internal("UID THREAD", algorithm, search_keys, charset) end + # Decode a string from modified UTF-7 format to UTF-8. + # + # UTF-7 is a 7-bit encoding of Unicode [UTF7]. IMAP uses a + # slightly modified version of this to encode mailbox names + # containing non-ASCII characters; see [IMAP] section 5.1.3. + # + # Net::IMAP does _not_ automatically encode and decode + # mailbox names to and from utf7. def self.decode_utf7(s) return s.gsub(/&(.*?)-/n) { if $1.empty? @@ -770,6 +820,7 @@ module Net } end + # Encode a string from UTF-8 format to modified UTF-7. def self.encode_utf7(s) return s.gsub(/(&)|([^\x20-\x25\x27-\x7e]+)/n) { |x| if $1 @@ -1221,7 +1272,7 @@ module Net end private_class_method :u8tou16 - class RawData + class RawData # :nodoc: def format_data return @data end @@ -1233,7 +1284,7 @@ module Net end end - class Atom + class Atom # :nodoc: def format_data return @data end @@ -1245,7 +1296,7 @@ module Net end end - class QuotedString + class QuotedString # :nodoc: def format_data return '"' + @data.gsub(/["\\]/n, "\\\\\\&") + '"' end @@ -1257,7 +1308,7 @@ module Net end end - class Literal + class Literal # :nodoc: def format_data return "{" + @data.length.to_s + "}" + CRLF + @data end @@ -1269,7 +1320,7 @@ module Net end end - class MessageSet + class MessageSet # :nodoc: def format_data return format_internal(@data) end @@ -1743,7 +1794,7 @@ module Net end end - class ResponseParser + class ResponseParser # :nodoc: def parse(str) @str = str @pos = 0 @@ -2964,6 +3015,8 @@ module Net end end + # Authenticator for the "LOGIN" authentication type. See + # #authenticate(). class LoginAuthenticator def process(data) case @state @@ -2988,6 +3041,8 @@ module Net end add_authenticator "LOGIN", LoginAuthenticator + # Authenticator for the "CRAM-MD5" authentication type. See + # #authenticate(). class CramMD5Authenticator def process(challenge) digest = hmac_md5(challenge, @password) @@ -3020,24 +3075,37 @@ module Net end add_authenticator "CRAM-MD5", CramMD5Authenticator + # Superclass of IMAP errors. class Error < StandardError end + # Error raised when data is in the incorrect format. class DataFormatError < Error end + # Error raised when a response from the server is non-parseable. class ResponseParseError < Error end + # Superclass of all errors used to encapsulate "fail" responses + # from the server. class ResponseError < Error end + # Error raised upon a "NO" response from the server, indicating + # that the client command could not be completed successfully. class NoResponseError < ResponseError end + # Error raised upon a "BAD" response from the server, indicating + # that the client command violated the IMAP protocol, or an internal + # server failure has occurred. class BadResponseError < ResponseError end + # Error raised upon a "BYE" response from the server, indicating + # that the client is not being allowed to login, or has been timed + # out due to inactivity. class ByeResponseError < ResponseError end end @@ -3183,3 +3251,4 @@ EOF imap.disconnect end end + |