Module: Viewpoint::EWS::FolderAccessors

Includes:
Viewpoint::EWS
Included in:
Viewpoint::EWSClient
Defined in:
lib/ews/folder_accessors.rb

Overview

This file is part of Viewpoint; the Ruby library for Microsoft Exchange Web Services.

Copyright © 2011 Dan Wanek <[email protected]>

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.

Constant Summary collapse

FOLDER_TYPE_MAP = 
{
  :mail     => 'IPF.Note',
  :calendar => 'IPF.Appointment',
  :task     => 'IPF.Task',
}

Constants included from Viewpoint::EWS

ConnectingSID

Instance Attribute Summary

Attributes included from Viewpoint::EWS

#logger

Instance Method Summary collapse

Methods included from Viewpoint::EWS

#remove_impersonation, root_logger, #set_impersonation

Instance Method Details

#folders(opts = {}) {|obj| ... } ⇒ Array Also known as: find_folders

Find subfolders of the passed root folder. If no parameters are passed this method will search from the Root folder.

Parameters:

  • opts (Hash) (defaults to: {}) —

    Misc options to control request

Options Hash (opts):

  • :root (String, Symbol) —

    Either a FolderId(String) or a DistinguishedFolderId(Symbol) . This is where to start the search from. Usually :root,:msgfolderroot, or :publicfoldersroot

  • :traversal (Symbol) —

    :shallow/:deep/:soft_deleted

  • :shape (Symbol) —

    :id_only/:default/:all_properties

  • :folder_type (optional, String) —

    an optional folder type to limit the search to like ‘IPF.Task’

Yields:

  • (obj)

Returns:

  • (Array) —

    Returns an Array of Folder or subclasses of Folder

Raises:

  • (EwsError) —

    raised when the backend SOAP method returns an error.



39
40
41
42
43
44
45
46
47
 
# File 'lib/ews/folder_accessors.rb', line 39

def folders(opts={})
  opts = opts.clone
  args = find_folders_args(opts)
  obj = OpenStruct.new(opts: args, restriction: {})
  yield obj if block_given?
  merge_restrictions! obj
  resp = ews.find_folder( args )
  find_folders_parser(resp)
end

#get_folder(folder_id, opts = {}) ⇒ Object

Get a specific folder by id or symbol

Parameters:

  • folder_id (String, Symbol, Hash) —

    Either a FolderId(String) or a DistinguishedFolderId(Symbol). You can also pass a Hash in the form: <fold_id>, change_key: <change_key>

  • opts (Hash) (defaults to: {}) —

    Misc options to control request

Options Hash (opts):

  • :shape (Symbol) —

    :id_only/:default/:all_properties

  • :act_as (String, nil) —

    User to act on behalf as. This user must have been given delegate access to the folder or this operation will fail.

Raises:

  • (EwsError) —

    raised when the backend SOAP method returns an error.



59
60
61
62
63
64
 
# File 'lib/ews/folder_accessors.rb', line 59

def get_folder(folder_id, opts = {})
  opts = opts.clone
  args = get_folder_args(folder_id, opts)
  resp = ews.get_folder(args)
  get_folder_parser(resp)
end

#get_folder_by_name(name, opts = {}) ⇒ Object

Get a specific folder by its name

Parameters:

  • name (String) —

    The folder name

  • opts (Hash) (defaults to: {}) —

    Misc options to control request

Options Hash (opts):

  • :parent (String, Symbol) —

    Either a FolderId(String) or a DistinguishedFolderId(Symbol) . This is the parent folder.

  • :shape (Symbol) —

    :id_only/:default/:all_properties

  • :act_as (String, nil) —

    User to act on behalf as. This user must have been given delegate access to the folder or this operation will fail.

Raises:

  • (EwsError) —

    raised when the backend SOAP method returns an error.



75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/ews/folder_accessors.rb', line 75

def get_folder_by_name(name, opts={})
  opts = opts.clone
  opts[:root] = opts.delete(:parent)
  folders(opts) do |obj|
    obj.restriction = {
      :is_equal_to =>
      [
        {:field_uRI => {:field_uRI=>'folder:DisplayName'}},
        {:field_uRI_or_constant => {:constant => {:value=>name}}}
      ]
    }
  end.first
end

#make_folder(name, opts = {}) ⇒ Object Also known as: mkfolder

Parameters:

  • name (String) —

    The name of the new folder

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :parent (String, Symbol) —

    Either a FolderId(String) or a DistinguishedFolderId(Symbol) . This is the parent folder.

  • :type (Symbol) —

    the type of folder to create. must be one of :folder, :calendar, :contacts, :search, or :tasks

See Also:



96
97
98
99
100
101
 
# File 'lib/ews/folder_accessors.rb', line 96

def make_folder(name, opts={})
  parent = opts[:parent] || :msgfolderroot
  resp = ews.create_folder :parent_folder_id => {:id => parent},
    :folders => [folder_type(opts[:type]) => {:display_name => name}]
  create_folder_parser(resp).first
end

#sync_folders(opts = {}) {|Hash| ... } ⇒ Hash

Get a specific folder by id or symbol

Parameters:

  • opts (Hash) (defaults to: {}) —

    Misc options to control request

Options Hash (opts):

  • :shape (Symbol) —

    :id_only/:default/:all_properties

  • :folder_id (String, Symbol, Hash) —

    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: <fold_id>, change_key: <change_key>

  • :sync_state (String) —

    an optional Base64 encoded SyncState String from a previous sync call.

Yields:

  • (Hash) —

    yields the formatted argument Hash for last-minute modification before calling the backend EWS method.

Returns:

  • (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

Raises:

  • (EwsError) —

    raised when the backend SOAP method returns an error.



121
122
123
124
125
126
127
 
# File 'lib/ews/folder_accessors.rb', line 121

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