diff options
author | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-05-09 13:42:05 +0000 |
---|---|---|
committer | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2004-05-09 13:42:05 +0000 |
commit | d31210ccbd28a7873aa5db8f34ea87275dc62269 (patch) | |
tree | 07eec8a8d97df96f930054d556e3a93881887cfd /lib/net/smtp.rb | |
parent | 3dbd32a2144af170378d0b5713a828dad6c976fb (diff) |
* lib/net/ftp.rb: improved documentation
* lib/net/imap.rb: ditto
* lib/net/pop.rb: ditto
* lib/net/smtp.rb: ditto
* lib/net/telnet.rb: ditto
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@6281 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/net/smtp.rb')
-rw-r--r-- | lib/net/smtp.rb | 335 |
1 files changed, 198 insertions, 137 deletions
diff --git a/lib/net/smtp.rb b/lib/net/smtp.rb index 62a5fc559b..db54b998c9 100644 --- a/lib/net/smtp.rb +++ b/lib/net/smtp.rb @@ -1,10 +1,12 @@ # = net/smtp.rb # -#-- -# Copyright (c) 1999-2003 Yukihiro Matsumoto -# Copyright (c) 1999-2003 Minero Aoki +# Copyright (c) 1999-2003 Yukihiro Matsumoto. +# +# Copyright (c) 1999-2003 Minero Aoki. # -# written & maintained by Minero Aoki <aamine@loveruby.net> +# Written & maintained by Minero Aoki <aamine@loveruby.net>. +# +# Documented by William Webber and Minero Aoki. # # This program is free software. You can re-distribute and/or # modify this program under the same terms as Ruby itself, @@ -14,115 +16,14 @@ # the doc/net directory of the standard ruby interpreter package. # # $Id$ -#++ +# +# See Net::SMTP for documentation. # -# == What is This Library? -# -# This library provides functionality to send internet -# mail via SMTP, the Simple Mail Transfer Protocol. For details of -# SMTP itself, see [RFC2821] (http://www.ietf.org/rfc/rfc2821.txt). -# -# == What is This Library NOT? -# -# This library does NOT provide functions to compose internet mails. -# You must create them by yourself. If you want better mail support, -# try RubyMail or TMail. You can get both libraries from RAA. -# (http://www.ruby-lang.org/en/raa.html) -# -# FYI: the official documentation on internet mail is: [RFC2822] (http://www.ietf.org/rfc/rfc2822.txt). -# -# == Examples -# -# === Sending Messages -# -# You must open a connection to an SMTP server before sending messages. -# The first argument is the address of your SMTP server, and the second -# argument is the port number. Using SMTP.start with a block is the simplest -# way to do this. This way, the SMTP connection is closed automatically -# after the block is executed. -# -# require 'net/smtp' -# Net::SMTP.start('your.smtp.server', 25) {|smtp| -# # use the SMTP object smtp only in this block -# } -# -# Replace 'your.smtp.server' with your SMTP server. Normally -# your system manager or internet provider supplies a server -# for you. -# -# Then you can send messages. -# -# msgstr = <<END_OF_MESSAGE -# From: Your Name <your@mail.address> -# To: Destination Address <someone@example.com> -# Subject: test message -# Date: Sat, 23 Jun 2001 16:26:43 +0900 -# Message-Id: <unique.message.id.string@example.com> -# -# This is a test message. -# END_OF_MESSAGE -# -# require 'net/smtp' -# Net::SMTP.start('your.smtp.server', 25) {|smtp| -# smtp.send_message msgstr, -# 'your@mail.address', -# 'his_addess@example.com' -# } -# -# === Closing the Session -# -# You MUST close the SMTP session after sending messages, by calling -# the #finish method: -# -# # using SMTP#finish -# smtp = Net::SMTP.start('your.smtp.server', 25) -# smtp.send_message msgstr, 'from@address', 'to@address' -# smtp.finish -# -# You can also use the block form of SMTP.start/SMTP#start. This closes -# the SMTP session automatically: -# -# # using block form of SMTP.start -# Net::SMTP.start('your.smtp.server', 25) {|smtp| -# smtp.send_message msgstr, 'from@address', 'to@address' -# } -# -# I strongly recommend this scheme. This form is simpler and more robust. -# -# === HELO domain -# -# In almost all situations, you must provide a third argument -# to SMTP.start/SMTP#start. This is the domain name which you are on -# (the host to send mail from). It is called the "HELO domain". -# The SMTP server will judge whether it should send or reject -# the SMTP session by inspecting the HELO domain. -# -# Net::SMTP.start('your.smtp.server', 25, -# 'mail.from.domain') {|smtp| ... } -# -# === SMTP Authentication -# -# The Net::SMTP class supports three authentication schemes; -# PLAIN, LOGIN and CRAM MD5. (SMTP Authentication: [RFC2554]) -# To use SMTP authentication, pass extra arguments to -# SMTP.start/SMTP#start. -# -# # PLAIN -# Net::SMTP.start('your.smtp.server', 25, 'mail.from,domain', -# 'Your Account', 'Your Password', :plain) -# # LOGIN -# Net::SMTP.start('your.smtp.server', 25, 'mail.from,domain', -# 'Your Account', 'Your Password', :login) -# -# # CRAM MD5 -# Net::SMTP.start('your.smtp.server', 25, 'mail.from,domain', -# 'Your Account', 'Your Password', :cram_md5) require 'net/protocol' require 'digest/md5' - -module Net # :nodoc: +module Net # Module mixed in to all SMTP error classes module SMTPError @@ -156,9 +57,109 @@ module Net # :nodoc: end # - # Class providing SMTP client functionality. + # = Net::SMTP # - # See documentation for the file smtp.rb for examples of usage. + # == What is This Library? + # + # This library provides functionality to send internet + # mail via SMTP, the Simple Mail Transfer Protocol. For details of + # SMTP itself, see [RFC2821] (http://www.ietf.org/rfc/rfc2821.txt). + # + # == What is This Library NOT? + # + # This library does NOT provide functions to compose internet mails. + # You must create them by yourself. If you want better mail support, + # try RubyMail or TMail. You can get both libraries from RAA. + # (http://www.ruby-lang.org/en/raa.html) + # + # FYI: the official documentation on internet mail is: [RFC2822] (http://www.ietf.org/rfc/rfc2822.txt). + # + # == Examples + # + # === Sending Messages + # + # You must open a connection to an SMTP server before sending messages. + # The first argument is the address of your SMTP server, and the second + # argument is the port number. Using SMTP.start with a block is the simplest + # way to do this. This way, the SMTP connection is closed automatically + # after the block is executed. + # + # require 'net/smtp' + # Net::SMTP.start('your.smtp.server', 25) do |smtp| + # # Use the SMTP object smtp only in this block. + # end + # + # Replace 'your.smtp.server' with your SMTP server. Normally + # your system manager or internet provider supplies a server + # for you. + # + # Then you can send messages. + # + # msgstr = <<END_OF_MESSAGE + # From: Your Name <your@mail.address> + # To: Destination Address <someone@example.com> + # Subject: test message + # Date: Sat, 23 Jun 2001 16:26:43 +0900 + # Message-Id: <unique.message.id.string@example.com> + # + # This is a test message. + # END_OF_MESSAGE + # + # require 'net/smtp' + # Net::SMTP.start('your.smtp.server', 25) do |smtp| + # smtp.send_message msgstr, + # 'your@mail.address', + # 'his_addess@example.com' + # end + # + # === Closing the Session + # + # You MUST close the SMTP session after sending messages, by calling + # the #finish method: + # + # # using SMTP#finish + # smtp = Net::SMTP.start('your.smtp.server', 25) + # smtp.send_message msgstr, 'from@address', 'to@address' + # smtp.finish + # + # You can also use the block form of SMTP.start/SMTP#start. This closes + # the SMTP session automatically: + # + # # using block form of SMTP.start + # Net::SMTP.start('your.smtp.server', 25) do |smtp| + # smtp.send_message msgstr, 'from@address', 'to@address' + # end + # + # I strongly recommend this scheme. This form is simpler and more robust. + # + # === HELO domain + # + # In almost all situations, you must provide a third argument + # to SMTP.start/SMTP#start. This is the domain name which you are on + # (the host to send mail from). It is called the "HELO domain". + # The SMTP server will judge whether it should send or reject + # the SMTP session by inspecting the HELO domain. + # + # Net::SMTP.start('your.smtp.server', 25, + # 'mail.from.domain') { |smtp| ... } + # + # === SMTP Authentication + # + # The Net::SMTP class supports three authentication schemes; + # PLAIN, LOGIN and CRAM MD5. (SMTP Authentication: [RFC2554]) + # To use SMTP authentication, pass extra arguments to + # SMTP.start/SMTP#start. + # + # # PLAIN + # Net::SMTP.start('your.smtp.server', 25, 'mail.from.domain', + # 'Your Account', 'Your Password', :plain) + # # LOGIN + # Net::SMTP.start('your.smtp.server', 25, 'mail.from.domain', + # 'Your Account', 'Your Password', :login) + # + # # CRAM MD5 + # Net::SMTP.start('your.smtp.server', 25, 'mail.from.domain', + # 'Your Account', 'Your Password', :cram_md5) # class SMTP @@ -169,10 +170,17 @@ module Net # :nodoc: 25 end - # Creates a new Net::SMTP object. +address+ is the hostname - # or ip address of your SMTP server. +port+ is the port to - # connect to; it defaults to port 25. - # This method does not open the TCP connection. + # + # Creates a new Net::SMTP object. + # + # +address+ is the hostname or ip address of your SMTP + # server. +port+ is the port to connect to; it defaults to + # port 25. + # + # This method does not open the TCP connection. You can use + # SMTP.start instead of SMTP.new if you want to do everything + # at once. Otherwise, follow SMTP.new with SMTP#start. + # def initialize( address, port = nil ) @address = address @port = (port || SMTP.default_port) @@ -195,11 +203,13 @@ module Net # :nodoc: @esmtp end + # # Set whether to use ESMTP or not. This should be done before # calling #start. Note that if #start is called in ESMTP mode, # and the connection fails due to a ProtocolError, the SMTP # object will automatically switch to plain SMTP mode and # retry (but not vice versa). + # def esmtp=( bool ) @esmtp = bool end @@ -229,6 +239,7 @@ module Net # :nodoc: @read_timeout = sec end + # # WARNING: This method causes serious security holes. # Use this method for only debugging. # @@ -238,9 +249,10 @@ module Net # :nodoc: # # example # smtp = Net::SMTP.new(addr, port) # smtp.set_debug_output $stderr - # smtp.start { + # smtp.start do |smtp| # .... - # } + # end + # def set_debug_output( arg ) @debug_output = arg end @@ -249,16 +261,20 @@ module Net # :nodoc: # SMTP session control # + # # Creates a new Net::SMTP object and connects to the server. # # This method is equivalent to: # - # Net::SMTP.new(address,port).start(helo_domain,account,password,authtype) + # Net::SMTP.new(address, port).start(helo_domain, account, password, authtype) + # + # === Example # - # # example - # Net::SMTP.start('your.smtp.server') { + # Net::SMTP.start('your.smtp.server') do |smtp| # smtp.send_message msgstr, 'from@example.com', ['dest@example.com'] - # } + # end + # + # === Block Usage # # If called with a block, the newly-opened Net::SMTP object is yielded # to the block, and automatically closed when the block finishes. If called @@ -266,16 +282,23 @@ module Net # :nodoc: # the caller, and it is the caller's responsibility to close it when # finished. # + # === Parameters + # # +address+ is the hostname or ip address of your smtp server. + # # +port+ is the port to connect to; it defaults to port 25. + # # +helo+ is the _HELO_ _domain_ provided by the client to the # server (see overview comments); it defaults to 'localhost.localdomain'. + # # The remaining arguments are used for SMTP authentication, if required # or desired. +user+ is the account name; +secret+ is your password # or other authentication token; and +authtype+ is the authentication # type, one of :plain, :login, or :cram_md5. See the discussion of # SMTP Authentication in the overview notes. # + # === Errors + # # This method may raise: # # * Net::SMTPAuthenticationError @@ -285,6 +308,7 @@ module Net # :nodoc: # * Net::SMTPUnknownError # * IOError # * TimeoutError + # def SMTP.start( address, port = nil, helo = 'localhost.localdomain', user = nil, secret = nil, authtype = nil, @@ -297,21 +321,43 @@ module Net # :nodoc: @started end + # # Opens a TCP connection and starts the SMTP session. # + # === Parameters + # # +helo+ is the _HELO_ _domain_ that you'll dispatch mails from; see # the discussion in the overview notes. # + # If both of +user+ and +secret+ are given, SMTP authentication + # will be attempted using the AUTH command. +authtype+ specifies + # the type of authentication to attempt; it must be one of + # :login, :plain, and :cram_md5. See the notes on SMTP Authentication + # in the overview. + # + # === Block Usage + # # When this methods is called with a block, the newly-started SMTP # object is yielded to the block, and automatically closed after # the block call finishes. Otherwise, it is the caller's # responsibility to close the session when finished. # - # If both of +user+ and +secret+ are given, SMTP authentication - # will be attempted using the AUTH command. +authtype+ specifies - # the type of authentication to attempt; it must be one of - # :login, :plain, and :cram_md5. See the notes on SMTP Authentication - # in the overview. + # === Example + # + # This is very similar to the class method SMTP.start. + # + # require 'net/smtp' + # smtp = Net::SMTP.new('smtp.mail.server', 25) + # smtp.start(helo_domain, account, password, authtype) do |smtp| + # smtp.send_message msgstr, 'from@example.com', ['dest@example.com'] + # end + # + # The primary use of this method (as opposed to SMTP.start) + # is probably to set debugging (#set_debug_output) or ESMTP + # (#esmtp=), which must be done before the session is + # started. + # + # === Errors # # If session has already been started, an IOError will be raised. # @@ -324,6 +370,7 @@ module Net # :nodoc: # * Net::SMTPUnknownError # * IOError # * TimeoutError + # def start( helo = 'localhost.localdomain', user = nil, secret = nil, authtype = nil ) # :yield: smtp if block_given? @@ -391,21 +438,26 @@ module Net # :nodoc: public + # # Sends +msgstr+ as a message. Single CR ("\r") and LF ("\n") found # in the +msgstr+, are converted into the CR LF pair. You cannot send a # binary message with this method. +msgstr+ should include both # the message headers and body. # # +from_addr+ is a String representing the source mail address. + # # +to_addr+ is a String or Strings or Array of Strings, representing # the destination mail address or addresses. # - # # example - # Net::SMTP.start('smtp.example.com') {|smtp| + # === Example + # + # Net::SMTP.start('smtp.example.com') do |smtp| # smtp.send_message msgstr, # 'from@example.com', # ['dest@example.com', 'dest2@example.com'] - # } + # end + # + # === Errors # # This method may raise: # @@ -415,6 +467,7 @@ module Net # :nodoc: # * Net::SMTPUnknownError # * IOError # * TimeoutError + # def send_message( msgstr, from_addr, *to_addrs ) send0(from_addr, to_addrs.flatten) { @socket.write_message msgstr @@ -424,33 +477,40 @@ module Net # :nodoc: alias send_mail send_message alias sendmail send_message # obsolete + # # Opens a message writer stream and gives it to the block. # The stream is valid only in the block, and has these methods: # # puts(str = ''):: outputs STR and CR LF. - # print(str):: outputs STR. - # printf(fmt, *args):: outputs sprintf(fmt,*args). - # write(str):: outputs STR and returns the length of written bytes. - # <<(str):: outputs STR and returns self. + # print(str):: outputs STR. + # printf(fmt, *args):: outputs sprintf(fmt,*args). + # write(str):: outputs STR and returns the length of written bytes. + # <<(str):: outputs STR and returns self. # # If a single CR ("\r") or LF ("\n") is found in the message, # it is converted to the CR LF pair. You cannot send a binary # message with this method. # + # === Parameters + # # +from_addr+ is a String representing the source mail address. + # # +to_addr+ is a String or Strings or Array of Strings, representing # the destination mail address or addresses. # - # # example - # Net::SMTP.start('smtp.example.com', 25) {|smtp| - # smtp.open_message_stream('from@example.com', ['dest@example.com']) {|f| + # === Example + # + # Net::SMTP.start('smtp.example.com', 25) do |smtp| + # smtp.open_message_stream('from@example.com', ['dest@example.com']) do |f| # f.puts 'From: from@example.com' # f.puts 'To: dest@example.com' # f.puts 'Subject: test message' # f.puts # f.puts 'This is a test message.' - # } - # } + # end + # end + # + # === Errors # # This method may raise: # @@ -460,6 +520,7 @@ module Net # :nodoc: # * Net::SMTPUnknownError # * IOError # * TimeoutError + # def open_message_stream( from_addr, *to_addrs, &block ) # :yield: stream send0(from_addr, to_addrs.flatten) { @socket.write_message_by_block(&block) |