viewpoint 0.1.0 → 0.1.1

data/TODO

@@ -4,3 +4,5 @@
       deepen!
     else
       raise the NoMethod error
+
+- Clean-up exceptions.  There is exception raising in the Model that will never ocurr because it is already being checked for in the Parser

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/model/generic_folder.rb

@@ -57,7 +57,7 @@ module Viewpoint
       #   or a FolderId (String)
       # @param [String] traversal Shallow/Deep/SoftDeleted
       # @return [Array] Returns an Array of Folder or subclasses of Folder
-      def self.find_folders(root = :root, traversal = 'Shallow')
+      def self.find_folders(root = :msgfolderroot, traversal = 'Shallow')
         resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal )
         if(resp.status == 'Success')
           folders = []
@@ -71,6 +71,39 @@ module Viewpoint
         end
       end
 
+      # Return a list of folder names
+      # @return [Array<String>] Return an Array of folder names.
+      def self.folder_names
+        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder([:msgfolderroot], 'Shallow')
+        if(resp.status == 'Success')
+          flds = []
+          resp.items.each do |f|
+            flds << f[f.keys.first][:display_name][:text]
+          end
+          flds
+        else
+          raise EwsError, "Could not retrieve folders. #{resp.code}: #{resp.message}"
+        end
+      end
+
+      # Gets a folder by name.  This name must match the folder name exactly.
+      # @param [String] name The name of the folder to fetch.
+      def self.get_folder_by_name(name)
+        # For now the :field_uRI and :field_uRI_or_constant must be in an Array for Ruby 1.8.7 because Hashes
+        # are not positional at insertion until 1.9
+        restr = {:restriction =>
+          {:is_equal_to => 
+            [{:field_uRI => {:field_uRI=>'folder:DisplayName'}}, {:field_uRI_or_constant =>{:constant => {:value=>name}}}]}}
+        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder([:msgfolderroot], 'Shallow', {:base_shape => 'Default'}, restr)
+        if(resp.status == 'Success')
+          f = resp.items.first
+          f_type = f.keys.first.to_s.camel_case
+          eval "#{f_type}.new(f[f.keys.first])"
+        else
+          raise EwsError, "Could not retrieve folder. #{resp.code}: #{resp.message}"
+        end
+      end
+
       attr_accessor :folder_id, :change_key, :parent_id
       attr_reader :subscription_id, :watermark, :sync_state
       alias :id :folder_id

data/lib/model/item.rb

@@ -39,7 +39,23 @@ module Viewpoint
         self.new(resp[resp.keys.first])
       end
 
-      attr_reader :item_id, :body_type
+      # Add attachments to the passed in ParentId
+      # @param [String,Hash] parent_id Either a String ItemId or a Hash ItemId with a ChangeKey
+      # @option parent_id [String] :id The Id
+      # @option parent_id [String] :change_key The ChangeKey
+      # @param [Array<File>] attachments An Array of File objects to read in.
+      def self.add_attachments(parent_id, attachments)
+        conn = Viewpoint::EWS::EWS.instance
+        b64attach = []
+        attachments.each do |a|
+          b64attach << {:name => {:text =>(File.basename a.path)}, :content => {:text => Base64.encode64(a.read)}}
+        end
+        resp = conn.ews.create_attachment(parent_id, b64attach) 
+        (resp.status == 'Success') || (raise EwsError, "Could not create attachments. #{resp.code}: #{resp.message}")
+        {:id => resp.items.first[:attachment_id][:root_item_id], :change_key => resp.items.first[:attachment_id][:root_item_change_key]}
+      end
+
+      attr_reader :item_id, :change_key, :body_type
       alias :id :item_id
 
       # Initialize an Exchange Web Services item
@@ -50,6 +66,7 @@ module Viewpoint
         @ews_item = ews_item
         @shallow = shallow
         @item_id = ews_item[:item_id][:id]
+        @change_key = ews_item[:item_id][:change_key]
 
         init_methods
       end
@@ -65,6 +82,37 @@ module Viewpoint
         init_methods
       end
 
+      # Move this item to a new folder
+      # @param [String,Symbol,GenericFolder] new_folder The new folder to move it to. This should
+      #   be a subclass of GenericFolder, a DistinguishedFolderId (must me a Symbol) or a FolderId (String)
+      def move!(new_folder)
+        new_folder = new_folder.id if new_folder.kind_of?(GenericFolder)
+        resp = (Viewpoint::EWS::EWS.instance).ews.move_item([@item_id], new_folder)
+        if(resp.status == 'Success')
+          @item_id = resp.items.first[resp.items.first.keys.first][:item_id][:id]
+          @change_key = resp.items.first[resp.items.first.keys.first][:item_id][:change_key]
+          true
+        else
+          raise EwsError, "Could not move item. #{resp.code}: #{resp.message}"
+        end
+      end
+
+      # Copy this item to a new folder
+      # @param [String,Symbol,GenericFolder] new_folder The new folder to move it to. This should
+      #   be a subclass of GenericFolder, a DistinguishedFolderId (must me a Symbol) or a FolderId (String)
+      # @return [Item] The Item object of the copy
+      def copy(new_folder)
+        new_folder = new_folder.id if new_folder.kind_of?(GenericFolder)
+        resp = (Viewpoint::EWS::EWS.instance).ews.copy_item([@item_id], new_folder)
+        if(resp.status == 'Success')
+          item = resp.items.first
+          i_type = item.keys.first.to_s.camel_case
+          return(eval "#{i_type}.new(item[item.keys.first])")
+        else
+          raise EwsError, "Could not copy item. #{resp.code}: #{resp.message}"
+        end
+      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:
@@ -75,7 +123,7 @@ module Viewpoint
         deltype = soft ? 'SoftDelete' : 'HardDelete'
         resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], deltype)
         self.clear_object!
-        resp.status == 'Success'
+        (resp.status == 'Success') || (raise EwsError, "Could not delete message. #{resp.code}: #{resp.message}")
       end
 
       # Delete this item by moving it to the Deleted Items folder
@@ -85,7 +133,7 @@ module Viewpoint
       def recycle!
         resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], 'MoveToDeletedItems')
         self.clear_object!
-        resp.status == 'Success'
+        (resp.status == 'Success') || (raise EwsError, "Could not recycle message. #{resp.code}: #{resp.message}")
       end
 
       private

data/lib/model/message.rb

@@ -29,9 +29,11 @@ module Viewpoint
       # @param [Array] to_recipients An array of e-mail addresses to send to
       # @param [Array] cc_recipients An array of e-mail addresses to send to
       # @param [Array] bcc_recipients An array of e-mail addresses to send to
-      # @return [true] Returns true on successful send or it raises an error with
-      #   a message stating why the e-mail could not be sent.
-      def self.send(subject, body, to_recipients, cc_recipients=[], bcc_recipients=[])
+      # @param [Array<File>] file_attachments An array of File objects to read data from that
+      #   will attach to this message.
+      # @return [Message,true] Returns true if the message is sent, if draft is true it will return the Message object
+      #   or it raises an error with a message stating why the e-mail could not be sent.
+      def self.send(subject, body, to_recipients, cc_recipients=[], bcc_recipients=[], file_attachments=nil, draft=false)
         item = {}
         item[:subject] = {:text => subject}
         item[:body] = {:text => body, :body_type => 'Text'} unless body.nil?
@@ -42,15 +44,24 @@ module Viewpoint
         cc_recipients.each do |a|
           item[:cc_recipients] = [] unless item[:cc_recipients].is_a?(Array)
           item[:cc_recipients] << {:mailbox => {:email_address => {:text => a}}}
-        end
+        end unless cc_recipients.nil?
         bcc_recipients.each do |a|
           item[:bcc_recipients] = [] unless item[:bcc_recipients].is_a?(Array)
           item[:bcc_recipients] << {:mailbox => {:email_address => {:text => a}}}
-        end
+        end unless bcc_recipients.nil?
         
         conn = Viewpoint::EWS::EWS.instance
-        resp = conn.ews.create_message_item(:sentitems, item, 'SendAndSaveCopy')
-        (resp.status == 'Success') || (raise EwsError, "Could not retrieve item. #{resp.code}: #{resp.message}")
+        resp = conn.ews.create_message_item(:drafts, item, 'SaveOnly')
+        (resp.status == 'Success') || (raise EwsError, "Could not send message. #{resp.code}: #{resp.message}")
+        msg_key = resp.items.first.keys.first
+        msg_id = resp.items.first[msg_key][:item_id]
+        msg_id = add_attachments(msg_id, file_attachments) unless file_attachments.nil?
+        if !draft
+          resp = conn.ews.send_item([msg_id])
+          (resp.status == 'Success') || (raise EwsError, "Could not send message. #{resp.code}: #{resp.message}")
+        else
+          self.new({:item_id => msg_id})
+        end
       end
 
       # Initialize an Exchange Web Services item of type Message
@@ -58,6 +69,18 @@ module Viewpoint
         super(ews_item)
       end
 
+      def headers
+        deepen! if @shallow
+        return @headers if defined?(@headers) && !@headers.empty?
+        @headers = {}
+        # @todo When ruby 1.9 becomes more pervasive the Enumerator#each_with_object
+        #@headers ||= @ews_item[:internet_message_headers][:internet_message_header].each_with_object({}) do |h,obj|
+        @ews_item[:internet_message_headers][:internet_message_header].each do |h|
+          @headers[h[:header_name]] = h[:text]
+        end
+        @headers
+      end
+
       private
 
       def init_methods

data/lib/soap/handsoap/builders/ews_build_helpers.rb

@@ -52,19 +52,42 @@ module Viewpoint
           end
         end
 
-
         # For now this is the same as folder_ids! so just use that method
         def parent_folder_ids!(node, folder_ids)
           folder_ids!(node, folder_ids, nil, "#{NS_EWS_MESSAGES}:ParentFolderIds")
         end
 
+        # @see http://msdn.microsoft.com/en-us/library/aa565020.aspx
+        def to_folder_id!(node, folder_id)
+          node.add("#{NS_EWS_MESSAGES}:ToFolderId") do |tfi|
+            folder_id!(tfi, folder_id)
+          end
+        end
 
+        # Create the ItemIds Element
+        # @param [Element] node The node we are adding Mailbox elements to.
+        # @param [Array] item_ids The item ids to add in.
         def item_ids!(node, item_ids)
           node.add("#{NS_EWS_MESSAGES}:ItemIds") do |ids|
             item_ids.each do |id|
-              ids.add("#{NS_EWS_TYPES}:ItemId") do |iid|
-                iid.set_attr('Id',id)
-              end
+              item_id!(ids,id)
+            end
+          end
+        end
+
+        # Builds an ItemId element out of a String or Hash object
+        # @param [Element] node The node we are adding Mailbox elements to.
+        # @param [String,Hash] item_id The id of the Item.  If this is a Hash
+        #   it should contain the Id and the ChangeKey.
+        # @option item_ids [String] :id The item Id
+        # @option item_ids [String] :change_key The ChangeKey
+        def item_id!(node, item_id, element_name="#{NS_EWS_TYPES}:ItemId")
+          node.add(element_name) do |iid|
+            if(item_id.is_a?(String))
+              iid.set_attr('Id',item_id)
+            else
+              iid.set_attr('Id',item_id[:id])
+              iid.set_attr('ChangeKey',item_id[:change_key])
             end
           end
         end
@@ -94,19 +117,10 @@ module Viewpoint
 
         def saved_item_folder_id!(node, folder_id)
           node.add("#{NS_EWS_MESSAGES}:SavedItemFolderId") do |sfid|
-            if( folder_id.is_a?(Symbol) )
-              # @todo add change_key support to DistinguishedFolderId
-              sfid.add("#{NS_EWS_TYPES}:DistinguishedFolderId") do |df|
-                df.set_attr('Id', folder_id.to_s)
-              end
-            else
-              # @todo add change_key support to FolderId
-              sfid.add("#{NS_EWS_TYPES}:FolderId",folder_id)
-            end
+            folder_id!(sfid, folder_id)
           end
         end
 
-
         # @todo This only supports the FieldURI extended property right now
         def folder_shape!(node, folder_shape)
           node.add("#{NS_EWS_MESSAGES}:FolderShape") do |fshape|
@@ -284,6 +298,17 @@ module Viewpoint
           node.add("#{NS_EWS_MESSAGES}:SyncState", sync_state)
         end
 
+        # @todo Add support of ItemAttachment
+        def attachments!(node, files, items)
+          node.add("#{NS_EWS_MESSAGES}:Attachments") do |att|
+            files.each do |f|
+              att.add("#{NS_EWS_TYPES}:FileAttachment") do |fatt|
+                add_hierarchy!(fatt, f)
+              end
+            end
+          end
+        end
+
         # Add a hierarchy of elements from hash data
         # @example Hash to XML
         #   {:this => {:text =>'that'},'top' => {:id => '32fss', :text => 'TestText', {'middle' => 'bottom'}}}

data/lib/soap/handsoap/ews_service.rb

@@ -29,6 +29,7 @@ module Viewpoint
   module EWS
     module SOAP
       class ExchangeWebService < Handsoap::Service
+        include Viewpoint::EWS::SOAP
 
         SOAP_ACTION_PREFIX = "http://schemas.microsoft.com/exchange/services/2006/messages"
 
@@ -133,8 +134,12 @@ module Viewpoint
           action = "#{SOAP_ACTION_PREFIX}/FindFolder"
           resp = invoke("#{NS_EWS_MESSAGES}:FindFolder", :soap_action => action) do |root|
             build!(root) do
+              restriction = opts.delete(:restriction)
               root.set_attr('Traversal', traversal)
               folder_shape!(root, folder_shape)
+              root.add("#{NS_EWS_MESSAGES}:Restriction") do |r|
+                add_hierarchy!(r, restriction)
+              end unless restriction.nil?
               parent_folder_ids!(root, parent_folder_ids)
             end
           end
@@ -245,8 +250,8 @@ module Viewpoint
         def delete_folder(folder_id, delete_type = 'MoveToDeletedItems')
           action = "#{SOAP_ACTION_PREFIX}/DeleteFolder"
           resp = invoke("#{NS_EWS_MESSAGES}:DeleteFolder", :soap_action => action) do |root|
-            root.set_attr('DeleteType', delete_type)
             build!(root) do
+              root.set_attr('DeleteType', delete_type)
               folder_id = (folder_id.is_a?(Array)) ? folder_id : [folder_id]
               folder_ids!(root, folder_id)
             end
@@ -481,36 +486,77 @@ module Viewpoint
           parse_update_item(resp)
         end
 
-        def send_item
+        # Used to send e-mail messages that are located in the Exchange store.
+        # @see http://msdn.microsoft.com/en-us/library/aa580238.aspx
+        # @param [Array<Hash>] item_ids An Array of item ids.  These item_ids should be a Hash of
+        #   :id and :change_key.
+        # @param [Boolean] save_item Save item after sending (Think sent-items)
+        # @param [String, Symbol,nil] saved_item_folder The folder to save this item in. Either a
+        #   DistinguishedFolderId (must me a Symbol) or a FolderId (String).  Just leave
+        #   it blank for the default :sentitems
+        def send_item(item_ids, save_item=true, saved_item_folder=nil)
           action = "#{SOAP_ACTION_PREFIX}/SendItem"
-          resp = invoke("#{NS_EWS_MESSAGES}:SendItem", :soap_action => action) do |send_item|
-            build_send_item!(send_item)
+          resp = invoke("#{NS_EWS_MESSAGES}:SendItem", :soap_action => action) do |root|
+            build!(root) do
+              root.set_attr('SaveItemToFolder', save_item)
+              item_ids!(root,item_ids)
+              saved_item_folder_id!(root,saved_item_folder) unless saved_item_folder.nil?
+            end
           end
-          parse_send_item(resp)
+          parse!(resp)
         end
 
-        def move_item
+        # Used to move one or more items to a single destination folder.
+        # @see http://msdn.microsoft.com/en-us/library/aa565781.aspx
+        # @param [Array] item_ids An Array of item ids
+        # @param [String, Symbol] folder_id either a DistinguishedFolderId
+        #   (must me a Symbol) or a FolderId (String)
+        def move_item(item_ids, folder_id)
           action = "#{SOAP_ACTION_PREFIX}/MoveItem"
-          resp = invoke("#{NS_EWS_MESSAGES}:MoveItem", :soap_action => action) do |move_item|
-            build_move_item!(move_item)
+          resp = invoke("#{NS_EWS_MESSAGES}:MoveItem", :soap_action => action) do |root|
+            build!(root) do
+              to_folder_id!(root, folder_id)
+              item_ids!(root, item_ids)
+            end
           end
-          parse_move_item(resp)
+          parse!(resp)
         end
 
-        def copy_item
+        # Copies items and puts the items in a different folder
+        # @see http://msdn.microsoft.com/en-us/library/aa565012.aspx
+        # @param [Array] item_ids An Array of item ids
+        # @param [String, Symbol] folder_id either a DistinguishedFolderId
+        #   (must me a Symbol) or a FolderId (String)
+        def copy_item(item_ids, folder_id)
           action = "#{SOAP_ACTION_PREFIX}/CopyItem"
-          resp = invoke("#{NS_EWS_MESSAGES}:CopyItem", :soap_action => action) do |copy_item|
-            build_copy_item!(copy_item)
+          resp = invoke("#{NS_EWS_MESSAGES}:CopyItem", :soap_action => action) do |root|
+            build!(root) do
+              to_folder_id!(root, folder_id)
+              item_ids!(root, item_ids)
+            end
           end
-          parse_copy_item(resp)
+          parse!(resp)
         end
 
-        def create_attachment
+        # Creates either an item or file attachment and attaches it to the specified item.
+        # @see http://msdn.microsoft.com/en-us/library/aa565877.aspx
+        # @param [String,Hash] parent_id The id of the Item.  If this is a Hash
+        #   it should contain the Id and the ChangeKey.
+        # @option parent_id [String] :id The item Id
+        # @option parent_id [String] :change_key The ChangeKey
+        # @param [Array<Hash>] files An Array of Base64 encoded Strings with an associated name
+        #   hash format= :name => <name>, :content => <Base64 encoded string>
+        # @param [Array] items Exchange Items to attach to this Item
+        # @todo Need to implement attachment of Item types
+        def create_attachment(parent_id, files = [], items = [])
           action = "#{SOAP_ACTION_PREFIX}/CreateAttachment"
-          resp = invoke("#{NS_EWS_MESSAGES}:CreateAttachment", :soap_action => action) do |create_attachment|
-            build_create_attachment!(create_attachment)
+          resp = invoke("#{NS_EWS_MESSAGES}:CreateAttachment", :soap_action => action) do |root|
+            build!(root) do
+              item_id!(root, parent_id, "#{NS_EWS_MESSAGES}:ParentItemId")
+              attachments!(root, files, items)
+            end
           end
-          parse_create_attachment(resp)
+          parse!(resp)
         end
 
         def delete_attachment
@@ -601,6 +647,9 @@ module Viewpoint
           parse!(resp)
         end
 
+        # Provides detailed information about the availability of a set of users, rooms, and resources
+        # within a specified time window.
+        # @see http://msdn.microsoft.com/en-us/library/aa564001.aspx
         def get_user_availability
           action = "#{SOAP_ACTION_PREFIX}/GetUserAvailability"
           resp = invoke("#{NS_EWS_MESSAGES}:GetUserAvailability", :soap_action => action) do |get_user_availability|
@@ -630,7 +679,6 @@ module Viewpoint
         # Private Methods (Builders and Parsers)
         private
 
-
         def build!(node, opts = {}, &block)
           EwsBuilder.new(node, opts, &block)
         end

data/lib/soap/handsoap/parsers/ews_parser.rb

@@ -99,6 +99,22 @@ module Viewpoint
           end
         end
 
+        def copy_item_response(opts)
+          if(@response_message.status == 'Success')
+            @response_message.items << xml_to_hash!((@response/"//#{NS_EWS_MESSAGES}:Items/*").first.native_element)
+          else
+            raise EwsError, "#{@response_message.code}: #{@response_message.message}"
+          end
+        end
+        
+        def move_item_response(opts)
+          if(@response_message.status == 'Success')
+            @response_message.items << xml_to_hash!((@response/"//#{NS_EWS_MESSAGES}:Items/*").first.native_element)
+          else
+            raise EwsError, "#{@response_message.code}: #{@response_message.message}"
+          end
+        end
+
         # @todo need to find out out to us XPath to get ItemId.  It doesn't seem to work now.
         def create_item_response(opts)
           if(@response_message.status == 'Success')
@@ -111,6 +127,28 @@ module Viewpoint
             raise EwsError, "#{@response_message.code}: #{@response_message.message}"
           end
         end
+        
+        def send_item_response(opts)
+          if(@response_message.status == 'Success')
+            items = []
+            (@response/"//#{NS_EWS_MESSAGES}:Items/*").each do |i|
+              items << xml_to_hash!(i.native_element)
+            end
+            @response_message.items = items
+          else
+            raise EwsError, "#{@response_message.code}: #{@response_message.message}"
+          end
+        end
+
+        def create_attachment_response(opts)
+          if(@response_message.status == 'Success')
+            att_id = (@response/"//#{NS_EWS_TYPES}:FileAttachment/*").last
+            att_id = xml_to_hash!(att_id.native_element)
+            @response_message.items = [att_id]
+          else
+            raise EwsError, "#{@response_message.code}: #{@response_message.message}"
+          end
+        end
 
         def sync_folder_items_response(opts)
           if(@response_message.status == 'Success')