viewpoint 0.1.26 → 1.1.1

data/lib/ews/impersonation.rb

@@ -0,0 +1,30 @@
+module Viewpoint::EWS
+
+  ConnectingSID = {
+    :UPN => 'PrincipalName',
+    :SID => 'SID',
+    :PSMTP => 'PrimarySmtpAddress',
+    :SMTP => 'SmtpAddress'
+  }
+
+  # @param connecting_type [String] should be one of the ConnectingSID variables
+  #   ConnectingSID[:UPN] - use User Principal Name method
+  #   ConnectingSID[:SID] - use Security Identifier method
+  #   ConnectingSID[:PSMTP] - use primary Simple Mail Transfer Protocol method
+  #   ConnectingSID[:SMTP] - use Simple Mail Transfer Protocol method
+  #   you can add any other string, it will be converted into xml tag on soap request
+  # @param address [String] an address to include to requests for impersonation
+  def set_impersonation(connecting_type, address)
+    if ConnectingSID.has_value? connecting_type or connecting_type.is_a? String then
+      ews.impersonation_type = connecting_type
+      ews.impersonation_address = address
+    else
+      raise EwsBadArgumentError, "Not a proper connecting method: #{connecting_type.class}"
+    end
+  end
+
+  def remove_impersonation
+    ews.impersonation_type = ""
+    ews.impersonation_address = ""
+  end
+end

data/lib/ews/item_accessors.rb

@@ -0,0 +1,242 @@
+=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
+
+  # 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_items(item_ids, opts = {})
+    args = get_item_args(item_ids, opts.clone)
+    obj = OpenStruct.new(opts: args)
+    yield obj if block_given?
+    resp = ews.get_item(args)
+    get_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
+
+  # Exports an entire item into base64 string
+  # @param item_ids [Array] array of item ids. Can also be a single id value
+  # return [Array] array of bulk items
+  def export_items(item_ids)
+    args = export_items_args(item_ids)
+
+    resp = ews.export_items(args)
+    export_items_parser(resp)
+  end
+
+private
+
+  def get_item_args(item_id, opts)
+    opts[:shape] ||= :default
+    default_args = {
+      :item_shape => {:base_shape => opts[:shape]}
+    }
+    default_args[:item_ids] = case item_id
+    when Hash
+      if item_id.keys.index(:id)
+        [{:item_id => item_id}]
+      else
+        [item_id]
+      end
+    when Array
+      item_id.map do |i|
+        case i
+        when Hash
+          i
+        else
+          {:item_id => {:id => i}}
+        end
+      end
+    else
+      [{: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 get_items_parser(resp)
+    items = []
+
+    resp.response_messages.each do |rm|
+      if(rm && rm.status == 'Success')
+        rm.items.each do |i|
+          type = i.keys.first
+          items << class_by_name(type).new(ews, i[type])
+        end
+      end
+    end
+
+    items
+  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
+
+  def export_items_args(item_ids)
+    default_args = {}
+    default_args[:item_ids] = []
+    if item_ids.is_a?(Array) then
+      item_ids.each do |id|
+        default_args[:item_ids] = default_args[:item_ids] + [{:item_id => {:id => id}}]
+      end
+    else
+      default_args[:item_ids] = [{:item_id => {:id => item_ids}}]
+    end
+    default_args
+  end
+
+  def export_items_parser(resp)
+    rm = resp.response_messages
+    if(rm)
+      items = []
+      rm.each do |i|
+        if i.success? then
+          type = i.type
+          items << class_by_name(type).new(ews, i.message[:elems])
+        else
+          code = i.respond_to?(:code) ? i.code : "Unknown"
+          text = i.respond_to?(:message_text) ? i.message_text : "Unknown"
+          items << "Could not retrieve item. #{code}: #{text}"
+        end
+      end
+    items
+    end
+  end
+
+end # Viewpoint::EWS::ItemAccessors

data/lib/ews/mailbox_accessors.rb

@@ -0,0 +1,92 @@
+=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
+  # @option opts [Hash] :time_zone The TimeZone data
+  #   Example: {:bias => 'UTC offset in minutes',
+  #   :standard_time => {:bias => 480, :time => '02:00:00',
+  #     :day_order => 5, :month => 10, :day_of_week => 'Sunday'},
+  #   :daylight_time => {same options as :standard_time}}
+  def get_user_availability(emails, opts)
+    opts = opts.clone
+    args = get_user_availability_args(emails, opts)
+    resp = ews.get_user_availability(args.merge(opts))
+    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

data/lib/ews/meeting_accessors.rb

@@ -0,0 +1,39 @@
+module Viewpoint::EWS::MeetingAccessors
+  include Viewpoint::EWS
+
+  def accept_meeting(opts)
+    ews.create_item({
+      message_disposition: 'SendOnly',
+      items: [ { accept_item: opts_to_item(opts) } ]
+    })
+  end
+
+  def decline_meeting(opts)
+    ews.create_item({
+      message_disposition: 'SendOnly',
+      items: [ { decline_item: opts_to_item(opts) } ]
+    })
+  end
+
+  def tentatively_accept_meeting(opts)
+    ews.create_item({
+      message_disposition: 'SendOnly',
+      items: [ { tentatively_accept_item: opts_to_item(opts) } ]
+    })
+  end
+
+  private
+
+  def opts_to_item(opts)
+    hash = {
+      id: opts[:id],
+      change_key: opts[:change_key],
+      sensitivity: opts[:sensitivity]
+    }
+
+    hash[:text] = opts[:text] if opts[:text]
+    hash[:body_type] = (opts[:body_type] || 'Text') if opts[:text]
+
+    hash
+  end
+end

data/lib/ews/message_accessors.rb

@@ -0,0 +1,93 @@
+=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::MessageAccessors
+  include Viewpoint::EWS
+
+  # Send an E-mail message
+  #
+  # @param [Hash] opts A Hash with message params
+  # @option opts [String] :subject The message subject
+  # @option opts [String] :body The message body
+  # @option opts [Array] :to_recipients An array of e-mail addresses to send to
+  # @option opts [Array] :cc_recipients An array of e-mail addresses to send to
+  # @option opts [Array] :bcc_recipients An array of e-mail addresses to send to
+  # @option opts [Array] :extended_properties An array of extended properties
+  #   [{extended_field_uri: {epros}, value: <val>}] or values: [<val>, <val>]
+  # @option opts [Boolean] :draft if true it will save to the draft folder
+  #   without sending the message.
+  # @option opts [String,Symbol,Hash] saved_item_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>}
+  # @option opts [Array<File>] :file_attachments an Array of File or Tempfile objects
+  # @option opts [Array<File>] :inline_attachments an Array of Inline File or Tempfile objects
+  # @return [Message,Boolean] Returns true if the message is sent, false if
+  #   nothing is returned from EWS or if draft is true it will return the
+  #   Message object. Finally, if something goes wrong, it raises an error
+  #   with a message stating why the e-mail could not be sent.
+  # @todo Finish ItemAttachments
+  def send_message(opts = {}, &block)
+    msg = Template::Message.new opts.clone
+    yield msg if block_given?
+    if msg.has_attachments?
+      draft = msg.draft
+      msg.draft = true
+      resp = parse_create_item(ews.create_item(msg.to_ews))
+      msg.file_attachments.each do |f|
+        next unless f.kind_of?(File) or f.kind_of?(Tempfile)
+        resp.add_file_attachment(f)
+      end
+      msg.inline_attachments.each do |f|
+        next unless f.kind_of?(File) or f.kind_of?(Tempfile)
+        resp.add_inline_attachment(f)
+      end
+      if draft
+        resp.submit_attachments!
+        resp
+      else
+        resp.submit!
+      end
+    else
+      resp = ews.create_item(msg.to_ews)
+      resp.response_messages ?  parse_create_item(resp) : false
+    end
+  end
+
+  # See #send_message for options
+  def draft_message(opts = {}, &block)
+    send_message opts.merge(draft: true), &block
+  end
+
+
+  private
+
+
+  def parse_create_item(resp)
+    rm = resp.response_messages[0]
+    if(rm.status == 'Success')
+      rm.items.empty? ? true : parse_message(rm.items.first)
+    else
+      raise EwsError, "Could not send message. #{rm.code}: #{rm.message_text}"
+    end
+  end
+
+  def parse_message(msg)
+    mtype = msg.keys.first
+    message = class_by_name(mtype).new(ews, msg[mtype])
+  end
+
+end # Viewpoint::EWS::MessageAccessors