bits 0.1.1-mswin32

data/lib/bits.rb

@@ -0,0 +1,410 @@
+#
+# An interface for the "Background Intelligent Transfer Service" (BITS) in MS Windows
+#
+# A more decent way to interface with BITS would be the COM interface it provides. I did not get it to work, so I had to revert to pasing the bitsadmin command.
+#
+# Prereqs (formally stated in ../bits.gemspec):
+# - "Background Intelligent Transfer Service" (BITS) f�r Windows (KB842773)
+# - bitsadmin tool, available at http://www.microsoft.com/downloads/details.aspx?amp;displaylang=en&familyid=49AE8576-9BB9-4126-9761-BA8011FABF38&displaylang=en
+#
+# Author::    Nicolas E. Rabenau (mailto:nerab@gmx.at)
+# Copyright:: Copyright (c) 2005 Nicolas E. Rabenau
+# License::   Distributed under the same terms as Ruby
+#
+module BITS
+	#
+	# the basic bitsadmin string that is used in all methods
+	#
+	BITSADMIN = "bitsadmin /rawreturn /nowrap"
+
+	#
+	# The BITS Manager bundles all static BITS operations that are independent from an individual job
+	#
+	class Manager
+
+		#
+		# returns a hash of all BITS jobs where the job's name is the key and the Job itself is the value. If there is more
+		# than one job with the same name the value is an array of all jobs with that name.
+		#
+		def Manager.jobs
+			jobs = Hash.new
+
+			for jobString in `#{BITS::BITSADMIN} /list`.split(/\n/)
+				job = Job.new(jobString)
+
+				# a job's name is not guaranteed to be unique
+				if jobs[job.name].nil?
+					# value has not been assigned before
+					jobs[job.name] = job
+				else
+					if jobs[job.name].is_a? Array
+						# value already contains an array
+						jobs[job.name] << job
+					elsif jobs[job.name].is_a? Job
+						# value contains a Job
+						existingValue = jobs[job.name]
+						jobs[job.name] = Array.new
+						jobs[job.name] << existingValue
+						jobs[job.name] << job
+					else
+						# should never happen. If it does, there is something terribly wrong, so we bail out fast
+						raise "Unexpected class of value (#{jobs[job.name].class}) for jobs['#{job.name}']"
+					end
+				end
+			end
+
+			jobs
+		end
+
+		#
+		# returns a hash of all BITS jobs where the job's id is the key and the Job itself is the value
+		#
+		def Manager.jobs_by_id
+			jobs = Hash.new
+
+			for jobString in `#{BITS::BITSADMIN} /list`.split(/\n/)
+				job = Job.new(jobString)
+				jobs[job.id] = job
+			end
+
+			jobs
+		end
+
+		#
+		# create a new job with name
+		#
+		# It is arguable whether this method should be Job.create or Manager.createJob. I decided to use the latter.
+		#
+		def Manager.createJob(name)
+			if "" == name
+				raise "Job name missing"
+			end
+
+			Job.new(`#{BITS::BITSADMIN} /create "#{name}"`)
+		end
+
+		#
+		# deletes all jobs
+		#
+		def Manager.cancelAllJobs
+			`#{BITS::BITSADMIN} /reset`
+		end
+
+		#
+		# returns the version number of the underlying BITS
+		#
+		# For troubleshooting, we could use "bitsadmin /util /version /verbose"
+		#
+		def Manager.version
+			parsed = `bitsadmin`.scan /\d\.\d/
+			parsed[0]
+		end
+	end
+
+	#
+	# Models the description of a downloadable file, consisting of an URL and the local name where the result is going to be stored
+	#
+	class FileDescriptor
+		attr_accessor :remote_url, :local_name, :bytes_transferred, :bytes_total
+
+		#
+		# builds a new FileDescription with the URL and the optional local name
+		#
+		def initialize(url, local_name = nil)
+			@remote_url = url
+			@local_name = local_name
+			@bytes_transferred = 0
+			@bytes_total = 'UNKNOWN'
+		end
+
+		def to_s
+			"#{@remote_url} ->  #{@local_name}"
+	end
+	end
+
+	#
+	# Models a BITS job
+	#
+	# A job can be modified through set methods, changes will be effective immediately.
+	#
+	class Job
+		#
+		# used to refer to the job in BITS (primary key)
+		#
+		attr_reader :id
+
+		#
+		# builds a new Job from the supplied id. The job must already exist in BITS
+		#
+		# Ideally this method would have only module visibility in order to prevent instantiations of a job outside Manager.createJob
+		#
+		def initialize(job_id)
+			if %r!([A-Z0-9]{8}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{12})! =~ job_id
+				@id = $1
+			else
+				raise JobParseException, "Unable to parse '#{job_id}' into a job description. Maybe the format has changed?"
+			end
+		end
+
+		def files
+			output = `#{BITS::BITSADMIN} /listfiles {#{@id}}`
+
+			# bitsadmin typically produces something like this:
+			# 0 / UNKNOWN WORKING http://remote -> c:\temp\local.file
+
+			files = Array.new
+
+			for line in output.split(/\n/)
+				if %r!(\d+) / ((\d+)|UNKNOWN) WORKING (.*) -> (.*)! =~ line
+					# print "found 1: >#{$1}< 2: >#{$2}< 3: >#{$3}< 4: >#{$4}< 5: >#{$5}<"
+					p = FileDescriptor.new($4, $5)
+					p.bytes_transferred = $1
+					p.bytes_total = $2
+					files << p
+				else
+					raise FileDescriptorParseException, "Unable to parse '#{output}' into a file descriptor. Maybe the format has changed?"
+				end
+			end
+
+			files
+		end
+
+		#
+		# adds a file to be downloaded and the local name for the file to the job
+		#
+		def addFile(url, local_name)
+			`bitsadmin /rawreturn /addfile {#{@id}} #{url} #{local_name}`
+		end
+
+		#
+		# suspends the job
+		#
+		def suspend
+			`#{BITS::BITSADMIN} /suspend {#{@id}}`
+		end
+
+		#
+		# resumes the job
+		#
+		def resume
+			`#{BITS::BITSADMIN} /resume {#{@id}}`
+		end
+
+		#
+		# cancels the job
+		#
+		def cancel
+			`#{BITS::BITSADMIN} /cancel {#{@id}}`
+		end
+
+		#
+		# completes the job
+		#
+		def complete
+			`#{BITS::BITSADMIN} /complete {#{@id}}`
+		end
+
+		# returns the job's type
+		def type
+			`#{BITS::BITSADMIN} /gettype {#{@id}}`
+		end
+
+		# returns the job's ACL propagation flags
+		def aclflags
+			`#{BITS::BITSADMIN} /getaclflags {#{@id}}`
+		end
+
+		# returns the size of the job
+		def bytestotal
+			`#{BITS::BITSADMIN} /getbytestotal {#{@id}}`
+		end
+
+		# returns the number of bytes transferred
+		def bytestransferred
+			`#{BITS::BITSADMIN} /getbytestransferred {#{@id}}`
+		end
+
+		# returns the number of files in the job
+		def filestotal
+			`#{BITS::BITSADMIN} /getfilestotal {#{@id}}`
+		end
+
+		# returns the number of files transferred
+		def filestransferred
+			`#{BITS::BITSADMIN} /getfilestransferred {#{@id}}`
+		end
+
+		# returns the job's creation time
+		def creationtime
+			`#{BITS::BITSADMIN} /getcreationtime {#{@id}}`
+		end
+
+		# returns the job's modification time
+		def modificationtime
+			`#{BITS::BITSADMIN} /getmodificationtime {#{@id}}`
+		end
+
+		# returns the job's completion time
+		def completiontime
+			`#{BITS::BITSADMIN} /getcompletiontime {#{@id}}`
+		end
+
+		# returns the job's state
+		def state
+			`#{BITS::BITSADMIN} /getstate {#{@id}}`
+		end
+
+		# returns detailed error information
+		def error
+			`#{BITS::BITSADMIN} /geterror {#{@id}}`
+		end
+
+		# returns the job's owner
+		def owner
+			`#{BITS::BITSADMIN} /getowner {#{@id}}`
+		end
+
+		# returns the job's display name
+		def name
+			`#{BITS::BITSADMIN} /getdisplayname {#{@id}}`
+		end
+
+		# returns the job's description
+		def description
+			`#{BITS::BITSADMIN} /getdescription {#{@id}}`
+		end
+
+		# returns the job's priority
+		def priority
+			`#{BITS::BITSADMIN} /getpriority {#{@id}}`
+		end
+
+		# returns the notify flags
+		def notifyflags
+			`#{BITS::BITSADMIN} /getnotifyflags {#{@id}}`
+		end
+
+		# Determines if notify interface is registered
+		def notifyinterface
+			`#{BITS::BITSADMIN} /getnotifyinterface {#{@id}}`
+		end
+
+		# returns the retry delay in seconds
+		def minretrydelay
+			`#{BITS::BITSADMIN} /getminretrydelay {#{@id}}`
+		end
+
+		# returns the no progress timeout in seconds
+		def noprogresstimeout
+			`#{BITS::BITSADMIN} /getnoprogresstimeout {#{@id}}`
+		end
+
+		# returns an error count for the job
+		def errorcount
+			`#{BITS::BITSADMIN} /geterrorcount {#{@id}}`
+		end
+
+		# returns the proxy usage setting
+		def proxyusage
+			`#{BITS::BITSADMIN} /getproxyusage {#{@id}}`
+		end
+
+		# returns the proxy list
+		def proxylist
+			`#{BITS::BITSADMIN} /getproxylist {#{@id}}`
+		end
+
+		# returns the proxy bypass list
+		def proxybypasslist
+			`#{BITS::BITSADMIN} /getproxybypasslist {#{@id}}`
+		end
+
+		# returns the job's notification command line
+		def notifycmdline
+			`#{BITS::BITSADMIN} /getnotifycmdline {#{@id}}`
+		end
+
+		# returns a String representation of the job
+		def to_s
+			`#{BITS::BITSADMIN} /info {#{@id}}`
+		end
+
+# attribute writers
+
+		# sets the ACL propagation flags for the job
+		def aclflags=(acl_flags)
+			`#{BITS::BITSADMIN} /setaclflags {#{@id}} #{acl_flags}`
+		end
+
+		# sets the job display name
+		def name=(display_name)
+			`#{BITS::BITSADMIN} /setdisplayname {#{@id}} \"#{display_name}\"`
+		end
+
+		# sets the job description
+		def description=(description)
+			`#{BITS::BITSADMIN} /setdescription {#{@id}} \"#{description}\"`
+		end
+
+		# sets the job priority
+		def priority=(priority)
+			`#{BITS::BITSADMIN} /setpriority {#{@id}} #{priority}`
+		end
+
+		# sets the notify flags
+		def notifyflags=(notify_flags)
+			`#{BITS::BITSADMIN} /setnotifyflags {#{@id}} #{notify_flags}`
+		end
+
+		# sets the retry delay in seconds
+		def minretrydelay=(retry_delay)
+			`#{BITS::BITSADMIN} /setminretrydelay {#{@id}} #{retry_delay}`
+		end
+
+		# sets the no progress timeout in seconds
+		def noprogresstimeout=(timeout)
+			`#{BITS::BITSADMIN} /setnoprogresstimeout {#{@id}} #{timeout}`
+		end
+
+		# sets the proxy usage
+		def proxysettings=(usage)
+			`#{BITS::BITSADMIN} /setproxysettings {#{@id}} #{usage}`
+		end
+
+		# sets a program to execute for notification, and optionally parameters. The program name and parameters can be NULL.
+		# IMPORTANT: if parameters are non-NULL, then the program name should be the first parameter.
+		#
+		# For some reason I didn't get this assignment operation to work with more than a single parameter, therefore I made
+		# it a "setXxx" operation. Not elegant, but it works.
+		#
+		def setnotifycmdline(program_name, program_parameters = "")
+			`#{BITS::BITSADMIN} /setnotifycmdline {#{@id}} #{program_name} \"#{program_parameters}\"`
+		end
+
+		# adds credentials to a job. <target> may be either SERVER or PROXY, <scheme> may be BASIC, DIGEST, NTLM, NEGOTIATE, or PASSPORT.
+		def credentials=(target, scheme, username, password)
+			`#{BITS::BITSADMIN} /setcredentials {#{@id}} #{target} #{scheme} #{username} #{password}`
+		end
+	end
+
+	#
+	# Generic parse exception, base class for concrete parse exceptions
+	#
+	class ParseException < Exception
+
+	end
+
+	#
+	# Exception that occurs in case parsing a Job specification fails
+	#
+	class JobParseException < ParseException
+
+	end
+
+	#
+	# Exception that occurs in case parsing a FileDescriptor specification fails
+	#
+	class FileDescriptorParseException < ParseException
+
+	end
+end

data/test/test_bits.rb

@@ -0,0 +1,132 @@
+require 'test/unit'
+require "bits"
+include BITS
+
+#
+# Unit tests for bits.rb
+#
+# Author::    Nicolas E. Rabenau (mailto:nerab@gmx.at)
+# Copyright:: Copyright (c) 2005 Nicolas E. Rabenau
+# License::   Distributed under the same terms as Ruby
+#
+class BITS_Test < Test::Unit::TestCase
+
+	@@RND_CHARS = ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]
+
+	#
+	# create job with random name
+	#
+	def setup
+		@jobName = self.class.name + "_" + BITS_Test.randomString(8)
+		@job = Manager.createJob(@jobName)
+	end
+
+	#
+	# remove test job
+	#
+	def teardown
+		@job.cancel
+	end
+
+	#
+	# test setting and reading the job's name
+	#
+	def test_name
+		assert_equal(@jobName, @job.name)
+	end
+
+	#
+	# test setting and reading the job's description
+	#
+	def test_description
+		description = "A test job for bits.rb"
+		@job.description = description
+		assert_equal(description, @job.description)
+	end
+
+	#
+	# tests the Manager's job listing by name
+	#
+	def test_joblist_by_name
+		assert(0 < Manager.jobs.size)
+		assert(Manager.jobs.has_key?(@jobName))
+	end
+
+	#
+	# tests that the Manager's job listing by name returns all Jobs with duplicate names in an array
+	#
+	def test_joblist_by_name_with_duplicate_jobnames
+		assert(Manager.jobs.has_key?(@jobName))
+		j2 = Manager.createJob(@jobName)
+		assert_equal(Array, Manager.jobs[@jobName].class)
+		assert_equal(2, Manager.jobs[@jobName].size)
+		j2.cancel
+	end
+
+	#
+	# tests the Manager's job listing by id
+	#
+	def test_joblist_by_id
+		assert(0 < Manager.jobs_by_id.size)
+		assert(Manager.jobs_by_id.has_key?(@job.id))
+	end
+
+	#
+	# test setting and reading the job's notify commandline
+	#
+	def test_notifycmdline
+		notifycmdline = "net"
+		notifycmdlineparams = "net send * BITS job #{@job.name} (#{@job.id}) successfully completed."
+		@job.setnotifycmdline(notifycmdline, notifycmdlineparams)
+		@job.description = "Testing notifycmdline"
+		assert_equal("the notification command line is '#{notifycmdline}' '#{notifycmdline}'", @job.notifycmdline)
+	end
+
+	def test_status_created
+		assert_equal("SUSPENDED", @job.state)
+	end
+
+	#
+	# test resuming a job without an URL attached, must fail
+	#
+	def test_resume_empty
+		@job.resume
+		assert_equal("SUSPENDED", @job.state)
+	end
+
+	#
+	# test resuming a job with an URL attached, must not be in suspended or cancelled state
+	#
+	def test_resume_nonempty
+		@job.addFile("http://www.google.com", "c:\\temp\\google.com.html")
+		@job.resume
+		assert_not_equal("SUSPENDED", @job.state)
+		assert_not_equal("CANCELLED", @job.state)
+	end
+
+	#
+	# test attaching files to the job
+	#
+	def test_files
+		@job.addFile("http://www.google.com", "c:\\temp\\google.com.html")
+		@job.addFile("http://www.heise.de", "c:\\temp\\heise.de.html")
+		assert_equal(@job.files[0].remote_url, "http://www.google.com")
+		assert_equal(@job.files[0].local_name, "c:\\temp\\google.com.html")
+		assert_equal(@job.files[1].remote_url, "http://www.heise.de")
+		assert_equal(@job.files[1].local_name, "c:\\temp\\heise.de.html")
+	end
+
+private
+
+	#
+	# returns a String of defined length, made of random characters and numbers
+	#
+	def BITS_Test.randomString(length)
+		retVal = Array.new
+		for i in 0..length
+			retVal[i] = @@RND_CHARS[rand(@@RND_CHARS.length)]
+		end
+
+		retVal.to_s
+	end
+end

metadata

@@ -0,0 +1,41 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: bits
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+date: 2005-10-12
+summary: A ruby interface for the Background Intelligent Transfer Service (BITS)
+require_paths: 
+  - lib
+email: nerab@gmx.at
+homepage: http://bits.rubyforge.org
+rubyforge_project: bits
+description: 
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: mswin32
+authors: 
+  - Nicolas E. Rabenau
+files: 
+  - lib/bits.rb
+test_files: 
+  - test/test_bits.rb
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: 
+  - Background Intelligent Transfer Service (BITS) f�r Windows (KB842773)
+  - "bitsadmin tool, available at
+    http://www.microsoft.com/downloads/details.aspx?amp;displaylang=en&familyid=49AE8576-9BB9-4126-9761-BA8011FABF38&displaylang=en"
+dependencies: []