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:
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.
|
# 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
|
# == IMAP OVERVIEW
|
||||||
#
|
#
|
||||||
# An IMAP client connects to a server, and then authenticates
|
# 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
|
# === 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.authenticate('LOGIN', 'joe_user', 'joes_password')
|
||||||
# imap.examine('INBOX')
|
# imap.examine('INBOX')
|
||||||
# imap.search(["RECENT"]).each do |message_id|
|
# 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"
|
# === 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.authenticate('LOGIN', 'joe_user', 'joes_password')
|
||||||
# imap.select('Mail/sent-mail')
|
# imap.select('Mail/sent-mail')
|
||||||
# if not imap.list('Mail/', 'sent-apr03')
|
# if not imap.list('Mail/', 'sent-apr03')
|
||||||
@ -184,6 +129,68 @@ module Net
|
|||||||
# between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is
|
# between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is
|
||||||
# thrown if a server response is non-parseable.
|
# 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
|
class IMAP
|
||||||
include MonitorMixin
|
include MonitorMixin
|
||||||
if defined?(OpenSSL)
|
if defined?(OpenSSL)
|
||||||
@ -256,7 +263,15 @@ module Net
|
|||||||
return @@debug = val
|
return @@debug = val
|
||||||
end
|
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)
|
def self.add_authenticator(auth_type, authenticator)
|
||||||
@@authenticators[auth_type] = authenticator
|
@@authenticators[auth_type] = authenticator
|
||||||
end
|
end
|
||||||
@ -268,8 +283,16 @@ module Net
|
|||||||
@sock.close
|
@sock.close
|
||||||
end
|
end
|
||||||
|
|
||||||
# Sends a CAPABILITY command, and returns a listing of
|
# Sends a CAPABILITY command, and returns an array of
|
||||||
# capabilities that the server supports.
|
# 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
|
def capability
|
||||||
synchronize do
|
synchronize do
|
||||||
send_command("CAPABILITY")
|
send_command("CAPABILITY")
|
||||||
@ -291,7 +314,24 @@ module Net
|
|||||||
# Sends an AUTHENTICATE command to authenticate the client.
|
# Sends an AUTHENTICATE command to authenticate the client.
|
||||||
# The +auth_type+ parameter is a string that represents
|
# The +auth_type+ parameter is a string that represents
|
||||||
# the authentication mechanism to be used. Currently Net::IMAP
|
# 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)
|
# imap.authenticate('LOGIN', user, password)
|
||||||
#
|
#
|
||||||
@ -312,7 +352,9 @@ module Net
|
|||||||
end
|
end
|
||||||
|
|
||||||
# Sends a LOGIN command to identify the client and carries
|
# 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.
|
# A Net::IMAP::NoResponseError is raised if authentication fails.
|
||||||
def login(user, password)
|
def login(user, password)
|
||||||
@ -755,6 +797,14 @@ module Net
|
|||||||
return thread_internal("UID THREAD", algorithm, search_keys, charset)
|
return thread_internal("UID THREAD", algorithm, search_keys, charset)
|
||||||
end
|
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)
|
def self.decode_utf7(s)
|
||||||
return s.gsub(/&(.*?)-/n) {
|
return s.gsub(/&(.*?)-/n) {
|
||||||
if $1.empty?
|
if $1.empty?
|
||||||
@ -770,6 +820,7 @@ module Net
|
|||||||
}
|
}
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Encode a string from UTF-8 format to modified UTF-7.
|
||||||
def self.encode_utf7(s)
|
def self.encode_utf7(s)
|
||||||
return s.gsub(/(&)|([^\x20-\x25\x27-\x7e]+)/n) { |x|
|
return s.gsub(/(&)|([^\x20-\x25\x27-\x7e]+)/n) { |x|
|
||||||
if $1
|
if $1
|
||||||
@ -1221,7 +1272,7 @@ module Net
|
|||||||
end
|
end
|
||||||
private_class_method :u8tou16
|
private_class_method :u8tou16
|
||||||
|
|
||||||
class RawData
|
class RawData # :nodoc:
|
||||||
def format_data
|
def format_data
|
||||||
return @data
|
return @data
|
||||||
end
|
end
|
||||||
@ -1233,7 +1284,7 @@ module Net
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
class Atom
|
class Atom # :nodoc:
|
||||||
def format_data
|
def format_data
|
||||||
return @data
|
return @data
|
||||||
end
|
end
|
||||||
@ -1245,7 +1296,7 @@ module Net
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
class QuotedString
|
class QuotedString # :nodoc:
|
||||||
def format_data
|
def format_data
|
||||||
return '"' + @data.gsub(/["\\]/n, "\\\\\\&") + '"'
|
return '"' + @data.gsub(/["\\]/n, "\\\\\\&") + '"'
|
||||||
end
|
end
|
||||||
@ -1257,7 +1308,7 @@ module Net
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
class Literal
|
class Literal # :nodoc:
|
||||||
def format_data
|
def format_data
|
||||||
return "{" + @data.length.to_s + "}" + CRLF + @data
|
return "{" + @data.length.to_s + "}" + CRLF + @data
|
||||||
end
|
end
|
||||||
@ -1269,7 +1320,7 @@ module Net
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
class MessageSet
|
class MessageSet # :nodoc:
|
||||||
def format_data
|
def format_data
|
||||||
return format_internal(@data)
|
return format_internal(@data)
|
||||||
end
|
end
|
||||||
@ -1743,7 +1794,7 @@ module Net
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
class ResponseParser
|
class ResponseParser # :nodoc:
|
||||||
def parse(str)
|
def parse(str)
|
||||||
@str = str
|
@str = str
|
||||||
@pos = 0
|
@pos = 0
|
||||||
@ -2964,6 +3015,8 @@ module Net
|
|||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Authenticator for the "LOGIN" authentication type. See
|
||||||
|
# #authenticate().
|
||||||
class LoginAuthenticator
|
class LoginAuthenticator
|
||||||
def process(data)
|
def process(data)
|
||||||
case @state
|
case @state
|
||||||
@ -2988,6 +3041,8 @@ module Net
|
|||||||
end
|
end
|
||||||
add_authenticator "LOGIN", LoginAuthenticator
|
add_authenticator "LOGIN", LoginAuthenticator
|
||||||
|
|
||||||
|
# Authenticator for the "CRAM-MD5" authentication type. See
|
||||||
|
# #authenticate().
|
||||||
class CramMD5Authenticator
|
class CramMD5Authenticator
|
||||||
def process(challenge)
|
def process(challenge)
|
||||||
digest = hmac_md5(challenge, @password)
|
digest = hmac_md5(challenge, @password)
|
||||||
@ -3020,24 +3075,37 @@ module Net
|
|||||||
end
|
end
|
||||||
add_authenticator "CRAM-MD5", CramMD5Authenticator
|
add_authenticator "CRAM-MD5", CramMD5Authenticator
|
||||||
|
|
||||||
|
# Superclass of IMAP errors.
|
||||||
class Error < StandardError
|
class Error < StandardError
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Error raised when data is in the incorrect format.
|
||||||
class DataFormatError < Error
|
class DataFormatError < Error
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Error raised when a response from the server is non-parseable.
|
||||||
class ResponseParseError < Error
|
class ResponseParseError < Error
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Superclass of all errors used to encapsulate "fail" responses
|
||||||
|
# from the server.
|
||||||
class ResponseError < Error
|
class ResponseError < Error
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# Error raised upon a "NO" response from the server, indicating
|
||||||
|
# that the client command could not be completed successfully.
|
||||||
class NoResponseError < ResponseError
|
class NoResponseError < ResponseError
|
||||||
end
|
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
|
class BadResponseError < ResponseError
|
||||||
end
|
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
|
class ByeResponseError < ResponseError
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
@ -3183,3 +3251,4 @@ EOF
|
|||||||
imap.disconnect
|
imap.disconnect
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user