stxt-viewpoint 1.0.0.beta.3

data/lib/ews/exceptions/exceptions.rb

@@ -0,0 +1,61 @@
+=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
+
+  class EwsFrozenObjectError < 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,264 @@
+=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
+
+  # Get a specific folder by id or symbol
+  # @param [Hash] opts Misc options to control request
+  # @option opts [Symbol] :shape :id_only/:default/:all_properties
+  # @option opts [String,Symbol,Hash] :folder_id You can optionally specify a
+  #   folder_id to limit the hierarchy synchronization to it. It must be a
+  #   FolderId(String), a DistinguishedFolderId(Symbol) or you can pass a Hash
+  #   in the form: {id: <fold_id>, change_key: <change_key>}
+  # @option opts [String] :sync_state an optional Base64 encoded SyncState
+  #   String from a previous sync call.
+  # @yield [Hash] yields the formatted argument Hash for last-minute
+  #   modification before calling the backend EWS method.
+  # @return [Hash] A hash with the following keys
+  #   :all_synced, whether or not additional calls are needed to get all folders
+  #   :sync_state, the sync state to use for the next call
+  #   and the following optional keys depending on the changes
+  #   :create, :update, :delete
+  # @raise [EwsError] raised when the backend SOAP method returns an error.
+  def sync_folders(opts = {})
+    opts = opts.clone
+    args = sync_folders_args(opts)
+    yield args if block_given?
+    resp = ews.sync_folder_hierarchy( args )
+    sync_folders_parser(resp)
+  end
+
+
+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
+    folder_id = {:id => opts[:root]}
+    folder_id[:act_as] = opts[:act_as] if opts[:act_as]
+    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 => [folder_id],
+      :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
+
+  def sync_folders_args(opts)
+    opts[:shape] = opts[:shape] || :default
+    args = { :folder_shape => {:base_shape => opts[:shape]} }
+    if opts[:folder_id]
+      folder_id = opts[:folder_id]
+      if folder_id.is_a?(Hash)
+        args[:sync_folder_id] = folder_id
+      else
+        args[:sync_folder_id] = {:id => folder_id}
+      end
+    end
+    args[:sync_state] = opts[:sync_state] if opts[:sync_state]
+    args
+  end
+
+  def sync_folders_parser(resp)
+    rmsg = resp.response_messages[0]
+    if rmsg.success?
+      rhash = {}
+      rhash[:all_synced] = rmsg.includes_last_folder_in_range?
+      rhash[:sync_state] = rmsg.sync_state
+      rmsg.changes.each do |c|
+        ctype = c.keys.first
+        rhash[ctype] = [] unless rhash.has_key?(ctype)
+        if ctype == :delete
+          rhash[ctype] << c[ctype][:elems][0][:folder_id][:attribs]
+        else
+          type = c[ctype][:elems][0].keys.first
+          item = class_by_name(type).new(ews, c[ctype][:elems][0][type])
+          rhash[ctype] << item
+        end
+      end
+      rhash
+    else
+      raise EwsError, "Could not synchronize folders. #{rmsg.response_code}: #{rmsg.message_text}"
+    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/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,231 @@
+=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
+      [{:item_id => item_id}]
+    when Array
+      item_id.map{|i| {:item_id => {:id => i}}}
+    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