ftpfxp 0.0.1 → 0.0.2

data/lib/ftpfxp.rb

@@ -1,11 +1,10 @@
-=begin
-	= ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
-	Copyright (C)2006, Alex Lee. All Rights Reserved.
-
- 	Written by Alex Lee <alexeen@noservice.net>.
-
-	This library is distributed under the terms of the Ruby license.
-	You can freely distribute/modify this library.
-=end
+#
+# = ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
+#
+# Written by Alex Lee <alexeen@gmail.com>.
+#
+# This library is distributed under the terms of the Ruby license.
+# You can freely distribute/modify this library.
+#
 require 'ftpfxp/ftpfxp'
 require 'ftpfxp/ftpfxptls'

data/lib/ftpfxp/ftpfxp.rb

@@ -1,19 +1,47 @@
-=begin
-	= ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
-	Copyright (C)2006, Alex Lee. All Rights Reserved.
-
- 	Written by Alex Lee <alexeen@noservice.net>.
-
-	This library is distributed under the terms of the Ruby license.
-	You can freely distribute/modify this library.
-=end
+#
+# = ftpfxp.rb - FXP enhancements to the basic FTP Client Library.
+#
+# Written by Alex Lee <alexeen@gmail.com>.
+#
+# This library is distributed under the terms of the Ruby license.
+# You can freely distribute/modify this library.
+#
 require 'net/ftp'
 
 module Net
-	class FTPFXP < FTP
 
-		# Issue the FEAT command to dump a list of FTP extensions supported
-		# by this FTP server.
+	# :stopdoc:
+	class FTPFXPError < FTPError; end
+	class FTPFXPSrcSiteError < FTPFXPError; end
+	class FTPFXPDstSiteError < FTPFXPError; end
+	# :startdoc:
+
+  #
+  # This class implements the File Transfer Protocol with
+  # FXP Server-to-Server transfer. This class makes FXP
+  # file transfers extremely easy yet also provides the
+  # low level control for users who wish to do things their
+  # own ways.
+  #
+  # == Major Methods
+  #
+  # - #feat
+  # - #xdupe
+  # - #fxpgetpasvport
+	# - #fxpsetport
+	# - #fxpstor
+	# - #fxpretr
+	# - #fxpwait
+	# - #fxpto
+	# - #fastlist
+	# - #fileExists
+  #
+	class FTPFXP < FTP
+		#
+		# Issue the +FEAT+ command to dump a list of FTP extensions supported
+		# by this FTP server. Please note that this list is based on what
+		# the server wants to return.
+		#
 		def feat
 			synchronize do
 				putline('FEAT')
@@ -21,14 +49,16 @@ module Net
 			end
 		end
 
-		# Sets the extended dupe checking mode on the ftp server.
+		#
+		# Sets the <tt>extended dupe checking mode</tt> on the ftp server.
 		# If no mode specified, it returns the current mode.
 		# mode=0 : Disables the extended dupe checking mode.
 		# mode=1 : X-DUPE replies several file names per line.
 		# mode=2 : Server replies with one file name per X-DUPE line.
 		# mode=3 : Server replies with one filename per X-DUPE line with no truncation.
 		# mode=4 : All files listed in one long line up to max 1024 characters.
-		# For details, visit http://www.smartftp.com/Products/SmartFTP/RFC/x-dupe-info.txt
+		# For details, visit <em>http://www.smartftp.com/Products/SmartFTP/RFC/x-dupe-info.txt</em>
+		#
 		def xdupe(mode=nil)
 			synchronize do
 				if mode.nil?
@@ -41,7 +71,9 @@ module Net
 			end
 		end
 
-		# Returns the passive port values on this ftp server.
+		#
+		# Returns the +passive+ port values on this ftp server.
+		#
 		def fxpgetpasvport
 			synchronize do
 				# Get the passive IP and port values for next transfer.
@@ -50,7 +82,9 @@ module Net
 			end
 		end
 
-		# Sets the IP and port for next transfer on this ftp server.
+		#
+		# Sets the +IP+ and +port+ for next transfer on this ftp server.
+		#
 		def fxpsetport(ipnport)
 			synchronize do
 				putline("PORT #{ipnport}")
@@ -58,8 +92,10 @@ module Net
 			end
 		end
 
+		#
 		# This is called on the destination side of the FXP.
-		# This should be called before fxpretr.
+		# This should be called before +fxpretr+.
+		#
 		def fxpstor(file)
 			synchronize do
 				voidcmd('TYPE I')
@@ -68,8 +104,10 @@ module Net
 			end
 		end
 
+		#
 		# This is called on the source side of the FXP.
-		# This should be called after fxpstor.
+		# This should be called after +fxpstor+.
+		#
 		def fxpretr(file)
 			synchronize do
 				voidcmd('TYPE I')
@@ -78,18 +116,25 @@ module Net
 			end
 		end
 
+		#
 		# This waits for the FXP to finish on the current ftp server.
 		# If this is the source, it should return 226 Transfer Complete,
 		# on success. If this is the destination, it should return
 		# 226 File receive OK.
+		#
 		def fxpwait
 			synchronize do
 				return getresp
 			end
 		end
 
+		#
 		# This FXP the specified source path to the destination path
 		# on the destination site. Path names should be for files only.
+		# This raises an exception <tt>FTPFXPSrcSiteError</tt> if errored
+		# on source site and raises an exception <tt>FTPFXPDstSiteError</tt>
+		# if errored on destination site.
+		#
 		def fxpto(dst, dstpath, srcpath)
 			pline = fxpgetpasvport
 			comp = pline.split(/\s+/)
@@ -98,16 +143,18 @@ module Net
 			dst.fxpstor(dstpath)
 			fxpretr(srcpath)
 			resp = fxpwait
-			raise "#{resp}" unless '226' == resp[0,3]
+			raise FTPFXPSrcSiteError unless '226' == resp[0,3]
 			resp = dst.fxpwait
-			raise "#{resp}" unless '226' == resp[0,3]
+			raise FTPFXPDstSiteError unless '226' == resp[0,3]
 			return resp
 		end
 
-		# This is a faster implementation of LIST where we use STAT -l
+		#
+		# This is a faster implementation of LIST where we use +STAT -l+
 		# on supported servers. (All latest versions of ftp servers should
 		# support this!) The path argument is optional, but it will call
-		# STAT -l on the path if it is specified.
+		# +STAT -l+ on the path if it is specified.
+		#
 		def fastlist(path = nil)
 			synchronize do
 				if path.nil?
@@ -119,7 +166,9 @@ module Net
 			end
 		end
 
+		#
 		# Check if a file path exists.
+		#
 		def fileExists(path)
 			resp = fastlist(path)
 			stats = false

data/lib/ftpfxp/ftpfxptls.rb

@@ -1,22 +1,73 @@
-=begin
-	= ftpfxptlx.rb - FXP with SSL/TLS enhancements to the basic FTP Client Library.
-	Copyright (C)2006, Alex Lee. All Rights Reserved.
-
-	Written by Alex Lee <alexeen@noservice.net>.
-
-	This library is distributed under the terms of the Ruby license.
-	You can freely distribute/modify this library.
-=end
+#
+#	= ftpfxptlx.rb - FXP with SSL/TLS enhancements to the basic FTP Client Library.
+#
+#	Written by Alex Lee <alexeen@gmail.com>.
+#
+#	This library is distributed under the terms of the Ruby license.
+#	You can freely distribute/modify this library.
+#
 require 'socket'
 require 'openssl'
 require 'ftpfxp'
 
 module Net
+	# :stopdoc:
+	class FTPFXPTLSError < FTPFXPError; end
+	class FTPFXPTLSSrcSiteError < FTPFXPTLSError; end
+	class FTPFXPTLSDstSiteError < FTPFXPTLSError; end
+	# :startdoc:
+
+	#
+	# This class implements the File Transfer Protocol with
+	# SSL/TLS secure connections. This class makes secure
+	# file transfers extremely easy yet also provides the
+	# low level control for users who wish to do things their
+	# own ways.
+	#
+	# == Major Methods
+	#
+	# - #login
+	# - #fxpprotp
+	# - #fxpprotc
+	# - #fxpgetcpsvport
+	# - #ftpccc
+	# - #fxpsscnon
+	# - #fxpsscnoff
+	# - #fxpto
+	# - #fxpsscnto
+	#
 	class FTPFXPTLS < FTPFXP
 		include OpenSSL
-		# The mode option controls the encryption to use.
-		# mode = 0 for TLS (default)
-		# mode = 1 for SSL
+
+		# When +true+, transfers are performed securely. Default: +true+.
+		attr_reader :secure_on
+
+		#
+		# A synonym for <tt>FTPFXPTLS.new</tt>. but with a manditory host parameter.
+		#
+		# If a block is given, it is passed the +FTP+ object, which will be closed
+		# when the block finishes, or when an exception is raised.
+		#
+		def FTPFXPTLS.open(host, user = nil, passwd = nil, mode = 0, acct = nil)
+			if block_given?
+				ftpfxptls = new(host, user, passwd, mode, acct)
+				begin
+					yield ftpfxptls
+				ensure
+					ftpfxptls.close
+				end
+			else
+				new(host, user, passwd, mode, acct)
+			end
+		end
+
+		#
+		# This method authenticates a user with the ftp server connection.
+		# If no +username+ given, defaults to +anonymous+.
+		# If no +mode+ given, defaults to +TLS AUTH+.
+		# - mode = 0 for +TLS+ (default)
+		# - mode = 1 for +SSL+
+		#
 		def login(user = "anonymous", passwd = nil, mode = 0, acct = nil)
 			# SSL/TLS context.
 			ctx = OpenSSL::SSL::SSLContext.new
@@ -45,17 +96,24 @@ module Net
 			@secure_on = true
 		end
 
+		# :stopdoc:
+		#
 		# Notes of support of each command extension.
 		# Servers known to support SSCN:
 		#	glftpd, surgeftp, Gene6, RaidenFTPD, Serv-U
 		# Servers known to support CPSV
 		#	glftpd, surgeftp, vsftpd, ioftpd, RaidenFTPd, and most others ...
 		#	Note: Serv-U does not support CPSV.
+		#
+		# :startdoc:
 
+		#
+		# This method notifies the server to start using protection mode.
 		# Must issue this command on both control connections
-		# before CPSV or SSCN when preparing secure FXP.
+		# before +CPSV+ or +SSCN+ when preparing secure FXP.
 		# Both servers will attempt to initiate SSL/TLS handshake
 		# regardless if it is Active or Passive mode.
+		#
 		def fxpprotp
 			synchronize do
 				# PROT P - Private - Integrity and Privacy
@@ -68,9 +126,11 @@ module Net
 			end
 		end
 
+		#
 		# Issue this command on the server will set the data
-		# connection to unencrypted mode and no SSL/TLS handshake
+		# connection to +unencrypted mode+ and no SSL/TLS handshake
 		# will be initiated for subsequent transfers.
+		#
 		def fxpprotc
 			synchronize do
 				putline('PROT C')
@@ -78,6 +138,7 @@ module Net
 			end
 		end
 
+		#
 		# This is the exact same command as PASV, except it requires the
 		# control connection to be in protected mode (PROT P) and it tells
 		# the server NOT to initiate the SSL/TLS handshake. The other
@@ -85,6 +146,7 @@ module Net
 		# to do as usual and initiate SSL/TLS handshake.
 		# Server must support CPSV FTP extension protocol
 		# command. Most advance FTP servers implements CPSV.
+		#
 		def fxpgetcpsvport
 			synchronize do
 				putline('CPSV')
@@ -92,9 +154,11 @@ module Net
 			end
 		end
 
-		# This executes the CCC (Clear Command Channel) command.
+		#
+		# This executes the +CCC+ (Clear Command Channel) command.
 		# Though the server may not allow this command because
 		# there are security issues with this.
+		#
 		def ftpccc
 			synchronize do
 				putline('CCC')
@@ -103,12 +167,14 @@ module Net
 			end
 		end
 
-		# Toggle the SSCN mode to on for this server. SSCN
+		#
+		# Toggle the +SSCN+ mode to on for this server. SSCN
 		# requires that protected mode must be turned on
 		# (ie. PROT P). If SSCN is on, it tells the server
 		# to act in client mode for SSL/TLS handshakes.
 		# Server must support the SSCN FTP extension protocol
 		# command.
+		#
 		def fxpsscnon
 			synchronize do
 				putline('SSCN ON')
@@ -116,11 +182,13 @@ module Net
 			end
 		end
 
-		# Toggle the SSCN mode to off for this server. If
+		#
+		# Toggle the +SSCN+ mode to off for this server. If
 		# SSCN is off, it tells the server to act in server
 		# mode (default) for SSL/TLS handshakes.
 		# Server must support the SSCN FTP extension protocol
 		# command.
+		#
 		def fxpsscnoff
 			synchronize do
 				putline('SSCN OFF')
@@ -128,9 +196,15 @@ module Net
 			end
 		end
 
-    # This FXP the specified source path to the destination path
+		#
+    # This +FXP+ the specified source path to the destination path
     # on the destination site. Path names should be for files only.
-		# Do not call this if you're using SSCN.
+		# <em>Do not call this method if you're using SSCN.</em>
+		# This method uses +CPSV+. This raises an exception
+		# <tt>FTPFXPTLSSrcSiteError</tt> if errored on source site and
+		# raises an exception <tt>FTPFXPTLSDstSiteError</tt> if errored
+		# on destination site.
+		#
 		def fxpto(dst, dstpath, srcpath)
 			if not @secure_on
 				voidcmd('PROT P')
@@ -144,14 +218,18 @@ module Net
 			dst.fxpstor(dstpath)
 			fxpretr(srcpath)
 			resp = fxpwait
-			raise "#{resp}" unless '226' == resp[0,3]
+			raise FTPFXPTLSSrcSiteError unless '226' == resp[0,3]
 			resp = dst.fxpwait
-			raise "#{resp}" unless '226' == resp[0,3]
+			raise FTPFXPTLSDstSiteError unless '226' == resp[0,3]
 			return resp
 		end
 
-    # This FXP the specified source path to the destination path
+		#
+    # This +FXP+ the specified source path to the destination path
     # on the destination site. Path names should be for files only.
+		# <em>Do not call this method if you're using CPSV.</em>
+		# This method uses +SSCN+.
+		#
 		def fxpsscnto(dst, dstpath, srcpath)
 			if not @secure_on
 				voidcmd('PROT P')
@@ -167,13 +245,15 @@ module Net
 			dst.fxpstor(dstpath)
 			fxpretr(srcpath)
 			resp = fxpwait
-			raise "#{resp}" unless '226' == resp[0,3]
+			raise FTPFXPTLSSrcSiteError unless '226' == resp[0,3]
 			resp = dst.fxpwait
-			raise "#{resp}" unless '226' == resp[0,3]
+			raise FTPFXPTLSDstSiteError unless '226' == resp[0,3]
 			return resp
 		end
 
+		#
 		# Override the transfercmd to support SSL sockets.
+		#
 		def transfercmd(cmd, rest_offset = nil)
 			if @passive
 				host, port = makepasv

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: ftpfxp
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2006-07-10 00:00:00 -04:00
+  version: 0.0.2
+date: 2006-07-11 00:00:00 -04:00
 summary: Extension to Net::FTP providing FXP and SSL/TLS support
 require_paths: 
 - lib
@@ -15,7 +15,7 @@ description:
 autorequire: ftpfxp
 default_executable: 
 bindir: bin
-has_rdoc: false
+has_rdoc: true
 required_ruby_version: !ruby/object:Gem::Version::Requirement 
   requirements: 
   - - ">"