rexchange 0.1.1

data/CHANGELOG

@@ -0,0 +1,3 @@
+-- 1.1
+* Fleshed out the README
+* Copied the RAKEFILE from the Rools project

data/RAKEFILE

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+# require 'pscp'
+
+PACKAGE_VERSION = '0.1.1'
+
+PACKAGE_FILES = FileList[
+  'README',
+  'CHANGELOG',
+  'RAKEFILE',
+  'lib/**/*.rb',
+  'test/*.rb'
+].to_a
+
+PROJECT = 'rexchange'
+
+ENV['RUBYFORGE_USER'] = "ssmoot@rubyforge.org"
+ENV['RUBYFORGE_PROJECT'] = "/var/www/gforge-projects/#{PROJECT}"
+
+task :default => [:rdoc]
+
+desc 'Generate Documentation'
+rd = Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = "RExchange -- A simple wrapper around Microsoft Exchange Server's WebDAV API"
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include(PACKAGE_FILES)
+end
+
+gem_spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = PROJECT
+  s.summary = "A simple wrapper around Microsoft Exchange Server's WebDAV API"
+  s.description = "Connect, browse, and iterate through folders and messages on an Exchange Server"
+  s.version = PACKAGE_VERSION
+  
+  s.authors = 'Sam Smoot', 'Scott Bauer'
+  s.email = 'ssmoot@gmail.com; bauer.mail@gmail.com'
+  s.rubyforge_project = PROJECT
+  s.homepage = 'http://substantiality.net'
+  
+  s.files = PACKAGE_FILES
+  
+  s.require_path = 'lib'
+  s.requirements << 'none'
+  s.autorequire = 'rexchange'
+  
+  s.has_rdoc = true
+  s.rdoc_options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+end
+
+Rake::GemPackageTask.new(gem_spec) do |p|
+  p.gem_spec = gem_spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc "Publish RDOC to RubyForge"
+task :rubyforge => [:rdoc, :gem] do
+  Rake::SshDirPublisher.new(ENV['RUBYFORGE_USER'], ENV['RUBYFORGE_PROJECT'], 'doc').upload
+end

data/README

@@ -0,0 +1,76 @@
+= RExchange -- A pure ruby wrapper for the Microsoft Exchange Server WebDAV API
+
+== Things you should know
+
+* Requires Ruby 1.8.4 (for the extended WebDAV support in the net/http library)
+* RExchange is cross-platform compatible, being written in pure Ruby
+* Kiwi fruits are packed with vitamins
+
+== Why should you use RExchange
+
+* It makes interacting with Exchange simple
+* It was written for a real application, and does real work reliably day in and day out
+
+== Example
+
+	uri = 'https://example.com/exchange/admin/'
+	options = { :user => 'mydomain\admin', :password => 'random' }
+	
+	# We pass our uri (pointing directly to a mailbox), and options hash to RExchange::open
+	# to create a RExchange::Session.
+	RExchange::open(uri, options) do |mailbox|
+	
+		# The block parameter ("mailbox" in this case) is actually the Session itself.
+		# You can refer to folders by chaining them as method calls. "inbox" in this case
+		# isn't a defined method for Session, but part of the DSL to refer to folder names.
+		# Each folder name returns a RExchange::Folder. The folder is Enumerable, allowing
+		# iteration over the messages in the folder.
+	  mailbox.inbox.each do |message|
+	
+			# The "message" block parameter is a RExchange::Message object. You have access to
+			# several attributes of the message, including: href, from, to, message-id, date,
+			# importance, hasattachment and body.
+	 		p message.subject
+	
+			# The RExchange::Message#move_to method moves the message to another folder, in this
+			# case, an "archive" folder off of the inbox.
+			message.move_to '/inbox/archive'
+		end
+		
+		# You can also call the RExchange::Folder#messages method if you find calling "each"
+		# on a folder directly a little obscure.
+		mailbox.inbox.archive.messages.each do |m|
+		
+			# Our previous message should show up in here now.
+			p m.subject
+		end
+		
+		# The RExchange::Folder#message_in method is less expensive than the DSL folder-chaining
+		# methods. Since the folder-chaining is cached in the Session it's a small hit, and some
+		# may prefer the readability of them, but if you're looking for absolute performance
+		# or have really deep folder structures then this may be the method for you.
+		mailbox.messages_in '/inbox/' do |m|
+			
+			# Since we moved all our messages to the archive earlier, this shouldn't display
+			# anything.
+			p m.from
+		end
+		
+		# Folder names are "normalized", replacing dashes and spaces with underscores,
+		# squeezing out multiple underscores in a row, and downcasing the whole thing.
+		# So a folder name such as "My Very-long Folder Name" would look like:
+		mailbox.my_very_long_folder_name
+	end
+	
+== Caveats
+
+There are several features missing (simply because we didn't need them yet). Among them:
+
+* The ability to delete messages or folders
+* The ability to create folders
+* There's no mechanism for sending new messages, or replying or forwarding existing ones
+* There are a lot more message attributes we're not retrieving since they weren't useful to us, but they might be to you
+* Exporting an email or entire folder tree to offline storage
+* And much much more!
+
+If you'd like to see any of these features, or have some ideas of your own you'd like to see implemented don't hesitate to let us know, and if it strikes our fancy maybe you'll get some free programming!

data/lib/rexchange.rb

@@ -0,0 +1,11 @@
+require 'rexchange/session'
+
+module RExchange
+  # Use STDOUT or another stream if you'd like to capture the HTTP debug output
+  DEBUG_STREAM = nil
+  
+  # A shortcut to RExchange::Session#new's block syntax
+  def self.open(uri, options = {})
+    yield RExchange::Session.new(uri, options)  
+  end
+end

data/lib/rexchange/credentials.rb

@@ -0,0 +1,27 @@
+require 'uri'
+
+module RExchange
+
+  # Credentials are passed around between Folders to emulate a stateful
+  # connection with the RExchange::Session
+  class Credentials
+    attr_reader :user, :password, :uri, :use_ssl
+
+    # You must pass a uri, and an options hash containing :user and :password
+    def initialize(uri, options = {})
+      @uri = URI.parse(uri)
+      @use_ssl = (@uri.scheme.downcase == 'https')
+      @user = @uri.userinfo ? @user.userinfo.split(':')[0] : options.delete(:user)
+      @password = @uri.userinfo ? @user.userinfo.split(':')[1] : options.delete(:password)
+      @port = @uri.port || @uri.default_port
+            
+      if block_given?
+        yield self
+      else
+        return self
+      end
+    end
+    
+  end
+  
+end

data/lib/rexchange/dav_move_request.rb

@@ -0,0 +1,22 @@
+require 'rexchange/exchange_request'
+
+module RExchange
+  # Used to move entities to different locations in the accessable mailbox.
+  class DavMoveRequest < ExchangeRequest
+    METHOD = 'MOVE'
+    REQUEST_HAS_BODY = false
+    RESPONSE_HAS_BODY = false
+    
+    def self.execute(credentials, source, destination)
+      options = {
+        :headers => {
+        'Destination' => destination
+        },
+        :path => source
+      }
+      
+      super credentials, options
+    end
+  end
+  
+end

data/lib/rexchange/dav_search_request.rb

@@ -0,0 +1,8 @@
+require 'rexchange/exchange_request'
+
+module RExchange
+  # Used for arbitrary SEARCH requests
+  class DavSearchRequest < ExchangeRequest
+    METHOD = 'SEARCH'
+  end
+end

data/lib/rexchange/exchange_request.rb

@@ -0,0 +1,40 @@
+require 'net/https'
+
+module RExchange
+  
+  # Exchange Server's WebDAV interface is non-standard, so
+  # we create this simple wrapper to extend the 'net/http'
+  # library and add the request methods we need.
+  class ExchangeRequest < Net::HTTPRequest
+    REQUEST_HAS_BODY = true
+    RESPONSE_HAS_BODY = true
+    
+    def self.execute(credentials, options = {})
+      http = Net::HTTP.new(credentials.uri.host, credentials.uri.port)
+      http.set_debug_output(RExchange::DEBUG_STREAM) if RExchange::DEBUG_STREAM
+      request_path = options[:path] || credentials.uri.path
+      req = self.new(request_path)
+      req.basic_auth credentials.user, credentials.password
+      req.content_type = 'text/xml'
+      req.add_field 'host', credentials.uri.host
+      
+      if options[:headers]
+        options[:headers].each_pair do |k, v|
+          req.add_field k, v
+        end
+      end
+      
+      req.body = options[:body] if REQUEST_HAS_BODY
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      return http.request(req) if RESPONSE_HAS_BODY
+      return true
+    end
+    
+    private
+    # You can not instantiate an ExchangeRequest externally.
+    def initialize(*args)
+      super
+    end
+  end
+end

data/lib/rexchange/extensions.rb

@@ -0,0 +1,9 @@
+class String
+  def ends_with?(partial)
+    self[self.size - partial.size..self.size] == partial
+  end
+  
+  def ensure_ends_with(partial)
+    self.ends_with?(partial) ? self : self + partial
+  end
+end 

data/lib/rexchange/folder.rb

@@ -0,0 +1,119 @@
+require 'rexml/document'
+require 'net/https'
+require 'rexchange/extensions'
+require 'rexchange/dav_search_request'
+require 'rexchange/message'
+
+module RExchange
+
+  class Folder
+    include REXML
+    
+    include Enumerable
+    
+    attr_reader :credentails
+    
+    def initialize(credentials, parent, folder)
+      @credentials, @parent, @folder = credentials, parent, folder
+    end
+    
+    alias :old_method_missing :method_missing
+    
+    def method_missing(sym, *args)
+      if subfolder_exist?(sym.to_s)
+        Folder.new(@credentials, self, sym )
+      else
+        old_method_missing(sym, args)
+      end
+    end
+    
+    def each
+      messages.each do |msg|
+        yield msg
+      end  
+    end
+    
+    def messages_in(folder)
+      folder.split('/').inject(@credentials.uri.path) do |final_path, current_path|
+        Folder.new(@credentials, final_path, current_path)
+      end.messages
+    end
+    
+    def messages
+    
+      body = <<DABODY
+				<?xml version="1.0"?>
+				<D:searchrequest xmlns:D = "DAV:">
+					 <D:sql>
+					 SELECT "DAV:href", 
+              "urn:schemas:httpmail:from", "urn:schemas:httpmail:to", "urn:schemas:mailheader:message-id",
+							"urn:schemas:httpmail:subject", "DAV:href", "urn:schemas:httpmail:date",
+							"urn:schemas:httpmail:importance", "urn:schemas:httpmail:hasattachment",
+							"urn:schemas:httpmail:textdescription", "urn:schemas:httpmail:htmldescription"
+					 FROM SCOPE('shallow traversal of "#{to_s}"')
+					 WHERE "DAV:ishidden" = false
+						 AND "DAV:isfolder" = false
+						 AND "DAV:contentclass" = 'urn:content-classes:message'
+            </D:sql>
+				</D:searchrequest>
+DABODY
+      
+      response = DavSearchRequest.execute(@credentials, :body => body)
+      
+      mail_messages = []
+      xpath_query = "//a:propstat[a:status/text() = 'HTTP/1.1 200 OK']/a:prop"
+      Document.new(response.body).elements.each(xpath_query) do |m| 
+        mail_messages << Message.new(@credentials, m)
+      end
+      
+      return mail_messages
+    end
+    
+    def self.join(*args)
+      args.collect { |f| f.to_s.ensure_ends_with('/') }.to_s.squeeze('/')
+    end
+    
+    def folders
+      @folders ||= get_folders
+    end
+    
+    def subfolder_exist?(folder)
+      folders.include? normalize_folder_name(folder)    
+    end
+    
+    def to_s
+      Folder.join(@parent, @folder)
+    end
+    
+    private
+    def normalize_folder_name(folder)
+      folder.to_s.tr('- ', '_').squeeze('_').downcase
+    end
+    
+    def get_folders
+      request_body = <<DA_QUERY
+    				<?xml version="1.0"?>
+    				<D:searchrequest xmlns:D = "DAV:">
+    					 <D:sql>
+    					 SELECT "DAV:displayname"
+    					 FROM SCOPE('shallow traversal of "#{to_s}"')
+    					 WHERE "DAV:ishidden" = false
+                           AND "DAV:isfolder" = true
+    					 </D:sql>
+    				</D:searchrequest>
+DA_QUERY
+      
+      response = DavSearchRequest.execute(@credentials, :body => request_body)
+      
+      folders = []
+      
+      # iterate through folders query and add each normalized name to the folders array.
+      xpath_query = "//a:propstat[a:status/text() = 'HTTP/1.1 200 OK']/a:prop"
+      Document.new(response.body).elements.each(xpath_query) do |m| 
+        folders << normalize_folder_name(m.elements['a:displayname'].text)
+      end
+      
+      return folders
+    end
+  end
+end

data/lib/rexchange/message.rb

@@ -0,0 +1,43 @@
+require 'rexml/document'
+require 'ostruct'
+require 'rexchange/dav_move_request'
+
+module RExchange
+  class Message
+    include REXML
+    include Enumerable
+    
+    attr_accessor :attributes  
+    
+    def [](key)
+      return @attributes[key]
+    end
+    
+    def method_missing(sym, *args)
+      return @attributes[sym.to_s] if @attributes.include?(sym.to_s)
+    end
+    
+    def body
+      @attributes['textdescription'] || @attributes['htmldescription']
+    end
+    
+    def initialize(session, dav_property_node)
+      @attributes = {}
+      @session = session
+      
+      dav_property_node.elements.each do |element|
+        @attributes[element.name.tr('-', '_')] = element.text
+      end
+      
+      return self    
+    end
+    
+    def move_to(folder)
+      source = URI.parse(self.href).path
+      destination = @session.uri.path.ensure_ends_with('/') + folder.ensure_ends_with('/') + source.split('/').last
+      
+      DavMoveRequest.execute(@session, source, destination)
+    end
+    
+  end
+end

data/lib/rexchange/session.rb

@@ -0,0 +1,34 @@
+require 'uri'
+require 'rexchange/folder'
+require 'rexchange/credentials'
+
+module RExchange 
+
+  class Session < Folder
+    
+    # Creates a Credentials instance to pass to subfolders
+    # === Example
+    #   uri = 'https://mydomain.com/exchange/demo'
+    #   options = { :user => 'test', :password => 'random' }
+    # 
+    #   RExchange::Session.new(uri, options) do |mailbox|
+    #     mailbox.test.each do |message|
+    #       puts message.subject
+    #     end
+    #   end
+    def initialize(uri, options = {})
+    
+      @credentials = Credentials.new(uri, options)
+      @parent = @credentials.uri.path
+      @folder = ''
+      
+      if block_given?
+        yield self
+      else
+        return self
+      end
+    end
+      
+  end 
+
+end

data/test/functional.rb

@@ -0,0 +1,28 @@
+require 'test/unit'
+require 'rexchange'
+
+class FunctionalTests < Test::Unit::TestCase
+  
+  def setup
+  end
+  
+  def teardown
+  end
+  
+  # Ok, so it's not a real test, but I needed to get started,
+  # and get rid of console scripts.
+  def test_no_exceptions
+    
+    uri = "https://#{ENV['rexchange_test_server']}/exchange/#{ENV['rexchange_test_mailbox']}/"
+    options = { :user => ENV['rexchange_test_user'], :password => ENV['rexchange_test_password'] }
+
+    RExchange::open(uri, options) do |mailbox|
+      mailbox.inbox.each do |message|
+        puts message.body
+      end
+      
+      mailbox.folders.each { |folder| puts folder }
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: rexchange
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+date: 2006-01-27
+summary: "A simple wrapper around Microsoft Exchange Server's WebDAV API"
+require_paths: 
+  - lib
+email: ssmoot@gmail.com; bauer.mail@gmail.com
+homepage: http://substantiality.net
+rubyforge_project: rexchange
+description: "Connect, browse, and iterate through folders and messages on an Exchange Server"
+autorequire: rexchange
+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: ruby
+authors: 
+  - Sam Smoot
+  - Scott Bauer
+files: 
+  - README
+  - CHANGELOG
+  - RAKEFILE
+  - lib/rexchange.rb
+  - lib/rexchange/credentials.rb
+  - lib/rexchange/dav_move_request.rb
+  - lib/rexchange/dav_search_request.rb
+  - lib/rexchange/exchange_request.rb
+  - lib/rexchange/extensions.rb
+  - lib/rexchange/folder.rb
+  - lib/rexchange/message.rb
+  - lib/rexchange/session.rb
+  - test/functional.rb
+test_files: []
+rdoc_options: 
+  - "--line-numbers"
+  - "--inline-source"
+  - "--main"
+  - README
+extra_rdoc_files: 
+  - README
+  - CHANGELOG
+  - RAKEFILE
+executables: []
+extensions: []
+requirements: 
+  - none
+dependencies: []