stxt-viewpoint 1.0.0.beta.3

data/README.md

@@ -0,0 +1,201 @@
+**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.
+
+# Viewpoint for Exchange Web Services 1.0
+http://github.com/zenchild/Viewpoint/wiki
+
+Viewpoint for EWS provides a thin Ruby layer on top of Microsoft Exchange
+Web Services(EWS). It also includes a bunch of model classes that add an
+additional layer of abstraction on top of EWS for use in implementing
+programs with Viewpoint.
+
+BLOG:  http://distributed-frostbite.blogspot.com/
+
+Add me in LinkedIn:  http://www.linkedin.com/in/danwanek
+
+Find me on irc.freenode.net in #ruby-lang (zenChild)
+
+# Features
+
+## New in 1.0
+
+* SOAP backend is now only dependant on Nokogiri. Before version 1.0 Viewpoint
+went through a number of iterations in backends including SOAP4r and Handsoap.
+Each of these approaches had major issues so in the end I decided it was
+easiest to just build the SOAP messages with Nokogiri since I was using it as
+the parser for response messages already.
+
+* Viewpoint is no longer built on a Singleton pattern. The reason it was
+previously is because of the Handsoap backend. Handsoap itself uses a
+Singleton pattern for connection to the SOAP endpoint so with authentication
+I was forced to implement Viewpoint as a Singleton as well. Now with Handsoap
+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. 
+
+>> 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 
+  MailboxUser#get_delegate_info.
+
+
+# Using Viewpoint
+
+The version 1.0 API is quite a departure from the 0.1.x code base. If you have a lot of legacy code and aren't suffering from performance issues, think twice about upgrading. That said, I hope you'll find the new API much clean and more intuitive than previous versions.
+
+I also try and document the code to the base of my ability. Included in that code are links to the official Microsoft EWS documentation that might be helpful when troubleshooting "interesting" issues. You can either generate the documentation yourself with yard or check it out on [rdoc.info](http://rdoc.info/github/zenchild/Viewpoint/frames).
+
+Note the `cli` variable in the setup code directly below. I will use that variable throughout without the setup code.
+
+## The Setup
+```ruby
+require 'viewpoint'
+include Viewpoint::EWS
+
+endpoint = 'https://example.com/ews/Exchange.asmx'
+user = 'username'
+pass = 'password'
+
+cli = Viewpoint::EWSClient.new endpoint, user, pass
+```
+
+There are also various options you can pass to EWSClient.
+
+If you are testing in an environment using a self-signed certificate you can pass a connection parameter to ignore SSL verification by passing `http_opts: {ssl_verify_mode: 0}`.
+
+If you want to target a specific version of Exchange you can pass `server_version: SOAP::ExchangeWebService::VERSION_2010_SP1`. You really shouldn't have to use this unless you know why.
+
+## Accessors
+
+There are some basic accessors available on the Viewpoint::EWSClient instance. In prior versions these were typically class methods off of the models themselves (ex: Folder.get_folder(id)). Now all accessors are available through EWSClient.
+
+### Folder Accessors
+
+#### Listing Folders
+```ruby
+# Find all folders under :msgfolderroot
+folders = cli.folders
+
+# Find all folders under Inbox
+inbox_folders = cli.folders root: :inbox
+
+# Find all folders under :root and do a Deep search
+all_folders = cli.folders root: :root, traversal: :deep
+```
+
+#### Finding single folders
+```ruby
+# If you know the EWS id
+cli.get_folder <folder_id>
+# ... or if it's a standard folder pass its symbol
+cli.get_folder :index
+# or by name
+cli.get_folder_by_name 'test'
+# by name as a subfolder under "Inbox"
+cli.get_folder_by_name 'test', parent: :inbox
+```
+
+#### Creating/Deleting a folder
+```ruby
+# make a folder under :msgfolderroot
+cli.make_folder 'myfolder'
+
+# make a folder under Inbox
+my_folder = cli.make_folder 'My Stuff', parent: :inbox
+
+# make a new Tasks folder
+tasks = cli.make_folder 'New Tasks', type: :tasks
+
+# delete a folder
+my_folder.delete!
+```
+
+### Item Accessors
+
+#### Finding items
+```ruby
+items = inbox.items
+
+# for today
+inbox.todays_items
+
+# since a specific date
+sd = Date.iso8601 '2013-01-01'
+inbox.items_since sd
+
+# between 2 dates
+sd = Date.iso8601 '2013-01-01'
+ed = Date.iso8601 '2013-02-01'
+inbox.items_between sd, ed
+```
+### Free/Busy Calendar Accessors
+
+```ruby
+# Find when a user is busy
+require 'time'
+start_time = DateTime.parse("2013-02-19").iso8601
+end_time = DateTime.parse("2013-02-20").iso8601
+user_free_busy = cli.get_user_availability(['joe.user@exchange.site.com'],
+  start_time: start_time,
+  end_time:   end_time,
+  requested_view: :free_busy)
+busy_times = user_free_busy.calendar_event_array
+
+# Parse events from the calendar event array for start/end times and type
+busy_times.each { | event |
+  cli.event_busy_type(event)
+  cli.event_start_time(event)
+  cli.event_end_time(event)
+}
+
+# Find the user's working hours
+user_free_busy.working_hours
+```
+
+
+### Mailbox Accessors
+### Message Accessors
+```ruby
+cli.send_message subject: "Test", body: "Test", to_recipients: ['test@example.com']
+
+# or
+cli.send_message do |m|
+  m.subject = "Test"
+  m.body    = "Test"
+  m.to_recipients << 'test@example.com'
+  m.to_recipients << 'test2@example.com'
+end
+
+# set :draft => true or use cli.draft_message to only create a draft and not send.
+```
+
+## Thanks go out to...
+
+* Handl.it for sponsoring a good portion of the development effort.
+** https://www.handle.com/
+* The National Association of REALTORS® for providing a testing account
+  and much appreciated input and support.
+* The Holmes Group Limited for providing Exchange 2013 test accounts.
+
+---
+DISCLAIMER:  If you see something that could be done better or would like
+to help out in the development of this code please feel free to clone the
+'git' repository and send me patches:
+git clone git://github.com/zenchild/Viewpoint.git
+or add an issue on GitHub:
+http://github.com/zenchild/Viewpoint/issues
+
+Cheers!
+---

data/TODO

@@ -0,0 +1,17 @@
+h2. TODOS
+
+* Automate "deepening" of Model objects by over-riding method_missing
+
+<pre>
+if object.is_shallow? && all_methods.index(method)
+  deepen!
+else
+  raise the NoMethod error
+</pre>
+
+* Clean-up exceptions.  There is exception raising in the Model that will never ocurr because it is already being checked for in the Parser
+
+* Refactor #find_folders methods.  There is a lot of duplicate code right now and it could be simplified quite a bit.
+
+* Test TODO
+** Test for undefined methods and make sure the method_missing method isn't causing problems

data/lib/ews/calendar_accessors.rb

@@ -0,0 +1,46 @@
+=begin
+This file is a cotribution to Viewpoint; the Ruby library for Microsoft Exchange Web Services.
+
+Copyright © 2013 Mark McCahill <mark.mccahill@duke.edu>
+
+  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::CalendarAccessors
+  include Viewpoint::EWS
+
+  def event_busy_type( the_event )
+    the_event[:calendar_event][:elems][2][:busy_type][:text]
+  end
+
+  def event_start_time( the_event )
+    the_event[:calendar_event][:elems][0][:start_time][:text]
+  end
+
+  def event_end_time( the_event )
+    the_event[:calendar_event][:elems][1][:end_time][:text]
+  end
+  
+  def event_name( the_event )
+    the_event[:calendar_event][:elems][3][:calendar_event_details][:elems][1][:subject][:text]
+  end
+  
+  def event_location( the_event )
+    the_event[:calendar_event][:elems][3][:calendar_event_details][:elems][2][:location][:text]
+  end
+  
+  def event_is_recurring( the_event )
+    the_event[:calendar_event][:elems][3][:calendar_event_details][:elems][4][:is_recurring][:text]
+  end
+
+end # Viewpoint::EWS::CalendarAccessors

data/lib/ews/connection.rb

@@ -0,0 +1,120 @@
+=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
+require 'httpclient'
+
+class Viewpoint::EWS::Connection
+  include Viewpoint::EWS::ConnectionHelper
+  include Viewpoint::EWS
+
+  attr_reader :endpoint
+  # @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
+  def initialize(endpoint, opts = {})
+    @log = Logging.logger[self.class.name.to_s.to_sym]
+    @httpcli = HTTPClient.new
+    @httpcli.ssl_config.verify_mode = opts[:ssl_verify_mode] if opts[:ssl_verify_mode]
+    @httpcli.ssl_config.ssl_version = opts[:ssl_version] if opts[:ssl_version]
+    # Up the keep-alive so we don't have to do the NTLM dance as often.
+    @httpcli.keep_alive_timeout = 60
+    @endpoint = endpoint
+  end
+
+  def set_auth(user,pass)
+    @httpcli.set_auth(@endpoint.to_s, user, pass)
+  end
+
+  # Authenticate to the web service. You don't have to do this because
+  # authentication will happen on the first request if you don't do it here.
+  # @return [Boolean] true if authentication is successful, false otherwise
+  def authenticate
+    self.get && true
+  end
+
+  # Every Connection class must have the dispatch method. It is what sends the
+  # SOAP request to the server and calls the parser method on the EWS instance.
+  #
+  # This was originally in the ExchangeWebService class but it was added here
+  # to make the processing chain easier to modify. For example, it allows the
+  # reactor pattern to handle the request with a callback.
+  # @param ews [Viewpoint::EWS::SOAP::ExchangeWebService] used to call
+  #   #parse_soap_response
+  # @param soapmsg [String]
+  # @param opts [Hash] misc opts for handling the Response
+  def dispatch(ews, soapmsg, opts)
+    respmsg = post(soapmsg)
+    @log.debug <<-EOF.gsub(/^ {6}/, '')
+      Received SOAP Response:
+      ----------------
+      #{Nokogiri::XML(respmsg).to_xml}
+      ----------------
+    EOF
+    opts[:raw_response] ? respmsg : ews.parse_soap_response(respmsg, opts)
+  end
+
+  # Send a GET to the web service
+  # @return [String] If the request is successful (200) it returns the body of
+  #   the response.
+  def get
+    check_response( @httpcli.get(@endpoint) )
+  end
+
+  # Send a POST to the web service
+  # @return [String] If the request is successful (200) it returns the body of
+  #   the response.
+  def post(xmldoc)
+    headers = {'Content-Type' => 'text/xml'}
+    check_response( @httpcli.post(@endpoint, xmldoc, headers) )
+  end
+
+
+  private
+
+  def check_response(resp)
+    case resp.status
+    when 200
+      resp.body
+    when 302
+      # @todo 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')
+        err_string, err_code = parse_soap_error(resp.body)
+        raise Errors::SoapResponseError.new("SOAP Error: Message: #{err_string}  Code: #{err_code}", resp, err_code, err_string)
+      else
+        raise Errors::ServerError.new("Internal Server Error. Message: #{resp.body}", resp)
+      end
+    else
+      raise Errors::ResponseError.new("HTTP Error Code: #{resp.status}, Msg: #{resp.body}", resp)
+    end
+  end
+
+  # @param [String] xml to parse the errors from.
+  def parse_soap_error(xml)
+    ndoc = Nokogiri::XML(xml)
+    ns = ndoc.collect_namespaces
+    err_string  = ndoc.xpath("//faultstring",ns).text
+    err_code    = ndoc.xpath("//faultcode",ns).text
+    @log.debug "Internal SOAP error. Message: #{err_string}, Code: #{err_code}"
+    [err_string, err_code]
+  end
+
+end

data/lib/ews/connection_helper.rb

@@ -0,0 +1,35 @@
+=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::ConnectionHelper
+
+  def init_logging!
+    @log = Logging.logger[self.class.name.to_s.to_sym]
+  end
+
+  # @param [String] xml to parse the errors from.
+  def parse_soap_error(xml)
+    ndoc = Nokogiri::XML(xml)
+    ns = ndoc.collect_namespaces
+    err_string  = ndoc.xpath("//faultstring",ns).text
+    err_code    = ndoc.xpath("//faultcode",ns).text
+    @log.debug "Internal SOAP error. Message: #{err_string}, Code: #{err_code}"
+    [err_string, err_code]
+  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

@@ -0,0 +1,101 @@
+require 'ews/folder_accessors'
+require 'ews/item_accessors'
+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
+  include Viewpoint::EWS
+  include Viewpoint::EWS::FolderAccessors
+  include Viewpoint::EWS::ItemAccessors
+  include Viewpoint::EWS::MessageAccessors
+  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
+  attr_reader :ews
+
+  # Initialize the EWSClient instance.
+  # @param [String] endpoint The EWS endpoint we will be connecting to
+  # @param [String] user The user to authenticate as. If you are using
+  #   NTLM or Negotiate authentication you do not need to pass this parameter.
+  # @param [String] pass The user password. If you are using NTLM or
+  #   Negotiate authentication you do not need to pass this parameter.
+  # @param [Hash] opts Various options to pass to the backends
+  # @option opts [String] :server_version The Exchange server version to
+  #   target. See the VERSION_* constants in
+  #   Viewpoint::EWS::SOAP::ExchangeWebService.
+  # @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)
+    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
+
+
+  # This method also exists in EWS::Types, but there is a lot of other stuff
+  # in there that I didn't want to include directly in this class.
+  def class_by_name(cname)
+    if(cname.instance_of? Symbol)
+      cname = camel_case(cname)
+    end
+    Viewpoint::EWS::Types.const_get(cname)
+  end
+
+  # Used for multiple accessors
+  def merge_restrictions!(obj, merge_type = :and)
+    if obj.opts[:restriction] && !obj.opts[:restriction].empty? && !obj.restriction.empty?
+      obj.opts[:restriction] = {
+        merge_type => [
+          obj.opts.delete(:restriction),
+          obj.restriction
+        ]
+      }
+    elsif !obj.restriction.empty?
+      obj.opts[:restriction] = obj.restriction
+    end
+  end
+
+end