viewpoint 0.0.5 → 0.1.0

data/lib/model/item.rb

@@ -0,0 +1,126 @@
+#############################################################################
+# 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/>.
+#############################################################################
+
+
+# This class is inherited by all Item subtypes such as Message, Event,
+# and Task.  It will serve as the brain for all of the methods that
+# each of these Item types have in common.
+module Viewpoint
+  module EWS
+    class Item
+      include Model
+
+      # This is a class method that fetches an existing Item from the
+      #  Exchange Store.
+      # @param [String] item_id The id of the item.
+      # @return [Item] Returns an Item or subclass of Item
+      # @todo Add support to fetch an item with a ChangeKey
+      def self.get_item(item_id)
+        conn = Viewpoint::EWS::EWS.instance
+        resp = conn.ews.get_item([item_id])
+        resp = resp.items.shift
+        self.new(resp[resp.keys.first])
+      end
+
+      attr_reader :item_id, :body_type
+      alias :id :item_id
+
+      # Initialize an Exchange Web Services item
+      # @param [Hash] ews_item A hash representing this item
+      # @param [Boolean] shallow Whether or not we have retrieved all the elements for this object
+      def initialize(ews_item, shallow = true)
+        super() # Calls initialize in Model (creates @ews_methods Array)
+        @ews_item = ews_item
+        @shallow = shallow
+        @item_id = ews_item[:item_id][:id]
+
+        init_methods
+      end
+
+      def deepen!
+        conn = Viewpoint::EWS::EWS.instance
+        resp = conn.ews.get_item([@item_id], {:base_shape => 'AllProperties'})
+        resp = resp.items.shift
+        @ews_item = resp[resp.keys.first]
+        @shallow = false
+        @ews_methods = []
+        @ews_methods_undef = []
+        init_methods
+      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
+      # @return [Boolean] Whether or not the item was deleted
+      # @todo Add exception handling for failed deletes
+      def delete!(soft=false)
+        deltype = soft ? 'SoftDelete' : 'HardDelete'
+        resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], deltype)
+        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!
+        resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], 'MoveToDeletedItems')
+        self.clear_object!
+        resp.status == 'Success'
+      end
+
+      private
+
+      # @todo Handle:
+      #   <Attachments/> <Categories/> <InternetMessageHeaders/> <ResponseObjects/>
+      #   <ExtendedProperty/> <EffectiveRights/>
+      def init_methods
+        @parent_folder_id = @ews_item[:parent_folder_id][:id] if @ews_item[:parent_folder_id].is_a?(Hash)
+        @conversation_id  = @ews_item[:conversation_id][:id] if @ews_item[:conversation_id].is_a?(Hash)
+        @ews_methods << :item_id
+        if(@ews_item[:body] && @ews_item[:body][:body_type])
+          @body_type = @ews_item[:body][:body_type]
+          @ews_methods << :body_type
+        end
+        if(@ews_item[:unique_body] && @ews_item[:unique_body][:body_type])
+          @unique_body_type = @ews_item[:body][:body_type]
+          @ews_methods << :unique_body_type
+        end
+        if(@ews_item[:mime_content] && @ews_item[:mime_content][:character_set])
+          @mime_charset = @ews_item[:mime_content][:character_set]
+          @ews_methods << :mime_charset
+        end
+        define_str_var :subject, :sensitivity, :body, :item_class, :importance, :in_reply_to, :unique_body
+        define_str_var :display_cc, :display_to, :culture, :last_modified_name, :mime_content
+        define_str_var :web_client_read_form_query_string, :web_client_edit_form_query_string
+        define_int_var :size, :reminder_minutes_before_start
+        define_bool_var :has_attachments, :is_submitted, :is_draft, :is_from_me, :is_resend, :is_unmodified, :reminder_is_set, :is_associated
+        define_datetime_var :date_time_sent, :date_time_created, :date_time_received, :reminder_due_by, :last_modified_time
+      end
+
+      def method_missing(m, *args, &block)
+        warn "!!! No such method: #{m}"
+      end
+
+    end # Item
+  end # EWS
+end # Viewpoint

data/lib/model/mailbox_user.rb

@@ -0,0 +1,107 @@
+#############################################################################
+# 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
+
+    # This represents a Mailbox object in the Exchange data store
+    # @see http://msdn.microsoft.com/en-us/library/aa565036.aspx MSDN docs
+    # @todo Design a Class method that resolves to an Array of MailboxUsers
+    class MailboxUser
+      include Model
+
+      # Resolve a user in the Exchange Data Store
+      # @param [String] A user to resolve to.
+      # @return [MailboxUser,Array] If it resolves to one user then it returns a MailboxUser.
+      #   If it resolves to more than one user an Array of MailboxUsers are returned.  If an
+      #   error ocurrs an exception is raised.
+      def self.find_user(resolve)
+        resp = (Viewpoint::EWS::EWS.instance).ews.resolve_names(resolve)
+        if(resp.status == 'Success')
+          return self.new(resp.items.first[:mailbox])
+        elsif(resp.code == 'ErrorNameResolutionMultipleResults')
+          users = []
+          resp.items.each do |u|
+            users << self.new(u[:mailbox])
+          end
+          return users
+        else
+          raise EwsError, "Find User produced an error: #{resp.code}: #{resp.message}"
+        end
+      end
+
+      def initialize(mbox_user)
+        super() # Calls initialize in Model (creates @ews_methods Array)
+        @ews_item = mbox_user
+        define_str_var :name, :email_address, :routing_type, :mailbox_type, :item_id
+      end
+      
+      # Adds one or more delegates to a principal's mailbox and sets specific access permissions
+      # @see http://msdn.microsoft.com/en-us/library/bb856527.aspx
+      #
+      # @param [String,MailboxUser] delegate_email The user you would like to give delegate access to.
+      #   This can either be a simple String e-mail address or you can pass in a MailboxUser object.
+      # @param [Hash] permissions A hash of folder type keys and permission type values. An example
+      #   would be {:calendar_folder_permission_level => 'Editor'}.  Possible keys are:
+      #   :calendar_folder_permission_level, :tasks_folder_permission_level, :inbox_folder_permission_level
+      #   :contacts_folder_permission_level, :notes_folder_permission_level, :journal_folder_permission_level
+      #   and possible values are:  None/Editor/Reviewer/Author/Custom
+      # @return [true] This method either returns true or raises an error with the message
+      #   as to why this operation did not succeed.
+      def add_delegate!(delegate_email, permissions)
+        # Modify permissions so we can pass it to the builders
+        permissions.each_pair do |k,v|
+          permissions[k] = {:text => v}
+        end
+
+        resp = (Viewpoint::EWS::EWS.instance).ews.add_delegate(self.email_address, delegate_email, permissions)
+        if(resp.status == 'Success')
+          return true
+        else
+          raise EwsError, "Could not add delegate access for user #{delegate_email}: #{resp.code}, #{resp.message}"
+        end
+      end
+
+      def update_delegate!(delegate_email, permissions)
+        # Modify permissions so we can pass it to the builders
+        permissions.each_pair do |k,v|
+          permissions[k] = {:text => v}
+        end
+
+        resp = (Viewpoint::EWS::EWS.instance).ews.update_delegate(self.email_address, delegate_email, permissions)
+        if(resp.status == 'Success')
+          return true
+        else
+          raise EwsError, "Could not update delegate access for user #{delegate_email}: #{resp.code}, #{resp.message}"
+        end
+      end
+
+      def get_delegate_info()
+        resp = (Viewpoint::EWS::EWS.instance).ews.get_delegate(self.email_address)
+       # if(resp.status == 'Success')
+       #   return true
+       # else
+       #   raise EwsError, "Could not update delegate access for user #{delegate_email}: #{resp.code}, #{resp.message}"
+       # end
+      end
+
+    end # MailboxUser
+  end # EWS
+end # Viewpoint

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/{viewpoint/errors.rb → model/meeting_message.rb}

@@ -1,5 +1,5 @@
 #############################################################################
-# Copyright © 2009 Dan Wanek <dan.wanek@gmail.com>
+# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
 #
 #
 # This file is part of Viewpoint.
@@ -17,18 +17,14 @@
 # You should have received a copy of the GNU General Public License along
 # with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
 #############################################################################
-$:.unshift(File.dirname(__FILE__))
-require 'viewpoint'
 
-class Viewpoint::InvalidEWSItemError < Exception
-  def message
-    "Invalid Item for Exchange Web Services"
-  end
-end
+module Viewpoint
+  module EWS
+    class MeetingMessage < Item
 
-
-class Viewpoint::NoSuchItemIdError < Exception
-  def message
-    "No such item_id found in Exchange"
-  end
-end
+      def initialize(ews_item)
+        super(ews_item)
+      end
+    end # MeetingMessage
+  end # EWS
+end # Viewpoint

data/lib/model/meeting_request.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 MeetingRequest < Item
+    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/message.rb

@@ -0,0 +1,73 @@
+#############################################################################
+# 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 Message < Item
+
+      # Send an E-mail message
+      #
+      # @param [String] subject The message subject
+      # @param [String] body The message body
+      # @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=[])
+        item = {}
+        item[:subject] = {:text => subject}
+        item[:body] = {:text => body, :body_type => 'Text'} unless body.nil?
+        to_recipients.each do |a|
+          item[:to_recipients] = [] unless item[:to_recipients].is_a?(Array)
+          item[:to_recipients] << {:mailbox => {:email_address => {:text => a}}}
+        end
+        cc_recipients.each do |a|
+          item[:cc_recipients] = [] unless item[:cc_recipients].is_a?(Array)
+          item[:cc_recipients] << {:mailbox => {:email_address => {:text => a}}}
+        end
+        bcc_recipients.each do |a|
+          item[:bcc_recipients] = [] unless item[:bcc_recipients].is_a?(Array)
+          item[:bcc_recipients] << {:mailbox => {:email_address => {:text => a}}}
+        end
+        
+        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}")
+      end
+
+      # Initialize an Exchange Web Services item of type Message
+      def initialize(ews_item)
+        super(ews_item)
+      end
+
+      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
+        define_mbox_user :from, :sender, :received_by, :received_representing
+        define_bool_var :is_read, :is_read_receipt_requested, :is_response_requested, :is_delivery_receipt_requested
+      end
+
+    end # Message
+  end # EWS
+end # Viewpoint

data/lib/model/model.rb

@@ -0,0 +1,161 @@
+#############################################################################
+# 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/>.
+#############################################################################
+
+
+# This class is inherited by all Item subtypes such as Message, Event,
+# and Task.  It will serve as the brain for all of the methods that
+# each of these Item types have in common.
+module Viewpoint
+  module EWS
+    # This is the base model Module for shared code among all Model classes.
+    # @attr_reader [Array] :ews_methods The EWS methods created for this Model.
+    module Model
+
+      # These are convenience methods to quickly create instance methods for
+      # the various Model types when passed a Hash from the SOAP parser.
+      # These functions depend on each model type saving the passed Hash
+      # in an instance variable called @ews_item.
+
+      attr_reader :ews_methods, :ews_methods_undef
+
+      def initialize
+        # Defined EWS methods
+        @ews_methods = []
+        # Undefined EWS methods
+        @ews_methods_undef = []
+      end
+
+      protected
+
+      def define_str_var(*vars)
+        vars.each do |var|
+          if(@ews_item[var])
+            @ews_methods << var
+            self.instance_eval <<-EOF
+            def #{var.to_s}
+              @ews_item[:#{var}][:text]
+            end
+            EOF
+          else
+            @ews_methods_undef << var
+          end
+        end
+      end
+      
+      def define_int_var(*vars)
+        vars.each do |var|
+          if(@ews_item[var])
+            @ews_methods << var
+            self.instance_eval <<-EOF
+            def #{var}
+              @#{var} ||= @ews_item[:#{var}][:text].to_i
+            end
+            EOF
+          else
+            @ews_methods_undef << var
+          end
+        end
+      end
+
+      def define_bool_var(*vars)
+        vars.each do |var|
+          if(@ews_item[var])
+            @ews_methods << "#{var}?".to_sym
+            self.instance_eval <<-EOF
+            def #{var}?
+              @#{var} ||= (@ews_item[:#{var}][:text] == 'true') ? true : false
+            end
+            EOF
+          else
+            @ews_methods_undef << "#{var}?".to_sym
+          end
+        end
+      end
+
+      def define_datetime_var(*vars)
+        vars.each do |var|
+          if(@ews_item[var])
+            @ews_methods << var
+            self.instance_eval <<-EOF
+            def #{var}
+              @#{var} ||= DateTime.parse(@ews_item[:#{var}][:text])
+            end
+            EOF
+          else
+            @ews_methods_undef << var
+          end
+        end
+      end
+
+      def define_mbox_users(*vars)
+        vars.each do |var|
+          if(@ews_item[var])
+            @ews_methods << var
+            self.instance_eval <<-EOF
+            def #{var}
+              return @#{var} if defined?(@#{var})
+              if( (@ews_item[:#{var}][:mailbox]).is_a?(Hash) )
+                @#{var} = [MailboxUser.new(@ews_item[:#{var}][:mailbox])]
+              elsif( (@ews_item[:#{var}][:mailbox]).is_a?(Array) )
+                @#{var} = []
+                @ews_item[:#{var}][:mailbox].each do |i|
+                  @#{var} << MailboxUser.new(i)
+                end
+              else
+                raise EwsError, "Bad value for mailbox: " + @ews_item[:#{var}][:mailbox]
+              end
+              @#{var}
+            end
+            EOF
+          else
+            @ews_methods_undef << var
+          end
+        end
+      end
+
+      def define_mbox_user(*vars)
+        vars.each do |var|
+          if(@ews_item[var])
+            @ews_methods << var
+            self.instance_eval <<-EOF
+            def #{var}
+              @#{var} ||= MailboxUser.new(@ews_item[:#{var}][:mailbox])
+            end
+            EOF
+          else
+            @ews_methods_undef << var
+          end
+        end
+      end
+
+      # After a delete is called on an object this method will clear
+      # out all of the defined EWS methods so they can't be called on the
+      # instantiated object.
+      def clear_object!
+        @ews_methods.each do |m|
+          self.instance_variables.each do |iv|
+            self.instance_variable_set("#{iv}",nil)
+          end
+        end
+      end
+
+    end # Model
+  end # EWS
+end # Viewpoint