0
@@ -7,16 +7,24 @@ module Net
0
     # A convenience method for starting a standalone SFTP session. It will
0
     # start up an SSH session using the given arguments (see the documentation
0
     # for Net::SSH::Session for details), and will then start a new SFTP session
0
-    # with the SSH session. If a block is given, it will be passed to the SFTP
0
-    # session.
0
-    def self.start(*args, &block)
0
-      session = Net::SSH.start(*args)
0
-      sftp = Net::SFTP::Session.new(session, &block)
0
+    # with the SSH session. This will block until the new SFTP is fully open
0
+    # and initialized before returning it.
0
+    #
0
+    #   sftp = Net::SFTP.start("localhost", "user")
0
+    #   sftp.upload! "/local/file.tgz", "/remote/file.tgz"
0
+    #
0
+    # If a block is given, it will be passed to the SFTP session and will be
0
+    # called once the SFTP session is fully open and initialized. When the
0
+    # block terminates, the new SSH session will automatically be closed.
0
+    #
0
+    #   Net::SFTP.start("localhost", "user") do |sftp|
0
+    #     sftp.upload! "/local/file.tgz", "/remote/file.tgz"
0
+    #   end
0
+    def self.start(host, user, options={}, &block)
0
+      session = Net::SSH.start(host, user, options)
0
+      sftp = Net::SFTP::Session.new(session, &block).connect!
0
 
0
-      if block_given?
0
-        sftp.loop { sftp.opening? }
0
-        sftp.loop
0
-      end
0
+      sftp.loop if block_given?
0
 
0
       sftp
0
     ensure
0
@@ -27,7 +35,15 @@ module Net
0
 end
0
 
0
 class Net::SSH::Connection::Session
0
+  # A convenience method for starting up a new SFTP connection on the current
0
+  # SSH session. Blocks until the SFTP session is fully open, and then
0
+  # returns the SFTP session.
0
+  #
0
+  #   Net::SSH.start("localhost", "user", "password") do |ssh|
0
+  #     ssh.sftp.upload!("/local/file.tgz", "/remote/file.tgz")
0
+  #     ssh.exec! "cd /some/path && tar xf /remote/file.tgz && rm /remote/file.tgz"
0
+  #   end
0
   def sftp
0
-    @sftp ||= Net::SFTP::Session.new(self)
0
+    @sftp ||= Net::SFTP::Session.new(self).connect!
0
   end
0
 end
0
\ No newline at end of file

0
@@ -5,6 +5,9 @@ module Net module SFTP
0
   # meaning and usage.
0
   module Constants
0
 
0
+    # The various packet types supported by SFTP protocol versions 1 through 6.
0
+    # The FXP_EXTENDED and FXP_EXTENDED_REPLY packet types are not currently
0
+    # understood by Net::SFTP.
0
     module PacketTypes
0
       FXP_INIT           = 1
0
       FXP_VERSION        = 2
0
@@ -37,16 +40,21 @@ module Net module SFTP
0
       FXP_NAME           = 104
0
       FXP_ATTRS          = 105
0
                          
0
-      FXP_EXTENDED       = 106
0
-      FXP_EXTENDED_REPLY = 107
0
+      FXP_EXTENDED       = 200
0
+      FXP_EXTENDED_REPLY = 201
0
     end
0
 
0
+    # Beginning in version 5 of the protocol, Net::SFTP::Session#rename accepts
0
+    # an optional +flags+ argument that must be either 0 or a combination of
0
+    # these constants.
0
     module RenameFlags
0
       OVERWRITE = 0x00000001
0
       ATOMIC    = 0x00000002
0
       NATIVE    = 0x00000004
0
     end
0
 
0
+    # When an FXP_STATUS packet is received from the server, the +code+ will
0
+    # be one of the following constants.
0
     module StatusCodes
0
       FX_OK                     = 0
0
       FX_EOF                    = 1
0
@@ -72,7 +80,15 @@ module Net module SFTP
0
       FX_LINK_LOOP              = 21
0
     end
0
 
0
+    # The Net::SFTP::Session#open operation is one of the worst casualties of
0
+    # the revisions between SFTP protocol versions. The flags change considerably
0
+    # between version 1 and version 6. Net::SFTP tries to shield programmers
0
+    # from the differences, so you'll almost never need to use these flags
0
+    # directly, but if you ever need to specify some flag that isn't exposed
0
+    # by the higher-level API, these are the ones that are available to you.
0
     module OpenFlags
0
+      # These are the flags that are understood by versions 1-4 of the the
0
+      # open operation.
0
       module FV1
0
         READ   = 0x00000001
0
         WRITE  = 0x00000002
0
@@ -82,6 +98,8 @@ module Net module SFTP
0
         EXCL   = 0x00000020
0
       end
0
 
0
+      # Version 5 of the open operation totally discarded the flags understood
0
+      # by versions 1-4, and replaced them with these.
0
       module FV5
0
         CREATE_NEW         = 0x00000000
0
         CREATE_TRUNCATE    = 0x00000001
0
@@ -97,6 +115,8 @@ module Net module SFTP
0
         DELETE_LOCK        = 0x00000100
0
       end
0
 
0
+      # Version 6 of the open operation added these flags, in addition to the
0
+      # flags understood by version 5.
0
       module FV6
0
         ADVISORY_LOCK           = 0x00000200
0
         NOFOLLOW                = 0x00000400
0
@@ -108,6 +128,8 @@ module Net module SFTP
0
       end
0
     end
0
 
0
+    # The Net::SFTP::Session#block operation, implemented in version 6 of
0
+    # the protocol, understands these constants for the +mask+ parameter.
0
     module LockTypes
0
       READ     = OpenFlags::FV5::READ_LOCK
0
       WRITE    = OpenFlags::FV5::WRITE_LOCK
0
@@ -116,6 +138,8 @@ module Net module SFTP
0
     end
0
 
0
     module ACE
0
+      # Access control entry types, used from version 4 of the protocol,
0
+      # onward. See Net::SFTP::Protocol::V04::Attributes::ACL.
0
       module Type
0
         ACCESS_ALLOWED = 0x00000000
0
         ACCESS_DENIED  = 0x00000001
0
@@ -123,6 +147,8 @@ module Net module SFTP
0
         SYSTEM_ALARM   = 0x00000003
0
       end
0
 
0
+      # Access control entry flags, used from version 4 of the protocol,
0
+      # onward. See Net::SFTP::Protocol::V04::Attributes::ACL.
0
       module Flag
0
         FILE_INHERIT         = 0x00000001
0
         DIRECTORY_INHERIT    = 0x00000002
0
@@ -133,6 +159,8 @@ module Net module SFTP
0
         IDENTIFIER_GROUP     = 0x00000040
0
       end
0
 
0
+      # Access control entry masks, used from version 4 of the protocol,
0
+      # onward. See Net::SFTP::Protocol::V04::Attributes::ACL.
0
       module Mask
0
         READ_DATA         = 0x00000001
0
         LIST_DIRECTORY    = 0x00000001