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 

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