viewpoint 0.1.24 → 0.1.25

data/lib/model/folder.rb

@@ -1,22 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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

data/lib/model/generic_folder.rb

@@ -1,22 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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
 
 # This class is inherited by all folder subtypes such as Mail, Calendar,
 # Tasks and Search.  It will serve as the brain for all of the methods that
@@ -36,7 +34,7 @@ module Viewpoint
       recoverableitemsroot recoverableitemsdeletions recoverableitemsversions
       recoverableitemspurges archiveroot archivemsgfolderroot archivedeleteditems
       archiverecoverableitemsroot archiverecoverableitemsdeletions
-      archiverecoverableitemsversions archiverecoverableitemspurges}
+      archiverecoverableitemsversions archiverecoverableitemspurges publicfoldersroot}
 
       @@event_types = %w{CopiedEvent CreatedEvent DeletedEvent ModifiedEvent MovedEvent NewMailEvent}
 
@@ -46,6 +44,7 @@ module Viewpoint
       #   delegate access to this folder or else this operation will fail.
       # @param [Hash] folder_shape
       # @option folder_shape [String] :base_shape IdOnly/Default/AllProperties
+      # @raise [EwsError] raised when the backend SOAP method returns an error.
       def self.get_folder(folder_id, act_as = nil, folder_shape = {:base_shape => 'Default'})
         resp = (Viewpoint::EWS::EWS.instance).ews.get_folder( [normalize_id(folder_id)], folder_shape, act_as )
         if(resp.status == 'Success')
@@ -60,11 +59,12 @@ module Viewpoint
       # Find subfolders of the passed root folder.  If no parameters are passed
       # this method will search from the Root folder.
       # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
-      #   or a FolderId (String)
+      #   or a FolderId (String). This is where to start the search from. Usually :root,:msgfolderroot,:publicfoldersroot
       # @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
+      # @raise [EwsError] raised when the backend SOAP method returns an error.
       def self.find_folders(root = :msgfolderroot, traversal = 'Shallow', shape = 'Default', folder_type = nil)
         if( folder_type.nil? )
           resp = (Viewpoint::EWS::EWS.instance).ews.find_folder( [normalize_id(root)], traversal, {:base_shape => shape} )
@@ -88,8 +88,11 @@ module Viewpoint
       end
 
       # Return a list of folder names
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      #   or a FolderId (String). This is where to start the search from. Usually :root,:msgfolderroot,:publicfoldersroot
       # @return [Array<String>] Return an Array of folder names.
-      def self.folder_names
+      # @raise [EwsError] raised when the backend SOAP method returns an error.
+      def self.folder_names(root = :msgfolderroot)
         resp = (Viewpoint::EWS::EWS.instance).ews.find_folder([:msgfolderroot], 'Shallow')
         if(resp.status == 'Success')
           flds = []
@@ -104,17 +107,22 @@ module Viewpoint
 
       # Gets a folder by name.  This name must match the folder name exactly.
       # @param [String] name The name of the folder to fetch.
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      #   or a FolderId (String). This is where to start the search from. Usually :root,:msgfolderroot,:publicfoldersroot
       # @param [String] shape the shape of the object to return IdOnly/Default/AllProperties
-      # @return [GenericFolder,nil] will return the folder by the given name of nil if not found.
-      def self.get_folder_by_name(name, shape = 'Default')
+      # @return [GenericFolder] will return the folder by the given name.
+      # @raise [EwsFolderNotFound] raised when a folder requested is not found
+      # @raise [EwsError] raised when the backend SOAP method returns an error.
+      def self.get_folder_by_name(name, root = :msgfolderroot, shape = 'Default', opts = {})
+        opts[:traversal] = 'Deep' unless opts.has_key?(:traversal)
         # For now the :field_uRI and :field_uRI_or_constant must be in an Array for Ruby 1.8.7 because Hashes
         # are not positional at insertion until 1.9
         restr = {:restriction =>
           {:is_equal_to => 
             [{:field_uRI => {:field_uRI=>'folder:DisplayName'}}, {:field_uRI_or_constant =>{:constant => {:value=>name}}}]}}
-        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder([:root], 'Deep', {:base_shape => shape}, restr)
+        resp = (Viewpoint::EWS::EWS.instance).ews.find_folder([root], opts[:traversal], {:base_shape => shape}, restr)
         if(resp.status == 'Success')
-          return nil if resp.items.empty?
+          raise EwsFolderNotFound, "The folder requested is invalid or unavailable" if resp.items.empty?
           f = resp.items.first
           f_type = f.keys.first.to_s.camel_case
           eval "#{f_type}.new(f[f.keys.first])"
@@ -123,6 +131,28 @@ module Viewpoint
         end
       end
 
+      # Gets a folder by the given path. The default search path is :msgfolderroot so if you want to
+      # specify a path at a different root change that parameter.
+      # @param [String] path the fully qualified path to a folder at the given root
+      #   @example "/myfolders/folder a/personal calendar"
+      # @param [String,Symbol] root An folder id, either a DistinguishedFolderId (must me a Symbol)
+      #   or a FolderId (String). This is where to start the search from. Usually :root,:msgfolderroot,:publicfoldersroot
+      # @param [String] shape the shape of the object to return IdOnly/Default/AllProperties
+      # @return [GenericFolder] will return the folder by the given path
+      # @raise [EwsFolderNotFound] raised when a folder requested is not found
+      # @raise [EwsError] raised when the backend SOAP method returns an error.
+      def self.get_folder_by_path(path, root = :msgfolderroot, shape = 'Default')
+        parts = path.split(/\//)
+        parts = parts.slice(1..(parts.length)) if parts.first.empty?
+        retfld = nil
+        parts.each do |p|
+          fld = self.get_folder_by_name(p, root, shape, {:traversal => 'Shallow'})
+          root = fld.id
+          retfld = fld if(fld.display_name.downcase == p.downcase)
+        end
+        retfld
+      end
+
       attr_accessor :folder_id, :change_key, :parent_id, :sync_state
       attr_reader :subscription_id, :watermark
       alias :id :folder_id
@@ -196,7 +226,7 @@ module Viewpoint
       end
 
       # Checks a subscribed folder for events
-      # @returns [Array] An array of Event items
+      # @return [Array] An array of Event items
       # @todo check for subscription expiry
       def get_events
         begin
@@ -275,22 +305,22 @@ module Viewpoint
       # @param [String,nil] exclude_str A string to exclude from matches against the subject.  This is optional.
       def search_by_subject(match_str, exclude_str = nil)
         match = {:contains =>
-          {
-            :containment_mode => 'Substring',
-            :containment_comparison => 'IgnoreCase',
-            :field_uRI => {:field_uRI=>'item:Subject'},
-            :constant => {:value =>match_str}
-          }
+          [
+            {:containment_mode => 'Substring'},
+            {:containment_comparison => 'IgnoreCase'},
+            {:field_uRI => {:field_uRI=>'item:Subject'}},
+            {:constant => {:value =>match_str}}
+          ]
         }
         unless exclude_str.nil?
           excl = {:not =>
             {:contains =>
-              {
-                :containment_mode => 'Substring',
-                :containment_comparison => 'IgnoreCase',
-                :field_uRI => {:field_uRI=>'item:Subject'},
-                :constant => {:value =>exclude_str}
-              }
+              [
+                {:containment_mode => 'Substring'},
+                {:containment_comparison => 'IgnoreCase'},
+                {:field_uRI => {:field_uRI=>'item:Subject'}},
+                {:constant => {:value =>exclude_str}}
+              ]
             }
           }
 

data/lib/model/item.rb

@@ -1,23 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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
 
 # This class is inherited by all Item subtypes such as Message, Event,
 # and Task.  It will serve as the brain for all of the methods that

data/lib/model/item_attachment.rb

@@ -1,22 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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

data/lib/model/item_field_uri_map.rb

@@ -1,3 +1,21 @@
+=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
     module ItemFieldUriMap

data/lib/model/mailbox_user.rb

@@ -1,22 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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
@@ -28,10 +26,12 @@ module Viewpoint
       include Model
 
       # Resolve a user in the Exchange Data Store
-      # @param [String] A user to resolve to.
+      # @param [String] resolve A user to resolve to.
       # @return [MailboxUser,Array] If it resolves to one user then it returns a MailboxUser.
       #   If it resolves to more than one user an Array of MailboxUsers are returned.  If an
       #   error ocurrs an exception is raised.
+      # @todo - rename "resolve" to something more descriptive
+      #   - standardize on a common return type???
       def self.find_user(resolve)
         resp = (Viewpoint::EWS::EWS.instance).ews.resolve_names(resolve)
         if(resp.status == 'Success')

data/lib/model/meeting_cancellation.rb

@@ -1,22 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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

data/lib/model/meeting_message.rb

@@ -1,22 +1,20 @@
-#############################################################################
-# Copyright © 2010 Dan Wanek <dan.wanek@gmail.com>
-#
-#
-# This file is part of Viewpoint.
-# 
-# Viewpoint is free software: you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or (at
-# your option) any later version.
-# 
-# Viewpoint is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License along
-# with Viewpoint.  If not, see <http://www.gnu.org/licenses/>.
-#############################################################################
+=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