viewpoint 1.0.0.beta.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9d907a62a27fdf84a5f753b2319e08bc2cbee8cf
+  data.tar.gz: 9bcbc3643c74e3bcb3cbb59390025196f39fa8eb
+SHA512:
+  metadata.gz: abb2801cebc4a0cc1e2cffae1271c0f7cac0410dcf59cfef1752cea8f57db0b052ae23ea20e8d85afd8dd5ade056e00f4884c8a3675d2f0f523e31bd6ebbe60a
+  data.tar.gz: 9cf44489f68a0f70894674d1d82080ffe352e340f96ba22053e003810c88088beada8f4a43491feacce88add6a59da369259301a34c3ec356879c618183cd5d1

data/README.md

@@ -1,4 +1,4 @@
-**ATTENTION:** If you want to fix a bug in the currently released gem please use the 0.1.x-support branch. The master is the current development branch and is not ready for prime-time just yet.
+[![Build Status](https://travis-ci.org/WinRb/Viewpoint.svg?branch=master)](https://travis-ci.org/WinRb/Viewpoint)
 
 # Viewpoint for Exchange Web Services 1.0
 http://github.com/zenchild/Viewpoint/wiki
@@ -33,13 +33,18 @@ out of the picture this is no longer required. Go crazy ;)
 ## Enhanced in 1.0
 
 * *Delegate access is supported*
-  One thing that was often asked for, but missing from the previous version
-  was delegate access to mailboxes and calendars.  This is now supported via
-  the 'act_as' parameter to the GenericFolder::get_folder method. For example:
-  ofolder = Folder.get_folder(:inbox,'otheruser@test.com')
-  If your user has delegate access to the Inbox for otheruser@test.com this
-  operation will retrieve their inbox and allow you to manipulate it as you
-  would with your own Inbox.
+  One thing that was often asked for, but missing from the previous version was delegate access to mailboxes and calendars.  This is now supported via the 'act_as' parameter to the GenericFolder::get_folder method. 
+
+>> Inbox example:
+  ```ofolder = Folder.get_folder(:inbox, opts = {act_as: "user@host.com"})```
+
+>> If your user has delegate access to the Inbox for user@host.com this operation will retrieve their inbox and allow you to manipulate it as you would with your own Inbox.
+
+>> Calendar example:
+  ```oCalendar = cli.get_folder(:calendar, opts = {act_as: "user@host.com"})```
+
+>> If your user has delegate access to the Calendar for user@host.com this operation will retrieve their calendar and allow you to manipulate it as you would with your own Calendar, depending on the permissions the other user has granted you.
+
 
 * There is also some support for manipulation of delegate access itself via
   the methods MailboxUser#add_delegate!, MailboxUser#update_delegate!, and 
@@ -127,12 +132,12 @@ items = inbox.items
 inbox.todays_items
 
 # since a specific date
-sd = Date.iso8061 '2013-01-01'
+sd = Date.iso8601 '2013-01-01'
 inbox.items_since sd
 
 # between 2 dates
-sd = Date.iso8061 '2013-01-01'
-ed = Date.iso8061 '2013-02-01'
+sd = Date.iso8601 '2013-01-01'
+ed = Date.iso8601 '2013-02-01'
 inbox.items_between sd, ed
 ```
 ### Free/Busy Calendar Accessors

data/lib/ews/connection.rb

@@ -25,10 +25,17 @@ class Viewpoint::EWS::Connection
   # @param [String] endpoint the URL of the web service.
   #   @example https://<site>/ews/Exchange.asmx
   # @param [Hash] opts Misc config options (mostly for developement)
-  # @option opts [Fixnum] ssl_verify_mode
+  # @option opts [Fixnum] :ssl_verify_mode
+  # @option opts [Array]  :trust_ca an array of hashed dir paths or a file
   def initialize(endpoint, opts = {})
     @log = Logging.logger[self.class.name.to_s.to_sym]
     @httpcli = HTTPClient.new
+    if opts[:trust_ca]
+      @httpcli.ssl_config.clear_cert_store
+      opts[:trust_ca].each do |ca|
+        @httpcli.ssl_config.add_trust_ca ca
+      end
+    end
     @httpcli.ssl_config.verify_mode = opts[:ssl_verify_mode] if opts[:ssl_verify_mode]
     # Up the keep-alive so we don't have to do the NTLM dance as often.
     @httpcli.keep_alive_timeout = 60
@@ -91,16 +98,18 @@ class Viewpoint::EWS::Connection
       resp.body
     when 302
       # @todo redirect
-      raise "Unhandled HTTP Redirect"
+      raise Errors::UnhandledResponseError.new("Unhandled HTTP Redirect", resp)
+    when 401
+      raise Errors::UnauthorizedResponseError.new("Unauthorized request", resp)
     when 500
-      if resp.headers['Content-Type'].include?('xml')
+      if resp.headers['Content-Type'] =~ /xml/
         err_string, err_code = parse_soap_error(resp.body)
-        raise "SOAP Error: Message: #{err_string}  Code: #{err_code}"
+        raise Errors::SoapResponseError.new("SOAP Error: Message: #{err_string}  Code: #{err_code}", resp, err_code, err_string)
       else
-        raise "Internal Server Error. Message: #{resp.body}"
+        raise Errors::ServerError.new("Internal Server Error. Message: #{resp.body}", resp)
       end
     else
-      raise "HTTP Error Code: #{resp.status}, Msg: #{resp.body}"
+      raise Errors::ResponseError.new("HTTP Error Code: #{resp.status}, Msg: #{resp.body}", resp)
     end
   end
 

data/lib/ews/convert_accessors.rb

@@ -0,0 +1,56 @@
+=begin
+  This file is part of Viewpoint; the Ruby library for Microsoft Exchange Web Services.
+
+  Copyright © 2013 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::ConvertAccessors
+  include Viewpoint::EWS
+
+  # This is a class method that converts identifiers between formats.
+  # @param [String] id The id to be converted
+  # @param [Hash] opts Misc options to control request
+  # @option opts [Symbol] :format :ews_legacy_id/:ews_id/:entry_id/:hex_entry_id/:store_id/:owa_id
+  # @option opts [Symbol] :destination_format :ews_legacy_id/:ews_id/:entry_id/:hex_entry_id/:store_id/:owa_id
+  # @option opts [String] :mailbox Mailbox, if required
+  # @return [EwsResponse] Returns an EwsResponse containing the convert response message
+
+  def convert_id(id, opts = {})
+    args = convert_id_args(id, opts.clone)
+    obj = OpenStruct.new(opts: args)
+    yield obj if block_given?
+    resp = ews.convert_id(args)
+    convert_id_parser(resp)
+  end
+
+  private
+
+  def convert_id_args(id, opts)
+    { id: id }.merge opts
+  end
+
+  def convert_id_parser(resp)
+    rm = resp.response_messages[0]
+
+    if(rm && rm.status == 'Success')
+      # @todo create custom response class
+      rm
+    else
+      code = rm.respond_to?(:code) ? rm.code : "Unknown"
+      text = rm.respond_to?(:message_text) ? rm.message_text : "Unknown"
+      raise EwsError, "Could not convert id. #{rm.code}: #{rm.message_text}"
+    end
+  end
+
+end # Viewpoint::EWS::ItemAccessors

data/lib/ews/errors.rb

@@ -0,0 +1,56 @@
+=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::Errors
+  class ResponseError < RuntimeError
+    attr_reader :response
+
+    def initialize(message, response)
+      super(message)
+      @response = response
+    end
+
+    def status
+      response.status
+    end
+
+    def body
+      response.body
+    end
+  end
+
+  class UnhandledResponseError < ResponseError
+  end
+
+  class ServerError < ResponseError
+  end
+
+  class UnauthorizedResponseError < ResponseError
+  end
+
+  class SoapResponseError < ResponseError
+    attr_reader :faultcode,
+                :faultstring
+
+    def initialize(message, response, faultcode, faultstring)
+      super(message, response)
+      @faultcode = faultcode
+      @faultstring = faultstring
+    end
+  end
+end

data/lib/ews/ews_client.rb

@@ -4,6 +4,9 @@ require 'ews/message_accessors'
 require 'ews/mailbox_accessors'
 require 'ews/push_subscription_accessors'
 require 'ews/calendar_accessors'
+require 'ews/room_accessors'
+require 'ews/roomlist_accessors'
+require 'ews/convert_accessors'
 
 # This class is the glue between the Models and the Web Service.
 class Viewpoint::EWSClient
@@ -14,8 +17,12 @@ class Viewpoint::EWSClient
   include Viewpoint::EWS::MailboxAccessors
   include Viewpoint::EWS::PushSubscriptionAccessors
   include Viewpoint::EWS::CalendarAccessors
+  include Viewpoint::EWS::RoomAccessors
+  include Viewpoint::EWS::RoomlistAccessors
+  include Viewpoint::EWS::ConvertAccessors
+  include Viewpoint::StringUtils
 
-  # The instance of Viewpoint::EWS::SOAP::ExchangeWebService 
+  # The instance of Viewpoint::EWS::SOAP::ExchangeWebService
   attr_reader :ews
 
   # Initialize the EWSClient instance.
@@ -31,16 +38,39 @@ class Viewpoint::EWSClient
   # @option opts [Object] :http_class specify an alternate HTTP connection class.
   # @option opts [Hash] :http_opts options to pass to the connection
   def initialize(endpoint, user = nil, pass = nil, opts = {})
+    # dup all. @see ticket https://github.com/zenchild/Viewpoint/issues/68
+    endpoint, user, pass = endpoint.dup, user.dup, pass.dup
+    opts = opts.dup
     http_klass = opts[:http_class] || Viewpoint::EWS::Connection
     con = http_klass.new(endpoint, opts[:http_opts] || {})
     con.set_auth(user,pass) if(user && pass)
     @ews = SOAP::ExchangeWebService.new(con, opts)
   end
 
+  # @param deepen [Boolean] true to autodeepen, false otherwise
+  # @param behavior [Symbol] :raise, :nil When setting autodeepen to false you
+  #   can choose what the behavior is when an attribute does not exist. The
+  #   default is to raise a EwsMinimalObjectError.
+  def set_auto_deepen(deepen, behavior = :raise)
+    if deepen
+      @ews.auto_deepen = true
+    else
+      behavior = [:raise, :nil].include?(behavior) ? behavior : :raise
+      @ews.no_auto_deepen_behavior = behavior
+      @ews.auto_deepen = false
+    end
+  end
+
   def auto_deepen=(deepen)
-    @ews.auto_deepen = (deepen ? true : false)
+    set_auto_deepen deepen
   end
 
+  # Specify a default time zone context for all time attributes
+  # @param id [String] Identifier of a Microsoft well known time zone (e.g: 'UTC', 'W. Europe Standard Time')
+  # @note A list of time zones known by the server can be requested via {EWS::SOAP::ExchangeTimeZones#get_time_zones}
+  def set_time_zone(microsoft_time_zone_id)
+    @ews.set_time_zone_context microsoft_time_zone_id
+  end
 
   private
 
@@ -49,7 +79,7 @@ class Viewpoint::EWSClient
   # in there that I didn't want to include directly in this class.
   def class_by_name(cname)
     if(cname.instance_of? Symbol)
-      cname = cname.to_s.camel_case
+      cname = camel_case(cname)
     end
     Viewpoint::EWS::Types.const_get(cname)
   end

data/lib/ews/exceptions/exceptions.rb

@@ -49,6 +49,8 @@ module Viewpoint::EWS
   # 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
 

data/lib/ews/folder_accessors.rb

@@ -101,6 +101,31 @@ module Viewpoint::EWS::FolderAccessors
   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
 
@@ -109,6 +134,8 @@ private
     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 => 
         [
@@ -119,7 +146,7 @@ private
       }
     end
     args = {
-      :parent_folder_ids => [{:id => opts[:root]}],
+      :parent_folder_ids => [folder_id],
       :traversal => opts[:traversal],
       :folder_shape => {:base_shape => opts[:shape]}
     }
@@ -178,6 +205,44 @@ private
     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

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

@@ -46,6 +46,22 @@ module Viewpoint::EWS::ItemAccessors
     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
@@ -80,6 +96,15 @@ module Viewpoint::EWS::ItemAccessors
     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
 
@@ -88,10 +113,13 @@ private
     default_args = {
       :item_shape => {:base_shape => opts[:shape]}
     }
-    if item_id.is_a?(Hash)
-      default_args[:item_ids] = [{:item_id => item_id}]
+    default_args[:item_ids] = case item_id
+    when Hash
+      [{:item_id => item_id}]
+    when Array
+      item_id.map{|i| {:item_id => {:id => i}}}
     else
-      default_args[:item_ids] = [{:item_id => {:id => item_id}}]
+      [{:item_id => {:id => item_id}}]
     end
     default_args.merge opts
   end
@@ -110,6 +138,21 @@ private
     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',
@@ -154,4 +197,35 @@ private
     }
   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