viewpoint 0.1.8 → 0.1.9

data/VERSION

@@ -1 +1 @@
-0.1.8
+0.1.9

data/lib/exceptions/exceptions.rb

@@ -24,6 +24,10 @@ module Viewpoint
     class EwsError < StandardError
     end
 
+    # Raise when authentication/authorization issues occur.
+    class EwsLoginError < StandardError
+    end
+
     # Raised when a user tries to query a folder subscription after the
     # subscription has timed out.
     class EwsSubscriptionTimeout < StandardError

data/lib/model/calendar_folder.rb

@@ -22,27 +22,16 @@ module Viewpoint
   module EWS
     class CalendarFolder < GenericFolder
 
-      # Find Calendar subfolders of the passed root folder.  If no parameters are passed
-      # this method will search from the Root folder.
-      # @param [Str] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      # Find folders of type Task
+      # @see GenericFolder.find_folders
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
       #   or a FolderId (String)
       # @param [String] traversal Shallow/Deep/SoftDeleted
+      # @param [String] shape the shape to return IdOnly/Default/AllProperties
+      # @param [optional, String] folder_type an optional folder type to limit the search to like 'IPF.Task'
       # @return [Array] Returns an Array of Folder or subclasses of Folder
-      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default')
-        restr = {:restriction => 
-          {:is_equal_to => {:field_uRI => {:field_uRI=>'folder:FolderClass'},:field_uRI_or_constant=>{:constant => {:value => 'IPF.Appointment'}}}}
-        }
-        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape}, restr)
-        if(resp.status == 'Success')
-          folders = []
-          resp.items.each do |f|
-            f_type = f.keys.first.to_s.camel_case
-            folders << (eval "#{f_type}.new(f[f.keys.first])")
-          end
-          return folders
-        else
-          raise EwsError, "Could not retrieve folders. #{resp.code}: #{resp.message}"
-        end
+      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default', folder_type = 'IPF.Appointment')
+        super(root, traversal, shape, folder_type)
       end
 
 

data/lib/model/contact.rb

@@ -20,12 +20,48 @@
 
 module Viewpoint
   module EWS
+    # Represents a Contact Item in the Exchange datastore.
     class Contact < Item
 
+      # This is a class method that creates a new Contact in the Exchange Data Store.
+      # @param [Hash] item A Hash of values based on values found here:
+      #   http://msdn.microsoft.com/en-us/library/aa581315.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 = {
+      #     :file_as => {:text => 'Dan Wanek'},
+      #     :given_name => {:text => 'Dan Wanek'},
+      #     :company_name => {:text => 'Test Company'},
+      #     :email_addresses => [
+      #       {:entry => {:key => 'EmailAddress1', :text => 'myemail@work.com'}},
+      #       {:entry => {:key => 'EmailAddress2', :text => 'myemail@home.com'}}
+      #     ],
+      #     :physical_addresses => [
+      #       {:entry => {:key => 'Business', :sub_elements => {:street => {:text => '6343 N Baltimore'}, :city => {:text => 'Bismarck'}, :state => {:text => 'ND'} }}}
+      #     ],
+      #     :phone_numbers => [
+      #       {:entry => {:key => 'BusinessPhone', :text => '7012220000'}}
+      #     ],
+      #     :job_title => {:text => 'Systems Architect'}
+      #   }
+      # @example Minimal Usage
+      def self.create_item_from_hash(item, folder_id = :contacts)
+        conn = Viewpoint::EWS::EWS.instance
+        resp = conn.ews.create_contact_item(folder_id, item)
+        if(resp.status == 'Success')
+          resp = resp.items.shift
+          self.new(resp[resp.keys.first])
+        else
+          raise EwsError, "Could not create Contact. #{resp.code}: #{resp.message}"
+        end
+      end
+
+
+
       # Create a Contact in the Exchange Data Store
-      #
-      # @param [String] subject The task subject
-      # @param [String] body The task body
       def self.add_contact()
         item = {}
         

data/lib/model/contacts_folder.rb

@@ -22,6 +22,19 @@ module Viewpoint
   module EWS
     class ContactsFolder < GenericFolder
 
+      # Find folders of type Contact
+      # @see GenericFolder.find_folders
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      #   or a FolderId (String)
+      # @param [String] traversal Shallow/Deep/SoftDeleted
+      # @param [String] shape the shape to return IdOnly/Default/AllProperties
+      # @param [optional, String] folder_type an optional folder type to limit the search to like 'IPF.Task'
+      # @return [Array] Returns an Array of Folder or subclasses of Folder
+      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default', folder_type = 'IPF.Contact')
+        super(root, traversal, shape, folder_type)
+      end
+
+
       # initialize with an item of CalendarFolderType
       def initialize(folder)
         super(folder)

data/lib/model/folder.rb

@@ -24,27 +24,16 @@ module Viewpoint
     # This is the type of folder that mail messages will be found in.
     class Folder < GenericFolder
 
-      # Find Message subfolders of the passed root folder.  If no parameters are passed
-      # this method will search from the Root folder.
-      # @param [Str] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      # Find folders of type Folder (message folders)
+      # @see GenericFolder.find_folders
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
       #   or a FolderId (String)
       # @param [String] traversal Shallow/Deep/SoftDeleted
+      # @param [String] shape the shape to return IdOnly/Default/AllProperties
+      # @param [optional, String] folder_type an optional folder type to limit the search to like 'IPF.Task'
       # @return [Array] Returns an Array of Folder or subclasses of Folder
-      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default')
-        restr = {:restriction => 
-          {:is_equal_to => {:field_uRI => {:field_uRI=>'folder:FolderClass'},:field_uRI_or_constant=>{:constant => {:value => 'IPF.Note'}}}}
-        }
-        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape}, restr)
-        if(resp.status == 'Success')
-          folders = []
-          resp.items.each do |f|
-            f_type = f.keys.first.to_s.camel_case
-            folders << (eval "#{f_type}.new(f[f.keys.first])")
-          end
-          return folders
-        else
-          raise EwsError, "Could not retrieve folders. #{resp.code}: #{resp.message}"
-        end
+      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default', folder_type = 'IPF.Note')
+        super(root, traversal, shape, folder_type)
       end
 
 

data/lib/model/generic_folder.rb

@@ -62,9 +62,19 @@ module Viewpoint
       # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
       #   or a FolderId (String)
       # @param [String] traversal Shallow/Deep/SoftDeleted
+      # @param [String] shape the shape to return IdOnly/Default/AllProperties
+      # @param [optional, String] folder_type an optional folder type to limit the search to like 'IPF.Task'
       # @return [Array] Returns an Array of Folder or subclasses of Folder
-      def self.find_folders(root = :msgfolderroot, traversal = 'Shallow', shape = 'Default')
-        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape} )
+      def self.find_folders(root = :msgfolderroot, traversal = 'Shallow', shape = 'Default', folder_type = nil)
+        if( folder_type.nil? )
+          resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape} )
+        else
+          restr = {:restriction => 
+            {:is_equal_to => {:field_uRI => {:field_uRI=>'folder:FolderClass'},:field_uRI_or_constant=>{:constant => {:value => folder_type}}}}
+          }
+          resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape}, restr)
+        end
+
         if(resp.status == 'Success')
           folders = []
           resp.items.each do |f|
@@ -205,7 +215,9 @@ module Viewpoint
 
       # Find Items
       def find_items(opts = {})
-        resp = (Viewpoint::EWS::EWS.instance).ews.find_item([@folder_id], 'Shallow', {:base_shape => 'Default'}, opts)
+        item_shape = {:base_shape => 'Default'}
+        item_shape[:additional_properties] = {:field_uRI => ['item:ParentFolderId']}
+        resp = (Viewpoint::EWS::EWS.instance).ews.find_item([@folder_id], 'Shallow', item_shape, opts)
         if(resp.status == 'Success')
           parms = resp.items.shift
           items = []
@@ -288,7 +300,8 @@ module Viewpoint
       # @param [String] change_key specify an optional change_key if you want to
       #   make sure you are fetching a specific version of the object.
       def get_item(item_id, change_key = nil)
-        resp = (Viewpoint::EWS::EWS.instance).ews.get_item([item_id])
+        item_shape = {:base_shape => 'Default', :additional_properties => {:field_uRI => ['item:ParentFolderId']}}
+        resp = (Viewpoint::EWS::EWS.instance).ews.get_item([item_id], item_shape)
         if(resp.status == 'Success')
           item = resp.items.shift
           type = item.keys.first

data/lib/model/item.rb

@@ -36,7 +36,8 @@ module Viewpoint
         conn = Viewpoint::EWS::EWS.instance
         resp = conn.ews.get_item([item_id])
         resp = resp.items.shift
-        self.new(resp[resp.keys.first])
+        resp_type = resp.keys.first
+        eval "#{resp_type.to_s.camel_case}.new(resp[resp_type])"
       end
 
       # Add attachments to the passed in ParentId
@@ -200,6 +201,14 @@ module Viewpoint
         (resp.status == 'Success') || (raise EwsError, "Could not recycle message. #{resp.code}: #{resp.message}")
       end
 
+      # Get the parent folder of this item
+      # @return [GenericFolder] returns a GenericFolder of subclass of that type.
+      def parent_folder
+        #deepen!
+        GenericFolder.get_folder @parent_folder_id
+      end
+
+
       private
 
       # @todo Handle:

data/lib/model/meeting_cancellation.rb

@@ -0,0 +1,28 @@
+#############################################################################
+# 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
+    # Meeting cancellations have the exact same elements as a Meeting Message
+    # so MeetingCancellation is just a subclass of that.
+    class MeetingCancellation < MeetingMessage
+    end # MeetingCancellation
+  end # EWS
+end # Viewpoint

data/lib/model/meeting_message.rb

@@ -0,0 +1,30 @@
+#############################################################################
+# 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 MeetingMessage < Item
+
+      def initialize(ews_item)
+        super(ews_item)
+      end
+    end # MeetingMessage
+  end # EWS
+end # Viewpoint

data/lib/model/meeting_request.rb

@@ -0,0 +1,41 @@
+#############################################################################
+# 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 MeetingRequest < Item
+
+
+      private
+
+      def init_methods
+        super()
+        define_str_var :conversation_index, :conversation_topic, :internet_message_id, :references
+        define_mbox_users :to_recipients, :cc_recipients, :bcc_recipients, :reply_to, :required_attendees, :optional_attendees
+        define_mbox_user :from, :sender, :received_by, :received_representing, :organizer
+        define_bool_var :is_read, :is_read_receipt_requested, :is_response_requested, :is_delivery_receipt_requested, :is_draft, :is_from_me
+        define_bool_var :is_all_day_event, :is_cancelled, :is_delegated, :is_meeting, :is_out_of_date, :is_recurring, :is_resend
+        define_bool_var :is_submitted, :is_unmodified, :allow_new_time_proposal
+        define_int_var :adjacent_meeting_count, :appointment_sequence_number, :appointment_state, :conflicting_meeting_count
+        define_datetime_var :start, :end
+      end
+    end # MeetingRequest
+  end # EWS
+end # Viewpoint

data/lib/model/meeting_response.rb

@@ -0,0 +1,26 @@
+#############################################################################
+# 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 MeetingResponse < Item
+    end # MeetingResponse
+  end # EWS
+end # Viewpoint

data/lib/model/search_folder.rb

@@ -23,6 +23,20 @@ module Viewpoint
     # This class represents a SearchFolderType object in the Exchange Data store.
     class SearchFolder < GenericFolder
 
+      # Find folders of type SearchFolder
+      # @see GenericFolder.find_folders
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      #   or a FolderId (String).  SearchFolders must be created under the :searchfolders distinguished
+      #   id so we might as well only search from there.
+      # @param [String] traversal Shallow/Deep/SoftDeleted
+      # @param [String] shape the shape to return IdOnly/Default/AllProperties
+      # @param [optional, String] folder_type an optional folder type to limit the search to like 'IPF.Task'
+      # @return [Array] Returns an Array of Folder or subclasses of Folder
+      def self.find_folders(root = :searchfolders, traversal = 'Deep', shape = 'Default', folder_type = nil)
+        super(root, traversal, shape, folder_type)
+      end
+
+
       def initialize(folder)
         super(folder)
         define_int_var :unread_count

data/lib/model/task.rb

@@ -22,13 +22,43 @@ module Viewpoint
   module EWS
     class Task < Item
       
+
+      # Create a Task in the Exchange Data Store from a hash
+      # @param [Hash] item A Hash of values based on values found here:
+      #   http://msdn.microsoft.com/en-us/library/aa563930.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] disposition SaveOnly/SendOnly/SendAndSaveCopy
+      #   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_date => {:text => '2010-07-29T14:00:00'},
+      #     :due_date => {:text => '2010-07-29T15:00:00'},
+      #   }
+      # @example Minimal Usage
+      #   item = {:subject => {:text => 'This is a test'}}
+      def self.create_item_from_hash(item, folder_id = :tasks, disposition = 'SaveOnly')
+        conn = Viewpoint::EWS::EWS.instance
+        resp = conn.ews.create_task_item(folder_id, item, disposition)
+        if(resp.status == 'Success')
+          resp = resp.items.shift
+          self.new(resp[resp.keys.first])
+        else
+          raise EwsError, "Could not create Task. #{resp.code}: #{resp.message}"
+        end
+      end
+
       # Create a Task in the Exchange Data Store
       #
+      # @param [nil, String] folder the folder to add the task to. If it is nil
+      #   the Task will be placed in the default Task folder.
       # @param [String] subject The task subject
       # @param [String] body The task body
       # @param [DateTime] v_start The date/time when this task begins
       # @param [DateTime] v_end The date/time when this task is due
-      def self.create_task(subject, body, v_start = nil, v_end = nil)
+      def self.create_task(folder, subject, body, v_start = nil, v_end = nil)
         item = {}
         item[:subject] = {:text => subject}
         item[:body] = {:text => body, :body_type => 'Text'} unless body.nil?
@@ -36,7 +66,7 @@ module Viewpoint
         item[:due_date] = {:text => v_end.to_s} unless v_end.nil?
         
         conn = Viewpoint::EWS::EWS.instance
-        resp = conn.ews.create_task_item(nil, item, 'SaveOnly')
+        resp = conn.ews.create_task_item(folder, item, 'SaveOnly')
         if(resp.status == 'Success')
           resp = resp.items.shift
           self.new(resp[resp.keys.first])

data/lib/model/tasks_folder.rb

@@ -23,31 +23,19 @@ module Viewpoint
     # This class represents a TaskFolderType object in the Exchange Data store.
     class TasksFolder < GenericFolder
       
-      # Find Task subfolders of the passed root folder.  If no parameters are passed
-      # this method will search from the Root folder.
-      # @param [Str] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      # Find folders of type Task
+      # @see GenericFolder.find_folders
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
       #   or a FolderId (String)
       # @param [String] traversal Shallow/Deep/SoftDeleted
+      # @param [String] shape the shape to return IdOnly/Default/AllProperties
+      # @param [optional, String] folder_type an optional folder type to limit the search to like 'IPF.Task'
       # @return [Array] Returns an Array of Folder or subclasses of Folder
-      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default')
-        restr = {:restriction => 
-          {:is_equal_to => {:field_uRI => {:field_uRI=>'folder:FolderClass'},:field_uRI_or_constant=>{:constant => {:value => 'IPF.Task'}}}}
-        }
-        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape}, restr)
-        if(resp.status == 'Success')
-          folders = []
-          resp.items.each do |f|
-            f_type = f.keys.first.to_s.camel_case
-            folders << (eval "#{f_type}.new(f[f.keys.first])")
-          end
-          return folders
-        else
-          raise EwsError, "Could not retrieve folders. #{resp.code}: #{resp.message}"
-        end
+      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default', folder_type = 'IPF.Task')
+        super(root, traversal, shape, folder_type)
       end
 
 
-
       def initialize(folder)
         super(folder)
         define_int_var :unread_count