viewpoint 0.0.5 → 0.1.0

data/README

@@ -3,67 +3,106 @@
 --------------------------------------------------------------------------
 This program attempts to create a client access library for Exchange Web
 Services (EWS) in Ruby.
---------------------------------------------------------------------------
-TO USE:
-require 'rubygems'
-require 'viewpoint'
-# See REQUIRED GEMS below
 
-REQUIRED GEMS:
-
-# Current SOAP4R ( http://dev.ctor.org/soap4r )
-gem install -r soap4r
-# NTLM isn't an automatic dependency so you may need this if you are having issues.
-gem install -r rubyntlm
+!!!CAUTION!!!  This is currently BETA code and has changed dramatically from
+the original version of Viewpoint which was based on Soap4r.  This version
+has essentially been gutted and written on top of Handsoap.  Development
+has been much more flexible, but the interface to Viewpoint has changed
+quite a bit.  I have tried to write good code comments and I will keep
+enhancing this.  I will also try and post examples on my blog as I write
+them or they are asked for.
 
+BLOG:  http://distributed-frostbite.blogspot.com/
+Add me in LinkedIn:  http://www.linkedin.com/in/danwanek
 
-# iCalendar
-gem install -r icalendar
+--------------------------------------------------------------------------
+MAJOR CHANGES TO THE FIRST VERSION:
 
-CONFIGURATION:
-Configure your user/pass and EWS endpoint in lib/soap/viewpoint.conf
-or $HOME/.viewpointrc.  If the file $HOME/.viewpointrc exists it takes
-presidence.  See the sample in lib/soap/viewpoint.conf for how this
-file should be configured.
+New SOAP backend
+  Viewpoint now uses Handsoap as its back-end instead of soap4r.  While
+  soap4r does some very nice things for you automatically, it ends up
+  making your code base fairly large and it complicates any customizations
+  that you might want to make.  One example is adding custom headers. Soap4r
+  required you to create a subclass to use as a sort of hook. I can do the
+  same thing in Handsoap with a one-liner in the services #on_create_document
+  method.
 
+Models are completely rewritten
+  The models are completely new and not backward compatible with the old
+  version of Viewpoint.  Some of the methods still exist, but don't count
+  on them.  I've tried to make this version much more extensible than the
+  last.
 
-Running Examples:
-To run the FuseFS example you need the 'fusefs' gem
+Delegate access is supported
+  One thing that was often asked for, but missing from the previous version
+  was delegate access to mailboxes and calendars.  This is now supported via
+  the 'act_as' parameter to the GenericFolder::get_folder method. For example:
+  ofolder = Folder.get_folder(:inbox,'otheruser@test.com')
+  If your user has delegate access to the Inbox for otheruser@test.com this
+  operation will retrieve their inbox and allow you to manipulate it as you
+  would with your own Inbox.
 
+  There is also some support for manipulation of delegate access itself via
+  the methods MailboxUser#add_delegate!, MailboxUser#update_delegate!, and 
+  MailboxUser#get_delegate_info.
 
-******************** EXAMPLES *********************
-# In the following examples the following are used:
-# "item" is a type of Viewpoint::Item
-# "folder" is a type of Viewpoint::Folder
-# "new_folder" is a type of Viewpoint::Folder
+Misc other changes
+  Since it's a complete rewrite there are tons of other changes that you'll
+  notice.  I've tried to keep the code comments coming so stay tuned to the
+  API docs for library information.  I'll also be posting more examples to
+  my blog.
 
-# === Convert your Exchange Calendar to a Icalendar::Calendar object ===
+--------------------------------------------------------------------------
+TO USE:
 require 'rubygems'
 require 'viewpoint'
-vp = Viewpoint::ExchWebServ.instance
-vp.authenticate
-vp.find_folders
-cal = vp.get_folder("Calendar")
-ical = cal.to_ical
-puts ical.to_ical
+# See REQUIRED GEMS below
+
+REQUIRED GEMS:
+
+# Handsoap (Thanks jrun for pointing me this way!)
+gem install -r handsoap
+# Nokogiri XML Parser
+gem install -r nokogiri
+# HttpClient
+gem install -r httpclient
+# NTLM Library
+gem install -r rubyntlm
 
-# === Get a listing of todays messages ===
-# See test/test_client.rb
+# iCalendar (still forthcoming in this release)
+gem install -r icalendar
 
-# === Moving an item ===
-item.move_to!(new_folder)
+--------------------------------------------------------------------------
+DESIGN GOALS/GUIDELINES:
 
-# === Deleting an item ===
-item.delete!
-item.recycle!   # Move to "Deleted Items"
+  1. The SOAP back-end should not know about the Model.
+    I went around and around on this one for awhile.  There are some
+    simplicity advantages to creating Model objects within the SOAP
+    responses, but I ultimately decided against it so that one could use
+    the SOAP back-end without the Model.  Essentially the SOAP classes
+    pass back a Hash that the Model uses to create its own objects.
 
+  2. The use of Hashes is not a crime.
+    While some people decidedly do not like Hashes and believe complex
+    hashing should be in the form of objects, there are some instances
+    where hashing is just plain simpler and flexible.  To that end, I use
+    hashes pretty extensively in Viewpoint, both for objects being passed
+    to the SOAP back-end and returned from it.
+
+  3. Follow EWS naming conventions where it makes sense.
+    I try and follow the naming conventions of the Exchange Web Service
+    operations as much as it makes sense.  There are some things howerver
+    where they do not and I have deviated somewhat.  For example,
+    an instance method named delete_folder doesn't make much sense, but
+    an instance method named delete! is pretty clear what it deletes.
 
 --------------------------------------------------------------------------
-DISCLAIMER:  I am by no means a Ruby or EWS expert.  There may be better
-means of doing what I am attempting to do.  If you see something that
-could be done better or would like to help out in the development of this
-code please feel free to clone the 'git' repository:
-git clone git://github.com/zenchild/Viewpoint-for-MS-Exchange.git
+DISCLAIMER:  If you see something that could be done better or would like
+to help out in the development of this code please feel free to clone the
+'git' repository and send me patches:
+git clone git://github.com/zenchild/Viewpoint.git
 or add an issue on GitHub:
-http://github.com/zenchild/Viewpoint-for-MS-Exchange/issues
+http://github.com/zenchild/Viewpoint/issues
+
+Cheers!
 --------------------------------------------------------------------------

data/Rakefile

@@ -1,6 +1,7 @@
 require 'rubygems'
 require 'rake/clean'
 require 'rake/gempackagetask'
+require 'date'
 
 CLEAN.include("pkg")
 CLEAN.include("doc")
@@ -18,19 +19,20 @@ GEMSPEC = Gem::Specification.new do |gem|
 
   gem.summary = "A Ruby client access library for Microsoft Exchange Web Services (EWS)"
   gem.description	= <<-EOF
-  	A Ruby client access library for Microsoft Exchange Web Services (EWS).  It is a work in progress.  Methods are still being added from the EWS API docs.  Please see them for further information: http://msdn.microsoft.com/en-us/library/bb204119.aspx
+  	A Ruby client access library for Microsoft Exchange Web Services (EWS).  Examples can be found here: http://distributed-frostbite.blogspot.com
   EOF
 
   gem.files = `git ls-files`.split(/\n/)
   gem.require_path = "lib"
-  gem.rdoc_options	= %w(-x wsdl/ -x test/ -x examples/)
+  gem.rdoc_options	= %w(-x test/ -x examples/)
   gem.extra_rdoc_files = %w(README COPYING.txt)
 
   gem.required_ruby_version	= '>= 1.8.7'
-  gem.add_runtime_dependency  'soap4r', '>=1.5.8'
+  gem.add_runtime_dependency  'handsoap'
+  gem.add_runtime_dependency  'nokogiri'
+  gem.add_runtime_dependency  'httpclient'
+  gem.add_runtime_dependency  'rubyntlm'
   gem.add_runtime_dependency  'icalendar'
-  gem.add_runtime_dependency  'rubyntlm', '>=0.1.1'
-  gem.post_install_message	= "Don't forget to create .viewpointrc.  See README"
 end
  
 Rake::GemPackageTask.new(GEMSPEC) do |pkg|

data/TODO

@@ -0,0 +1,6 @@
+
+- Automate "deepening" of Model objects by over-riding method_missing
+  … if object.is_shallow? && all_methods.index(method)
+      deepen!
+    else
+      raise the NoMethod error

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.1.0

data/lib/exceptions/exceptions.rb

@@ -0,0 +1,34 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+#
+# This file is part of Viewpoint.
+# 
+# Viewpoint is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# Viewpoint is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+module Viewpoint
+  module EWS
+
+    # Generic Ews Error
+    class EwsError < StandardError
+    end
+
+    # Raised when a user tries to query a folder subscription after the
+    # subscription has timed out.
+    class EwsSubscriptionTimeout < StandardError
+    end
+
+  end # EWS
+end # Viewpoint
+ 

data/lib/extensions/string.rb

@@ -0,0 +1,37 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+#
+# This file is part of Viewpoint.
+# 
+# Viewpoint is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# Viewpoint is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+# Custom extensions to the class String
+class String
+  # Change CamelCased strings to ruby_cased strings
+  # It uses the lookahead assertion ?=  In this case it basically says match
+  # anything followed by a capital letter, but not the capital letter itself.
+  # @see http://www.pcre.org/pcre.txt The PCRE guide for more details
+  def ruby_case
+    self.split(/(?=[A-Z])/).join('_').downcase
+  end
+
+  # Change a ruby_cased string to CamelCased
+  def camel_case
+    self.split(/_/).map { |i|
+      i.sub(/^./) { |s| s.upcase }
+    }.join
+  end
+end # String

data/lib/model/calendar_folder.rb

@@ -0,0 +1,45 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+#
+# This file is part of Viewpoint.
+# 
+# Viewpoint is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# Viewpoint is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+module Viewpoint
+  module EWS
+    class CalendarFolder < GenericFolder
+
+      # initialize with an item of CalendarFolderType
+      def initialize(folder)
+        super(folder)
+
+        # @todo Handle:
+        #   <SharingEffectiveRights/>
+      end
+
+      # Find Items
+      # @see GenericFolder#find_items
+      def find_items(start_date = nil, end_date = nil)
+        opts ||= {}
+        if(!start_date.nil? && !end_date.nil?)
+          opts = {:calendar_view => {:max_entries_returned => 256, :start_date => start_date, :end_date => end_date}}
+        end
+        super(opts)
+      end
+
+    end # CalendarFolder
+  end # EWS
+end # Viewpoint

data/lib/model/calendar_item.rb

@@ -0,0 +1,145 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
+#
+#
+# This file is part of Viewpoint.
+# 
+# Viewpoint is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# Viewpoint is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+module Viewpoint
+  module EWS
+    class CalendarItem < Message
+
+      # This is a class method that creates a new CalendarItem in the Exchange Data Store.
+      # @param [Hash] item A Hash of values based on values found here:
+      #   http://msdn.microsoft.com/en-us/library/aa564765.aspx
+      # @param [String, Symbol] folder_id The folder to create this item in. Either a
+      #   DistinguishedFolderId (must me a Symbol) or a FolderId (String)
+      # @param [String] send_invites "SendToNone/SendOnlyToAll/SendToAllAndSaveCopy"
+      #   See:  http://msdn.microsoft.com/en-us/library/aa565209.aspx
+      # @example Typical Usage
+      #   item = { :subject => {:text => 'Planning'},
+      #     :body => {:body_type => 'Text', :text => 'This is a test'},
+      #     :start => {:text => '2010-07-29T14:00:00'},
+      #     :end => {:text => '2010-07-29T15:00:00'},
+      #     :is_all_day_event => {:text => 'false'},
+      #     :location => {:text => 'Room 234'},
+      #     :required_attendees => {:attendee => {:mailbox => {:email_address => {:text => 'test@test.com'}}}}
+      #   }
+      # @example Minimal Usage
+      #   item = { :subject => {:text => 'Planning'},
+      #     :start => {:text => '2010-07-29T14:00:00'},
+      #     :end => {:text => '2010-07-29T15:00:00'}
+      #   }
+      def self.create_item_from_hash(item, folder_id = :calendar, send_invites = 'SendToAllAndSaveCopy')
+        conn = Viewpoint::EWS::EWS.instance
+        resp = conn.ews.create_calendar_item(folder_id, item, send_invites)
+        if(resp.status == 'Success')
+          resp = resp.items.shift
+          self.new(resp[resp.keys.first])
+        else
+          raise EwsError, "Could not create CalendarItem. #{resp.code}: #{resp.message}"
+        end
+      end
+
+      # Create a new CalendarItem.
+      # @param [DateTime] v_start The date and time when the CalendarItem begins
+      # @param [DateTime] v_end The date and time when the CalendarItem ends
+      # @param [String] subject The subject of this Item
+      # @param [String,optional] body The body of this object
+      # @param [String,optional] location The location where this calendar item will ocurr
+      # @param [Array<String>,optional] required_attendees An Array of e-mail addresses of required attendees
+      # @param [Array<String>,optional] optional_attendees An Array of e-mail addresses of optional attendees
+      # @param [Array<String>,optional] resources An Array of e-mail addresses of resources
+      def self.create_item(v_start, v_end, subject, body = nil, location = nil, required_attendees=[], optional_attendees=[], resources=[])
+        item = {}
+        item[:start] = {:text => v_start.to_s}
+        item[:end] = {:text => v_end.to_s}
+        item[:subject] = {:text => subject}
+        item[:body] = {:text => body, :body_type => 'Text'} unless body.nil?
+        item[:location] = {:text => location} unless location.nil?
+        required_attendees.each do |a|
+          item[:required_attendees] = [] unless item[:required_attendees].is_a?(Array)
+          item[:required_attendees] << {:attendee => {:mailbox => {:email_address => {:text => a}}}}
+        end
+        optional_attendees.each do |a|
+          item[:optional_attendees] = [] unless item[:optional_attendees].is_a?(Array)
+          item[:optional_attendees] << {:attendee => {:mailbox => {:email_address => {:text => a}}}}
+        end
+        resources.each do |a|
+          item[:resources] = [] unless item[:resources].is_a?(Array)
+          item[:resources] << {:attendee => {:mailbox => {:email_address => {:text => a}}}}
+        end
+        puts item
+        self.create_item_from_hash(item)
+      end
+
+      # Initialize an Exchange Web Services item of type CalendarItem
+      def initialize(ews_item)
+        super(ews_item)
+      end
+      
+      # Delete this item
+      # @param [Boolean] soft Whether or not to do a soft delete.  By default EWS will do a 
+      #   hard delete of this item.  See the MSDN docs for more info:
+      #   http://msdn.microsoft.com/en-us/library/aa562961.aspx
+      # @param [String] cancel_type "SendToNone/SendOnlyToAll/SendToAllAndSaveCopy"
+      #   Default is SendOnlyToAll
+      # @return [Boolean] Whether or not the item was deleted
+      # @todo Add exception handling for failed deletes
+      #
+      def delete!(soft=false, cancel_type='SendOnlyToAll')
+        deltype = soft ? 'SoftDelete' : 'HardDelete'
+        resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], deltype, cancel_type)
+        self.clear_object!
+        resp.status == 'Success'
+      end
+
+      # Delete this item by moving it to the Deleted Items folder
+      # @see  http://msdn.microsoft.com/en-us/library/aa562961.aspx
+      # @return [Boolean] Whether or not the item was deleted
+      # @todo Add exception handling for failed deletes
+      def recycle!(cancel_type='SendOnlyToAll')
+        resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], 'MoveToDeletedItems', cancel_type)
+        self.clear_object!
+        resp.status == 'Success'
+      end
+
+
+
+      private
+
+      def init_methods
+        super
+        define_str_var :calendar_item_type, :duration, :time_zone, :when, :location
+        define_str_var :legacy_free_busy_status, :my_response_type, :meeting_workspace_url, :net_show_url
+        define_int_var :adjacent_meeting_count, :appointment_sequence_number, :appointment_state
+        define_int_var :conference_type, :conflicting_meeting_count
+        define_mbox_user :organizer
+        define_bool_var :is_all_day_event, :is_cancelled, :is_meeting, :is_online_meeting, :is_recurring
+        define_bool_var :allow_new_time_proposal, :meeting_request_was_sent
+        define_datetime_var :appointment_reply_time, :start, :end, :original_start
+
+        # @todo Handle:
+        #   <AdjacentMeetings/> <ConflictingMeetings/> <DeletedOccurrences/>
+        #   <FirstOccurrence/> <LastOccurrence/> <ModifiedOccurrences/>
+        #   <StartTimeZone/> <EndTimeZone/> <MeetingTimeZone/>
+        #   <OptionalAttendees/> <RequiredAttendees/> <Resources/>
+        #   <Recurrence/>
+      end
+
+    end # CalendarItem
+  end # EWS
+end # Viewpoint