viewpoint 0.1.26 → 1.1.1

data/README

@@ -1,114 +0,0 @@
---------------------------------------------------------------------------
-                   Viewpoint for Exchange Web Services
-                http://github.com/zenchild/Viewpoint/wiki
---------------------------------------------------------------------------
-This program attempts to create a client access library for Exchange Web
-Services (EWS) in Ruby.
-
-!!!CAUTION!!!  This is currently BETA code and has changed dramatically from
-the original version of Viewpoint which was based on Soap4r.  This version
-has essentially been gutted and written on top of Handsoap.  Development
-has been much more flexible, but the interface to Viewpoint has changed
-quite a bit.  I have tried to write good code comments and I will keep
-enhancing this.  I will also try and post examples on my blog as I write
-them or they are asked for.
-
-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)
-
---------------------------------------------------------------------------
-MAJOR CHANGES TO THE FIRST VERSION:
-
-New SOAP backend
-  Viewpoint now uses Handsoap as its back-end instead of soap4r.  While
-  soap4r does some very nice things for you automatically, it ends up
-  making your code base fairly large and it complicates any customizations
-  that you might want to make.  One example is adding custom headers. Soap4r
-  required you to create a subclass to use as a sort of hook. I can do the
-  same thing in Handsoap with a one-liner in the services #on_create_document
-  method.
-
-Models are completely rewritten
-  The models are completely new and not backward compatible with the old
-  version of Viewpoint.  Some of the methods still exist, but don't count
-  on them.  I've tried to make this version much more extensible than the
-  last.
-
-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.
-
-  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.
-
-Misc other changes
-  Since it's a complete rewrite there are tons of other changes that you'll
-  notice.  I've tried to keep the code comments coming so stay tuned to the
-  API docs for library information.  I'll also be posting more examples to
-  my blog.
-
---------------------------------------------------------------------------
-TO USE:
-require 'rubygems'
-require 'viewpoint'
-# See REQUIRED GEMS below
-
-REQUIRED GEMS:
-
-# Handsoap (Thanks jrun for pointing me this way!)
-gem install -r handsoap
-# Nokogiri XML Parser
-gem install -r nokogiri
-# HttpClient
-gem install -r httpclient
-# NTLM Library
-gem install -r rubyntlm
-
-# iCalendar (still forthcoming in this release)
-gem install -r icalendar
-
---------------------------------------------------------------------------
-DESIGN GOALS/GUIDELINES:
-
-  1. The SOAP back-end should not know about the Model.
-    I went around and around on this one for awhile.  There are some
-    simplicity advantages to creating Model objects within the SOAP
-    responses, but I ultimately decided against it so that one could use
-    the SOAP back-end without the Model.  Essentially the SOAP classes
-    pass back a Hash that the Model uses to create its own objects.
-
-  2. The use of Hashes is not a crime.
-    While some people decidedly do not like Hashes and believe complex
-    hashing should be in the form of objects, there are some instances
-    where hashing is just plain simpler and flexible.  To that end, I use
-    hashes pretty extensively in Viewpoint, both for objects being passed
-    to the SOAP back-end and returned from it.
-
-  3. Follow EWS naming conventions where it makes sense.
-    I try and follow the naming conventions of the Exchange Web Service
-    operations as much as it makes sense.  There are some things howerver
-    where they do not and I have deviated somewhat.  For example,
-    an instance method named delete_folder doesn't make much sense, but
-    an instance method named delete! is pretty clear what it deletes.
---------------------------------------------------------------------------
-!!!SHOUTS OUT!!!
---------------------------------------------------------------------------
-* Thanks to Harold Lee (https://github.com/haroldl) for working on the
-  get_user_availability code.
---------------------------------------------------------------------------
-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/lib/model/calendar_folder.rb

@@ -1,67 +0,0 @@
-=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
-  module EWS
-    class CalendarFolder < GenericFolder
-
-      # Find folders of type Task
-      # @see GenericFolder.find_folders
-      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
-      #   or a FolderId (String)
-      # @param [String] traversal Shallow/Deep/SoftDeleted
-      # @param [String] shape the shape to return IdOnly/Default/AllProperties
-      # @param [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
-      def self.find_folders(root = :msgfolderroot, traversal = 'Deep', shape = 'Default', folder_type = 'IPF.Appointment')
-        super(root, traversal, shape, folder_type)
-      end
-
-
-      # initialize with an item of CalendarFolderType
-      def initialize(folder)
-        super(folder)
-
-        # @todo Handle:
-        #   <SharingEffectiveRights/>
-      end
-
-      # Fetch only items from today (since midnight)
-      def todays_items(opts = {})
-        #This is a bit convoluted for pre-1.9.x ruby versions that don't support to_datetime
-        items_between(DateTime.parse(Date.today.to_s), DateTime.parse((Date.today + 1).to_s), opts)
-      end
-
-      # Fetch items since a give DateTime
-      # @param [DateTime] start_date_time the time to fetch Items since.
-      def items_since(start_date_time, opts = {})
-        items_between(start_date_time, DateTime.now, opts)
-      end
-
-      # Find Calendar Items between two dates
-      # @param [DateTime] start_date the date to start the search from
-      # @param [DateTime] end_date the date to end the search at
-      # @param [Hash] opts misc opts like restrictions, etc
-      def items_between(start_date, end_date, opts = {})
-        opts[:calendar_view] = {:max_entries_returned => 256, :start_date => start_date, :end_date => end_date}
-        find_items(opts)
-      end
-
-    end # CalendarFolder
-  end # EWS
-end # Viewpoint

data/lib/model/calendar_item.rb

@@ -1,267 +0,0 @@
-=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
-  module EWS
-    class CalendarItem < Message
-
-      # This is a class method that creates a new CalendarItem in the Exchange Data Store.
-      # @param [Hash] item A Hash of values based on values found here:
-      #   http://msdn.microsoft.com/en-us/library/aa564765.aspx
-      # @param [String, Symbol] folder_id The folder to create this item in. Either a
-      #   DistinguishedFolderId (must me a Symbol) or a FolderId (String)
-      # @param [String] send_invites "SendToNone/SendOnlyToAll/SendToAllAndSaveCopy"
-      #   See:  http://msdn.microsoft.com/en-us/library/aa565209.aspx
-      # @example Typical Usage
-      #   item = { :subject => {:text => 'Planning'},
-      #     :body => {:body_type => 'Text', :text => 'This is a test'},
-      #     :start => {:text => '2010-07-29T14:00:00'},
-      #     :end => {:text => '2010-07-29T15:00:00'},
-      #     :is_all_day_event => {:text => 'false'},
-      #     :location => {:text => 'Room 234'},
-      #     :required_attendees => {:attendee => {:mailbox => {:email_address => {:text => 'test@test.com'}}}}
-      #   }
-      # @example Minimal Usage
-      #   item = { :subject => {:text => 'Planning'},
-      #     :start => {:text => '2010-07-29T14:00:00'},
-      #     :end => {:text => '2010-07-29T15:00:00'}
-      #   }
-      def self.create_item_from_hash(item, folder_id = :calendar, send_invites = 'SendToAllAndSaveCopy')
-        conn = Viewpoint::EWS::EWS.instance
-        resp = conn.ews.create_calendar_item(folder_id, item, send_invites)
-        if(resp.status == 'Success')
-          resp = resp.items.shift
-          self.new(resp[resp.keys.first])
-        else
-          raise EwsError, "Could not create CalendarItem. #{resp.code}: #{resp.message}"
-        end
-      end
-      
-      # Format attendees (usually called from #add_attendees!
-      # @param [Array,String,Hash,MailboxUser] attendees
-      # @param [Symbol] type the type of the attendees :required_attendees/:optional_attendees/:resources
-      def self.format_attendees(attendees, type=:required_attendees)
-        case attendees.class.to_s
-        when 'String'
-          return {type => [{:attendee => {:mailbox => {:email_address => {:text => attendees}}}}]}
-        when /Attendee|MailboxUser/
-          return {type => [{:attendee => {:mailbox => [{:name => {:text => attendees.name}}, {:email_address => {:text => attendees.email_address}}]}}]}
-        when 'Hash'
-          return {type => [{:attendee => {:mailbox => [{:name => {:text => attendees[:name]}}, {:email_address => {:text => attendees[:email_address]}}]}}]}
-        when 'Array'
-          as = {type => []}
-          attendees.each do |a|
-            as.merge!(format_attendees(a, type)) {|k,v1,v2| v1 + v2}
-          end
-          return as
-        end
-      end
-
-      # Create a new CalendarItem.
-      # If a block is given it is passed an opts hash with the keys :folder_id and :send_invites.
-      #   See ::create_item_from_hash for details
-      # @param [DateTime] v_start The date and time when the CalendarItem begins
-      # @param [DateTime] v_end The date and time when the CalendarItem ends
-      # @param [String] subject The subject of this Item
-      # @param [String,optional] body The body of this object
-      # @param [String,optional] location The location where this calendar item will ocurr
-      # @param [Array<String,MailboxUser,Attendee>,optional] required_attendees An Array of e-mail addresses of required attendees
-      # @param [Array<String,MailboxUser,Attendee>,optional] optional_attendees An Array of e-mail addresses of optional attendees
-      # @param [Array<String,MailboxUser,Attendee>,optional] resources An Array of e-mail addresses of resources
-      def self.create_item(v_start, v_end, subject, body = nil, location = nil, required_attendees=[], optional_attendees=[], resources=[])
-        item = {}
-        opts = {:folder_id => :calendar, :send_invites => 'SendToAllAndSaveCopy'}
-        yield opts if block_given?
-        item[:start] = {:text => v_start.to_s}
-        item[:end] = {:text => v_end.to_s}
-        item[:subject] = {:text => subject}
-        item[:body] = {:text => body, :body_type => 'Text'} unless body.nil?
-        item[:location] = {:text => location} unless location.nil?
-        item.merge!(self.format_attendees(required_attendees)) unless required_attendees.empty?
-        item.merge!(self.format_attendees(optional_attendees, :optional_attendees)) unless optional_attendees.empty?
-        resources.each do |a|
-          item[:resources] = [] unless item[:resources].is_a?(Array)
-          item[:resources] << {:attendee => {:mailbox => {:email_address => {:text => a}}}}
-        end
-        self.create_item_from_hash(item, opts[:folder_id], opts[:send_invites])
-      end
-
-      # Initialize an Exchange Web Services item of type CalendarItem
-      def initialize(ews_item, opts={})
-        super(ews_item, opts)
-      end
-      
-      # Add attendees to this CalendarItem. This does not commit the changes so you will have to use #save! to
-      #   commit them back. If you want to commit them at once look at the #add_attendees! method.
-      # @param [Array] required Required attendees to add to this object
-      #   Array values of attendees may be simple email strings, MailboxUser items or Hashes in the form
-      #   {:email_address => 'email@test', :name => 'My Name'}.
-      # @param [Array] optional Optional attendees to add to this object
-      #   see the notes for the 'required' parameter.
-      # @example
-      #   ['user1@example.org', 'user2@example.org']
-      #   or
-      #   [{:name => 'User1', :email_address => 'user1@example.org'}, {:name => 'User2', :email_address => 'user2@example.org'}]
-      #   or
-      #   ['user1@example.org', 'user2@example.org'], ['user3@example.org', 'user4@example.org']
-      #   or
-      #   [{:name => 'User1', :email_address => 'user1@example.org'}, {:name => 'User2', :email_address => 'user2@example.org'}],
-      #     [{:name => 'User3', :email_address => 'user3@example.org'}, {:name => 'User4', :email_address => 'user4@example.org'}]
-      # @return [Boolean] true on success, false otherwise
-      # @todo add ability to add resources
-      def add_attendees(required, optional = [], resources = [])
-        update = {}
-        update.merge!(self.class.format_attendees(required)) unless required.empty? || required.nil?
-        update.merge!(self.class.format_attendees(optional, :optional_attendees)) unless optional.empty? || optional.nil?
-
-        return false if update.empty?
-
-        @required_attendees, @optional_attendees = nil, nil
-        changes = update_attribs(update, :append)
-        @updates.merge!({:preformatted => changes}) {|k,v1,v2| v1 + v2}
-        true
-      end
-
-      # This is the same as the #add_attendees method, but it actually commits the change back to Exchange
-      # @see #add_attendees
-      def add_attendees!(required, optional = [], resources = [])
-        add_attendees(required, optional, resources)
-        save!
-      end
-
-      # Remove the attendees from the attendee list. This does not commit the changes so you will have to use
-      #   #save! to commit them back. If you want to commit them at once look at the #remove_attendees! method.
-      # @param [Array] attendees the attendees to remove from this CalendarItem
-      #   [Viewpoint::EWS::Attendee<user1>, Viewpoint::EWS::Attendee<user2>] or
-      #   ['user1@example.org', 'user2@example.org']
-      # @return [Boolean] false if the object is not updated, true otherwise
-      def remove_attendees(attendees)
-        return false if attendees.empty?
-
-        emails = attendees.is_a?(Array) ? attendees : attendees.values
-        emails = emails.collect do |v|
-          case v.class.to_s
-          when 'String'
-            v
-          when /MailboxUser|Attendee/
-            v.email_address
-          when 'Hash'
-            v[:email_address]
-          end
-        end
-
-        update = {}
-        [:required_attendees, :optional_attendees].each do |type|
-          ivar = self.send(type.to_s)
-          next if ivar.nil?
-
-          required_a = ivar.select {|v| !emails.include?(v.email_address) }
-          formatted_a = self.class.format_attendees(required_a, type)
-          if formatted_a[type].empty?
-            update[:preformatted] ||= []
-            update[:preformatted] << {:delete_item_field => [{:field_uRI => {:field_uRI=>FIELD_URIS[type][:text]}}]}
-            self.instance_eval "undef #{type}"
-          else
-            update.merge!(formatted_a)
-          end
-        end
-
-        return false if update.empty?
-
-        @required_attendees, @optional_attendees = nil, nil
-        @updates.merge!(update) {|k,v1,v2| v1 + v2}
-        true
-      end
-
-      # This is the same as the #remove_attendees method, but it actually commits the change back to Exchange
-      # @see #remove_attendees
-      def remove_attendees!(attendees)
-        remove_attendees(attendees)
-        save!
-      end
-
-      # Call UpdateItem for this item with the passed updates
-      # @param [Hash] updates a well-formed update hash
-      # @example {:set_item_field=>{:field_u_r_i=>{:field_u_r_i=>"message:IsRead"}, :message=>{:is_read=>{:text=>"true"}}}}
-      # TODO: This is a stand-in for the Item#update! method until I can firm it up a bit. It is neccessary for the SendMeetingInvitationsOrCancellations attrib
-      def update!(updates)
-        conn = Viewpoint::EWS::EWS.instance
-        resp = conn.ews.update_item([{:id => @item_id, :change_key => @change_key}], {:updates => updates},
-                                    {:message_disposition => 'SaveOnly', :conflict_resolution => 'AutoResolve', :send_meeting_invitations_or_cancellations => 'SendOnlyToChanged'})
-        if resp.status == 'Success'
-          @item_id = resp.items.first[resp.items.first.keys.first][:item_id][:id]
-          @change_key = resp.items.first[resp.items.first.keys.first][:item_id][:change_key]
-          @shallow = true
-          deepen!
-        else
-          raise EwsError, "Trouble updating Item. #{resp.code}: #{resp.message}"
-        end
-
-      end
-
-      # Delete this item
-      # @param [Boolean] soft Whether or not to do a soft delete.  By default EWS will do a 
-      #   hard delete of this item.  See the MSDN docs for more info:
-      #   http://msdn.microsoft.com/en-us/library/aa562961.aspx
-      # @param [String] cancel_type "SendToNone/SendOnlyToAll/SendToAllAndSaveCopy"
-      #   Default is SendOnlyToAll
-      # @return [Boolean] Whether or not the item was deleted
-      # @todo Add exception handling for failed deletes
-      #
-      def delete!(soft=false, cancel_type='SendOnlyToAll')
-        deltype = soft ? 'SoftDelete' : 'HardDelete'
-        resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], deltype, cancel_type)
-        self.clear_object!
-        resp.status == 'Success'
-      end
-
-      # Delete this item by moving it to the Deleted Items folder
-      # @see  http://msdn.microsoft.com/en-us/library/aa562961.aspx
-      # @return [Boolean] Whether or not the item was deleted
-      # @todo Add exception handling for failed deletes
-      def recycle!(cancel_type='SendOnlyToAll')
-        resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], 'MoveToDeletedItems', cancel_type)
-        self.clear_object!
-        resp.status == 'Success'
-      end
-
-
-      private
-
-      def init_methods
-        super
-        define_str_var :calendar_item_type, :duration, :time_zone, :when, :location, :u_i_d, {:u_i_d => :uid}
-        define_str_var :legacy_free_busy_status, :my_response_type, :meeting_workspace_url, :net_show_url
-        define_int_var :adjacent_meeting_count, :appointment_sequence_number, :appointment_state
-        define_int_var :conference_type, :conflicting_meeting_count
-        define_mbox_user :organizer
-        define_bool_var :is_all_day_event, :is_cancelled, :is_meeting, :is_online_meeting, :is_recurring
-        define_bool_var :allow_new_time_proposal, :meeting_request_was_sent
-        define_datetime_var :appointment_reply_time, :start, :end, :original_start
-        define_attendees :required_attendees, :optional_attendees, :resources
-
-        # @todo Handle:
-        #   <AdjacentMeetings/> <ConflictingMeetings/> <DeletedOccurrences/>
-        #   <FirstOccurrence/> <LastOccurrence/> <ModifiedOccurrences/>
-        #   <StartTimeZone/> <EndTimeZone/> <MeetingTimeZone/>
-        #   <Recurrence/>
-      end
-
-    end # CalendarItem
-  end # EWS
-end # Viewpoint