viewpoint 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ece8332b00329ee37c4cffa26e56e1556c80984b9d37d0ae60ace1fc347e3d
-  data.tar.gz: 8d7b1dfa6bf36a537a28506fd444ecae58332d2f063288b9ee8c898cb48a08fe
+  metadata.gz: 1bd4e910abc2cfbe08db2972b5903dfb283c4e9a8d98bd804b93f094709ae7b2
+  data.tar.gz: d6cd479428246450510e96931a72fb84eb50d148cbd33d95fd0278db24931d71
 SHA512:
-  metadata.gz: 746e02661dfd754fb47afb74ec487ec6d1739249e3623ef4657b3a384c3276f86b3a3c2fb3730caf681cb98f9a668bc189bb344740fe2e17e3290be9b7dba56f
-  data.tar.gz: 77bd344ed0b39d044c99ec57065a8b4bc1a70472615ad3adb79cacfbd8d8b7c7f63262bc33129916bed800e6669fddd193e8ee6eb45df1c503ab9835076bc34a
+  metadata.gz: 1f2a594e47277ccf9b74756ce63f6f9c25c43569db772109b0c7a5616719018b83f5d1de774f3c1afbe8253df8541275b737b69ae25c3e43e431fa525aa05849
+  data.tar.gz: c2588831f25737a7e57968295c3d75f64c50b7780b83f6f93826a0c03b98fec2d13af93e95504ccbe63b674fa74b19563d9218231a4488af0964d7b337ce4863

data/README.md

@@ -1,9 +1,9 @@
 # Viewpoint for Exchange Web Services
-[![Ruby](https://github.com/WinRb/Viewpoint/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/WinRb/Viewpoint/actions/workflows/ruby.yml)
+[![CI](https://github.com/WinRb/Viewpoint/actions/workflows/ci.yml/badge.svg)](https://github.com/WinRb/Viewpoint/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/viewpoint.svg)](https://rubygems.org/gems/viewpoint)
-[![License](https://img.shields.io/github/license/WinRb/Viewpoint.svg)](https://github.com/WinRb/Viewpoint/blob/master/LICENSE)
-[![Wiki](https://img.shields.io/badge/docs-wiki-lightgrey.svg)](http://github.com/WinRb/Viewpoint/wiki)
-[![Documentation](https://img.shields.io/badge/docs-rdoc-lightgrey.svg)](http://www.rubydoc.info/github/WinRb/Viewpoint/frames)
+[![License](https://img.shields.io/github/license/WinRb/Viewpoint.svg)](https://github.com/WinRb/Viewpoint/blob/main/LICENSE)
+[![Wiki](https://img.shields.io/badge/docs-wiki-lightgrey.svg)](https://github.com/WinRb/Viewpoint/wiki)
+[![Documentation](https://img.shields.io/badge/docs-rdoc-lightgrey.svg)](https://www.rubydoc.info/github/WinRb/Viewpoint/frames)
 
 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
@@ -57,7 +57,7 @@ out of the picture this is no longer required. Go crazy ;)
 
 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).
+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](https://www.rubydoc.info/github/WinRb/Viewpoint/frames).
 
 Note the `cli` variable in the setup code directly below. I will use that variable throughout without the setup code.
 
@@ -70,7 +70,12 @@ endpoint = 'https://example.com/ews/Exchange.asmx'
 user = 'username'
 pass = 'password'
 
-cli = Viewpoint::EWSClient.new endpoint, user, pass
+# Basic authentication
+cli = Viewpoint::EWSClient.new({ endpoint: endpoint, type: 'basic', user: user, password: pass })
+
+# OAuth bearer-token authentication
+token = 'your-oauth-bearer-token'
+cli = Viewpoint::EWSClient.new({ endpoint: endpoint, type: 'oauth', token: token })
 ```
 
 There are also various options you can pass to EWSClient.

data/lib/ews/calendar_accessors.rb

@@ -1,34 +1,38 @@
-=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]
+# frozen_string_literal: true
+
+# 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.
+
+module Viewpoint
+  module EWS
+    # Calendar operations mixed into the EWS client.
+    module 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
+    end
   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
-
-end # Viewpoint::EWS::CalendarAccessors
+end

data/lib/ews/connection.rb

@@ -1,140 +1,167 @@
-=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
+# frozen_string_literal: true
+
+#   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.
 require 'httpclient'
 
-class Viewpoint::EWS::Connection
-  include Viewpoint::EWS::ConnectionHelper
-  include Viewpoint::EWS
-
-  attr_reader :endpoint
-  @@supported_httpclient_opts = %i[agent_name default_header]
-
-  # @param [String] endpoint the URL of the web service.
-  #   @example https://<site>/ews/Exchange.asmx
-  # @param [Hash] opts Misc config options (mostly for development)
-  # @option opts [Fixnum] :ssl_verify_mode
-  # @option opts [Fixnum] :receive_timeout override the default receive timeout
-  #   seconds
-  # @option opts [Fixnum] :connect_timeout override the default connect timeout
-  #   seconds
-  # @option opts [Array]  :trust_ca an array of hashed dir paths or a file
-  # @option opts [String] :user_agent the http user agent to use in all requests
-  def initialize(endpoint, opts = {})
-    @log = Logging.logger[self.class.name.to_s.to_sym]
-
-    httpclient_opts = opts.slice(*@@supported_httpclient_opts)
-    @httpcli = HTTPClient.new(**httpclient_opts)
-
-    if opts[:trust_ca]
-      @httpcli.ssl_config.clear_cert_store
-      opts[:trust_ca].each do |ca|
-        @httpcli.ssl_config.add_trust_ca ca
+module Viewpoint
+  module EWS
+    # HTTP connection to the Exchange server.
+    class Connection
+      include Viewpoint::EWS::ConnectionHelper
+      include Viewpoint::EWS
+
+      attr_reader :endpoint
+
+      SUPPORTED_HTTPCLIENT_OPTS = %i[agent_name default_header].freeze
+
+      # @param [Hash] auth authentication details
+      # @option auth [String] :endpoint the URL of the web service.
+      #   @example https://<site>/ews/Exchange.asmx
+      # @option auth [String] :type the authentication type: 'basic' or 'oauth'
+      # @option auth [String] :user the user to authenticate as (basic auth)
+      # @option auth [String] :password the user password (basic auth)
+      # @option auth [String] :token the OAuth bearer token (oauth auth)
+      # @param [Hash] opts Misc config options (mostly for development)
+      # @option opts [Fixnum] :ssl_verify_mode
+      # @option opts [Fixnum] :receive_timeout override the default receive timeout
+      #   seconds
+      # @option opts [Fixnum] :connect_timeout override the default connect timeout
+      #   seconds
+      # @option opts [OpenSSL::X509::Store]  :cert_store a custom cert store
+      # @option opts [Array]  :trust_ca an array of hashed dir paths or a file
+      # @option opts [String] :user_agent the http user agent to use in all requests
+      def initialize(auth, opts = {})
+        @log = Viewpoint::EWS.root_logger
+
+        @auth_type  = auth[:type]
+        @auth_token = auth[:token]
+
+        httpclient_opts = opts.slice(*SUPPORTED_HTTPCLIENT_OPTS)
+        @httpcli = HTTPClient.new(**httpclient_opts)
+
+        if opts[:cert_store].is_a?(OpenSSL::X509::Store)
+          @log.debug 'Applying custom cert_store provided via opts[:cert_store]'
+          # Assign the provided store directly
+          @httpcli.ssl_config.cert_store = opts[:cert_store]
+
+          @log.debug 'Skipping original :trust_ca handling due to provided :cert_store.'
+        elsif 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]
+        @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
+        @httpcli.receive_timeout = opts[:receive_timeout] if opts[:receive_timeout]
+        @httpcli.connect_timeout = opts[:connect_timeout] if opts[:connect_timeout]
+        @endpoint = auth[:endpoint]
       end
-    end
 
-    @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
-    @httpcli.receive_timeout = opts[:receive_timeout] if opts[:receive_timeout]
-    @httpcli.connect_timeout = opts[:connect_timeout] if opts[:connect_timeout]
-    @endpoint = endpoint
-  end
+      def set_auth(user, pass)
+        @httpcli.set_auth(@endpoint.to_s, user, pass)
+      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
+        get && true
+      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 <<~LOG
+          Received SOAP Response:
+          ----------------
+          #{Nokogiri::XML(respmsg).to_xml}
+          ----------------
+        LOG
+        opts[:raw_response] ? respmsg : ews.parse_soap_response(respmsg, opts)
+      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 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' }
+        headers['Authorization'] = "Bearer #{@auth_token}" if oauth_token?
+        check_response(@httpcli.post(@endpoint, xmldoc, headers))
+      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
 
+      # True when a non-empty OAuth bearer token was supplied.
+      def oauth_token?
+        @auth_type == 'oauth' && @auth_token.is_a?(String) && !@auth_token.empty?
+      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'] =~ /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)
+      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
+          unless resp.headers['Content-Type'] =~ /xml/
+            raise Errors::ServerError.new("Internal Server Error. Message: #{resp.body}", resp)
+          end
+
+          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::ResponseError.new("HTTP Error Code: #{resp.status}, Msg: #{resp.body}", resp)
+        end
       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]
+      # @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
   end
-
 end

data/lib/ews/connection_helper.rb

@@ -1,35 +1,38 @@
-=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]
+# frozen_string_literal: true
+
+#   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.
+
+module Viewpoint
+  module EWS
+    # Helpers for building authenticated HTTP connections.
+    module ConnectionHelper
+      def init_logging!
+        @log = Viewpoint::EWS.root_logger
+      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
   end
-
 end

data/lib/ews/convert_accessors.rb

@@ -1,56 +1,60 @@
-=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}"
+# frozen_string_literal: true
+
+#   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.
+module Viewpoint
+  module EWS
+    # Convert operations mixed into the EWS client.
+    module 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
+          rm.respond_to?(:code) ? rm.code : 'Unknown'
+          rm.respond_to?(:message_text) ? rm.message_text : 'Unknown'
+          raise EwsError, "Could not convert id. #{rm.code}: #{rm.message_text}"
+        end
+      end
     end
   end
-
-end # Viewpoint::EWS::ItemAccessors
+end