RDoc updated by William Webber
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@4334 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
gsinclair
parent
de20b0bf59
commit
e6c23c67e9
205
lib/net/imap.rb
205
lib/net/imap.rb
@ -7,61 +7,6 @@
|
||||
# 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.
|
||||
#
|
||||
# == References
|
||||
#
|
||||
# [[IMAP]]
|
||||
# M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
|
||||
# RFC 2060, December 1996. (Note: since obsoleted by RFC 3501)
|
||||
#
|
||||
# [[LANGUAGE-TAGS]]
|
||||
# Alvestrand, H., "Tags for the Identification of
|
||||
# Languages", RFC 1766, March 1995.
|
||||
#
|
||||
# [[MD5]]
|
||||
# Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC
|
||||
# 1864, October 1995.
|
||||
#
|
||||
# [[MIME-IMB]]
|
||||
# Freed, N., and N. Borenstein, "MIME (Multipurpose Internet
|
||||
# Mail Extensions) Part One: Format of Internet Message Bodies", RFC
|
||||
# 2045, November 1996.
|
||||
#
|
||||
# [[RFC-822]]
|
||||
# Crocker, D., "Standard for the Format of ARPA Internet Text
|
||||
# Messages", STD 11, RFC 822, University of Delaware, August 1982.
|
||||
#
|
||||
# [[RFC-2087]]
|
||||
# Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997.
|
||||
#
|
||||
# [[RFC-2086]]
|
||||
# Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
|
||||
#
|
||||
# [[SORT-THREAD-EXT]]
|
||||
# Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - SORT and THREAD
|
||||
# Extensions", draft-ietf-imapext-sort, May 2003.
|
||||
#
|
||||
# [[OSSL]]
|
||||
# http://www.openssl.org
|
||||
#
|
||||
# [[RSSL]]
|
||||
# http://savannah.gnu.org/projects/rubypki
|
||||
|
||||
require "socket"
|
||||
require "monitor"
|
||||
require "digest/md5"
|
||||
begin
|
||||
require "openssl"
|
||||
rescue LoadError
|
||||
end
|
||||
|
||||
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
|
||||
@ -104,7 +49,7 @@ module Net
|
||||
#
|
||||
# === List sender and subject of all recent messages in the default mailbox
|
||||
#
|
||||
# imap = Net::IMAP.new('mail.example.com', 143)
|
||||
# imap = Net::IMAP.new('mail.example.com')
|
||||
# imap.authenticate('LOGIN', 'joe_user', 'joes_password')
|
||||
# imap.examine('INBOX')
|
||||
# imap.search(["RECENT"]).each do |message_id|
|
||||
@ -114,7 +59,7 @@ module Net
|
||||
#
|
||||
# === Move all messages from April 2003 from "Mail/sent-mail" to "Mail/sent-apr03"
|
||||
#
|
||||
# imap = Net::IMAP.new('mail.example.com', 143)
|
||||
# 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')
|
||||
@ -184,6 +129,68 @@ module Net
|
||||
# between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is
|
||||
# thrown if a server response is non-parseable.
|
||||
#
|
||||
#
|
||||
# == References
|
||||
#
|
||||
# [[IMAP]]
|
||||
# M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1",
|
||||
# RFC 2060, December 1996. (Note: since obsoleted by RFC 3501)
|
||||
#
|
||||
# [[LANGUAGE-TAGS]]
|
||||
# Alvestrand, H., "Tags for the Identification of
|
||||
# Languages", RFC 1766, March 1995.
|
||||
#
|
||||
# [[MD5]]
|
||||
# Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC
|
||||
# 1864, October 1995.
|
||||
#
|
||||
# [[MIME-IMB]]
|
||||
# Freed, N., and N. Borenstein, "MIME (Multipurpose Internet
|
||||
# Mail Extensions) Part One: Format of Internet Message Bodies", RFC
|
||||
# 2045, November 1996.
|
||||
#
|
||||
# [[RFC-822]]
|
||||
# Crocker, D., "Standard for the Format of ARPA Internet Text
|
||||
# Messages", STD 11, RFC 822, University of Delaware, August 1982.
|
||||
#
|
||||
# [[RFC-2087]]
|
||||
# Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997.
|
||||
#
|
||||
# [[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.
|
||||
#
|
||||
# [[OSSL]]
|
||||
# http://www.openssl.org
|
||||
#
|
||||
# [[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"
|
||||
require "digest/md5"
|
||||
begin
|
||||
require "openssl"
|
||||
rescue LoadError
|
||||
end
|
||||
|
||||
module Net
|
||||
|
||||
# Net::IMAP implements Internet Message Access Protocol (IMAP) client
|
||||
# functionality. The protocol is described in [IMAP].
|
||||
#
|
||||
# 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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user