viewpoint 0.1.27 → 1.0.0.beta.1

data/lib/ews/exceptions/exceptions.rb

@@ -0,0 +1,59 @@
+=begin
+  This file is part of Viewpoint; the Ruby library for Microsoft Exchange Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+module Viewpoint::EWS
+
+  # Generic Ews Error
+  class EwsError < StandardError; end
+
+  # Raise when authentication/authorization issues occur.
+  class EwsLoginError < EwsError; end
+
+  class EwsSubscriptionError < EwsError; end
+
+  # Raised when a user tries to query a folder subscription after the
+  # subscription has timed out.
+  class EwsSubscriptionTimeout < EwsSubscriptionError; end
+
+  # Represents a function in EWS that is not yet implemented in Viewpoint
+  class EwsNotImplemented < EwsError; end
+
+  # Raised when an method is called in the wrong way
+  class EwsBadArgumentError < EwsError; end
+
+  # Raised when an item that is asked for is not found
+  class EwsItemNotFound < EwsError; end
+
+  # Raised when a folder that is asked for is not found
+  class EwsFolderNotFound < EwsError; end
+
+  # Raise an Exchange Server version error. This is in case some functionality
+  # does not exist in a particular Server version but is called.
+  class EwsServerVersionError < EwsError; end
+
+  # Raised when #auto_deepen == false and a method is called for attributes
+  # that have not yet been fetched.
+  class EwsMinimalObjectError < EwsError; end
+
+  # Failed to save an object back to the EWS store.
+  class SaveFailed < EwsError; end
+
+  class EwsCreateItemError < EwsError; end
+
+  class EwsSendItemError < EwsError; end
+
+end # Viewpoint::EWS

data/lib/ews/folder_accessors.rb

@@ -0,0 +1,199 @@
+=begin
+  This file is part of Viewpoint; the Ruby library for Microsoft Exchange Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+module Viewpoint::EWS::FolderAccessors
+  include Viewpoint::EWS
+
+  FOLDER_TYPE_MAP = {
+    :mail     => 'IPF.Note',
+    :calendar => 'IPF.Appointment',
+    :task     => 'IPF.Task',
+  }
+
+  # Find subfolders of the passed root folder.  If no parameters are passed this
+  # method will search from the Root folder.
+  # @param [Hash] opts Misc options to control request
+  # @option opts [String,Symbol] :root Either a FolderId(String) or a
+  #   DistinguishedFolderId(Symbol) . This is where to start the search from.
+  #   Usually :root,:msgfolderroot, or :publicfoldersroot
+  # @option opts [Symbol] :traversal :shallow/:deep/:soft_deleted
+  # @option opts [Symbol] :shape :id_only/:default/:all_properties
+  # @option opts [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
+  # @raise [EwsError] raised when the backend SOAP method returns an error.
+  def folders(opts={})
+    opts = opts.clone
+    args = find_folders_args(opts)
+    obj = OpenStruct.new(opts: args, restriction: {})
+    yield obj if block_given?
+    merge_restrictions! obj
+    resp = ews.find_folder( args )
+    find_folders_parser(resp)
+  end
+  alias :find_folders :folders
+
+  # Get a specific folder by id or symbol
+  # @param [String,Symbol,Hash] folder_id Either a FolderId(String) or a
+  #   DistinguishedFolderId(Symbol). You can also pass a Hash in the form:
+  #   {id: <fold_id>, change_key: <change_key>}
+  # @param [Hash] opts Misc options to control request
+  # @option opts [Symbol] :shape :id_only/:default/:all_properties
+  # @option opts [String,nil] :act_as User to act on behalf as. This user must
+  #   have been given delegate access to the folder or this operation will fail.
+  # @raise [EwsError] raised when the backend SOAP method returns an error.
+  def get_folder(folder_id, opts = {})
+    opts = opts.clone
+    args = get_folder_args(folder_id, opts)
+    resp = ews.get_folder(args)
+    get_folder_parser(resp)
+  end
+
+  # Get a specific folder by its name
+  # @param [String] name The folder name
+  # @param [Hash] opts Misc options to control request
+  # @option opts [String,Symbol] :parent Either a FolderId(String) or a
+  #   DistinguishedFolderId(Symbol) . This is the parent folder.
+  # @option opts [Symbol] :shape :id_only/:default/:all_properties
+  # @option opts [String,nil] :act_as User to act on behalf as. This user must
+  #   have been given delegate access to the folder or this operation will fail.
+  # @raise [EwsError] raised when the backend SOAP method returns an error.
+  def get_folder_by_name(name, opts={})
+    opts = opts.clone
+    opts[:root] = opts.delete(:parent)
+    folders(opts) do |obj|
+      obj.restriction = {
+        :is_equal_to =>
+        [
+          {:field_uRI => {:field_uRI=>'folder:DisplayName'}},
+          {:field_uRI_or_constant => {:constant => {:value=>name}}}
+        ]
+      }
+    end.first
+  end
+
+  # @param [String] name The name of the new folder
+  # @param [Hash] opts
+  # @option opts [String,Symbol] :parent Either a FolderId(String) or a
+  #   DistinguishedFolderId(Symbol) . This is the parent folder.
+  # @option opts [Symbol] :type the type of folder to create. must be one of
+  #   :folder, :calendar, :contacts, :search, or :tasks
+  # @see http://msdn.microsoft.com/en-us/library/aa580808.aspx
+  def make_folder(name, opts={})
+    parent = opts[:parent] || :msgfolderroot
+    resp = ews.create_folder :parent_folder_id => {:id => parent},
+      :folders => [folder_type(opts[:type]) => {:display_name => name}]
+    create_folder_parser(resp).first
+  end
+  alias :mkfolder :make_folder
+
+
+private
+
+  # Build up the arguements for #find_folders
+  def find_folders_args(opts)
+    opts[:root] = opts[:root] || :msgfolderroot
+    opts[:traversal] = opts[:traversal] || :shallow
+    opts[:shape] = opts[:shape] || :default
+    if( opts[:folder_type] )
+      restr = { :is_equal_to => 
+        [
+          {:field_uRI => {:field_uRI=>'folder:FolderClass'}},
+          {:field_uRI_or_constant=>{:constant =>
+            {:value => map_folder_type(opts[:folder_type])}}},
+        ]
+      }
+    end
+    args = {
+      :parent_folder_ids => [{:id => opts[:root]}],
+      :traversal => opts[:traversal],
+      :folder_shape => {:base_shape => opts[:shape]}
+    }
+    args[:restriction] = restr if restr
+    args
+  end
+
+  # @param [Viewpoint::EWS::SOAP::EwsSoapResponse] resp
+  def find_folders_parser(resp)
+    if resp.status == 'Success'
+      folders = resp.response_message[:elems][:root_folder][:elems][0][:folders][:elems]
+      return [] if folders.nil?
+      folders.collect do |f|
+        ftype = f.keys.first
+        class_by_name(ftype).new(ews, f[ftype])
+      end
+    else
+      raise EwsFolderNotFound, "Could not retrieve folders. #{resp.code}: #{resp.message}"
+    end
+  end
+
+  def create_folder_parser(resp)
+    if resp.status == 'Success'
+      folders = resp.response_message[:elems][:folders][:elems]
+      folders.collect do |f|
+        ftype = f.keys.first
+        class_by_name(ftype).new(ews, f[ftype])
+      end
+    else
+      raise EwsError, "Could not create folder. #{resp.code}: #{resp.message}"
+    end
+  end
+
+  # Build up the arguements for #get_folder
+  def get_folder_args(folder_id, opts)
+    opts[:shape] ||= :default
+    default_args =  {
+      :folder_shape => {:base_shape => opts[:shape]}
+    }
+    if folder_id.is_a?(Hash)
+      default_args[:folder_ids] = [folder_id]
+    else
+      default_args[:folder_ids] = [{:id => folder_id}]
+    end
+    default_args.merge opts
+  end
+
+  # @param [Viewpoint::EWS::SOAP::EwsSoapResponse] resp
+  def get_folder_parser(resp)
+    if(resp.status == 'Success')
+      f = resp.response_message[:elems][:folders][:elems][0]
+      ftype = f.keys.first
+      class_by_name(ftype).new(ews, f[ftype])
+    else
+      raise EwsFolderNotFound, "Could not retrieve folder. #{resp.code}: #{resp.message}"
+    end
+  end
+
+  # Map a passed parameter to a know folder type mapping. If no mapping
+  # exits simply allow the passed in type to be passed to the SOAP call.
+  # @param [Symbol] type a symbol in FOLDER_TYPE_MAP
+  def map_folder_type(type)
+    FOLDER_TYPE_MAP[type] || type
+  end
+
+  def folder_type(type)
+    case type
+    when nil, :folder
+      :folder
+    when :calendar, :contacts, :search, :tasks
+      "#{type}_folder".to_sym
+    else
+      raise EwsBadArgumentError, "Not a proper folder type: :#{type}"
+    end
+  end
+
+end

data/lib/ews/item_accessors.rb

@@ -0,0 +1,157 @@
+=begin
+  This file is part of Viewpoint; the Ruby library for Microsoft Exchange Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+module Viewpoint::EWS::ItemAccessors
+  include Viewpoint::EWS
+
+  # This is a class method that fetches an existing Item from the
+  #  Exchange Store.
+  # @param [String] item_id The id of the item. You can also pass a Hash in the
+  #   form: {id: <fold_id>, change_key: <change_key>}
+  # @param [Hash] opts Misc options to control request
+  # @option opts [Symbol] :shape :id_only/:default/:all_properties
+  # @return [Item] Returns an Item or subclass of Item
+  # @todo Add support to fetch an item with a ChangeKey
+  def get_item(item_id, opts = {})
+    args = get_item_args(item_id, opts.clone)
+    obj = OpenStruct.new(opts: args)
+    yield obj if block_given?
+    resp = ews.get_item(args)
+    get_item_parser(resp)
+  end
+
+  # @param [Hash] opts Misc options to control request
+  # @option opts [Symbol] :folder_id
+  # @see GenericFolder#items
+  def find_items(opts = {})
+    args = find_items_args(opts.clone)
+    obj = OpenStruct.new(opts: args, restriction: {})
+    yield obj if block_given?
+    merge_restrictions! obj
+    resp = ews.find_item(args)
+    find_items_parser resp
+  end
+
+  # Copy an array of items to the specified folder
+  # @param items [Array] an array of EWS Items that you want to copy
+  # @param folder [String,Symbol,GenericFolder] The folder to copy to. This must
+  #   be a subclass of GenericFolder, a DistinguishedFolderId (must me a Symbol)
+  #   or a FolderId (String)
+  # @return [Array<Hash>] returns a Hash for each item passed
+  #   on success:
+  #     {:success => true, :item_id => <new_item_id>}
+  #   on failure:
+  #     {:success => false, :error_message => <the message>}
+  def copy_items(items, folder)
+    folder = folder.id if folder.kind_of?(Types::GenericFolder)
+    item_ids = items.collect{|i| {item_id: {id: i.id, change_key: i.change_key}}}
+    copy_opts = {
+      :to_folder_id => {:id => folder},
+      :item_ids => item_ids
+    }
+    resp = ews.copy_item(copy_opts)
+    copy_move_items_parser(resp)
+  end
+
+  # Move an array of items to the specified folder
+  # @see #copy_items for parameter info
+  def move_items(items, folder)
+    folder = folder.id if folder.kind_of?(Types::GenericFolder)
+    item_ids = items.collect{|i| {item_id: {id: i.id, change_key: i.change_key}}}
+    move_opts = {
+      :to_folder_id => {:id => folder},
+      :item_ids => item_ids
+    }
+    resp = ews.move_item(move_opts)
+    copy_move_items_parser(resp, :move_item_response_message)
+  end
+
+
+private
+
+  def get_item_args(item_id, opts)
+    opts[:shape] ||= :default
+    default_args = {
+      :item_shape => {:base_shape => opts[:shape]}
+    }
+    if item_id.is_a?(Hash)
+      default_args[:item_ids] = [{:item_id => item_id}]
+    else
+      default_args[:item_ids] = [{:item_id => {:id => item_id}}]
+    end
+    default_args.merge opts
+  end
+
+  def get_item_parser(resp)
+    rm = resp.response_messages[0]
+
+    if(rm && rm.status == 'Success')
+      i = rm.items.first
+      itype = i.keys.first
+      class_by_name(itype).new(ews, i[itype])
+    else
+      code = rm.respond_to?(:code) ? rm.code : "Unknown"
+      text = rm.respond_to?(:message_text) ? rm.message_text : "Unknown"
+      raise EwsItemNotFound, "Could not retrieve item. #{rm.code}: #{rm.message_text}"
+    end
+  end
+
+  def find_items_args(opts)
+    default_args = {
+      :traversal => 'Shallow',
+      :item_shape  => {:base_shape => 'Default'}
+    }
+
+    if opts[:folder_id].is_a?(Hash)
+      default_args[:parent_folder_ids] = [opts.delete(:folder_id)]
+    else
+      default_args[:parent_folder_ids] = [{:id => opts.delete(:folder_id)}]
+    end
+    default_args.merge(opts)
+  end
+
+  def find_items_parser(resp)
+    rm = resp.response_messages[0]
+    if rm.success?
+      items = []
+      rm.root_folder.items.each do |i|
+        type = i.keys.first
+        items << class_by_name(type).new(ews, i[type])
+      end
+      items
+    else
+      raise EwsError, "Could not retrieve folder. #{rm.code}: #{rm.message_text}"
+    end
+  end
+
+  def copy_move_items_parser(resp, resp_type = :copy_item_response_message)
+    resp.response_messages.collect {|r|
+      obj = {}
+      if r.success?
+        obj[:success] = true
+        item = r.items.first
+        key = item.keys.first
+        obj[:item_id] = item[key][:elems][0][:item_id][:attribs][:id]
+      else
+        obj[:success] = false
+        obj[:error_message] = "#{r.response_code}: #{r.message_text}"
+      end
+      obj
+    }
+  end
+
+end # Viewpoint::EWS::ItemAccessors

data/lib/ews/mailbox_accessors.rb

@@ -0,0 +1,87 @@
+=begin
+  This file is part of Viewpoint; the Ruby library for Microsoft Exchange Web Services.
+
+  Copyright © 2011 Dan Wanek <dan.wanek@gmail.com>
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+=end
+
+module Viewpoint::EWS::MailboxAccessors
+  include Viewpoint::EWS
+
+  # Resolve contacts in the Exchange Data Store
+  # @param [String] ustring A string to resolve contacts to.
+  # @return [Array<MailboxUser>] It returns an Array of MailboxUsers.
+  def search_contacts(ustring)
+    resp = ews.resolve_names(:name => ustring)
+
+    users = []
+    if(resp.status == 'Success')
+      mb = resp.response_message[:elems][:resolution_set][:elems][0][:resolution][:elems][0]
+      users << Types::MailboxUser.new(ews, mb[:mailbox][:elems])
+    elsif(resp.code == 'ErrorNameResolutionMultipleResults')
+      resp.response_message[:elems][:resolution_set][:elems].each do |u|
+      if u[:resolution][:elems][0][:mailbox]
+        users << Types::MailboxUser.new(ews, u[:resolution][:elems][0][:mailbox][:elems])
+      end
+      end
+    else
+      raise EwsError, "Find User produced an error: #{resp.code}: #{resp.message}"
+    end
+    users
+  end
+
+  # GetUserAvailability request
+  # @see http://msdn.microsoft.com/en-us/library/aa563800.aspx
+  # @param [Array<String>] emails A list of emails you want to retrieve free-busy info for.
+  # @param [Hash] opts
+  # @option opts [DateTime] :start_time
+  # @option opts [DateTime] :end_time
+  # @option opts [Symbol] :requested_view :merged_only/:free_busy/
+  #   :free_busy_merged/:detailed/:detailed_merged
+  def get_user_availability(emails, opts)
+    opts = opts.clone
+    args = get_user_availability_args(emails, opts)
+    resp = ews.get_user_availability(args)
+    get_user_availability_parser(resp)
+  end
+
+
+private
+
+  def get_user_availability_args(emails, opts)
+    unless opts.has_key?(:start_time) && opts.has_key?(:end_time) && opts.has_key?(:requested_view)
+      raise EwsBadArgumentError, "You must specify a start_time, end_time and requested_view."
+    end
+
+    default_args = {
+      mailbox_data: (emails.collect{|e| [email: {address: e}]}.flatten),
+      free_busy_view_options: {
+        time_window: {
+          start_time: opts[:start_time],
+          end_time: opts[:end_time]
+        },
+        requested_view: { :requested_free_busy_view => opts[:requested_view] },
+      }
+    }
+  end
+
+  def get_user_availability_parser(resp)
+    if(resp.status == 'Success')
+      resp
+    else
+      raise EwsError, "GetUserAvailability produced an error: #{resp.code}: #{resp.message}"
+    end
+  end
+
+end # Viewpoint::EWS::MailboxAccessors