Class: Viewpoint::EWS::SOAP::ExchangeWebService

Inherits:
Handsoap::Service
  • Object
show all
Includes:
Viewpoint::EWS::SOAP
Defined in:
lib/soap/handsoap/ews_service.rb

Constant Summary collapse

SOAP_ACTION_PREFIX = 
"http://schemas.microsoft.com/exchange/services/2006/messages"
@@raw_soap = 
false
@@http_options = 
nil

Constants included from Viewpoint::EWS::SOAP

ActiveDirectory, ActiveDirectoryContacts, Contacts, ContactsActiveDirectory, NS_EWS_MESSAGES, NS_EWS_TYPES, NS_SOAP

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ ExchangeWebService

Returns a new instance of ExchangeWebService.



36
37
38
39
40
41
 
# File 'lib/soap/handsoap/ews_service.rb', line 36

def initialize()
  if $DEBUG
    @debug = File.new('ews_debug.out', 'w')
    @debug.sync = true
  end
end

Class Method Details

.raw_soap! ⇒ Object

Turn off parsing and just return the soap response



49
50
51
 
# File 'lib/soap/handsoap/ews_service.rb', line 49

def self.raw_soap!
  @@raw_soap = true
end

.set_auth(user, pass) ⇒ Object 



43
44
45
46
 
# File 'lib/soap/handsoap/ews_service.rb', line 43

def self.set_auth(user,pass)
  @@user = user
  @@pass = pass
end

.set_http_options(option_hash) ⇒ Object

Set various HTTP options like ssl_ca_trust, etc



54
55
56
57
58
59
60
 
# File 'lib/soap/handsoap/ews_service.rb', line 54

def self.set_http_options(option_hash)
  if @@http_options.nil?
    @@http_options = option_hash
  else
    @@http_options.merge!(option_hash)
  end
end

Instance Method Details

#add_delegate(owner, delegate, permissions) ⇒ Object

Adds one or more delegates to a principal’s mailbox and sets specific access permissions.

Parameters:

  • owner (String) —

    The user that is delegating permissions

  • delegate (String) —

    The user that is being given delegate permission

  • permissions (Hash) —

    A hash of permissions that will be delegated. This Hash will eventually be passed to add_hierarchy! in the builder so it is in that format.

See Also:



686
687
688
689
690
691
692
693
694
 
# File 'lib/soap/handsoap/ews_service.rb', line 686

def add_delegate(owner, delegate, permissions)
  action = "#{SOAP_ACTION_PREFIX}/AddDelegate"
  resp = invoke("#{NS_EWS_MESSAGES}:AddDelegate", action) do |root|
    build!(root) do
      add_delegate!(owner, delegate, permissions)
    end
  end
  parse!(resp)
end

#convert_id ⇒ Object 



230
231
232
233
234
235
236
 
# File 'lib/soap/handsoap/ews_service.rb', line 230

def convert_id
  action = "#{SOAP_ACTION_PREFIX}/ConvertId"
  resp = invoke("#{NS_EWS_MESSAGES}:ConvertId", action) do |convert_id|
    build_convert_id!(convert_id)
  end
  parse_convert_id(resp)
end

#copy_folder ⇒ Object 



296
297
298
299
300
301
302
 
# File 'lib/soap/handsoap/ews_service.rb', line 296

def copy_folder
  action = "#{SOAP_ACTION_PREFIX}/CopyFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:CopyFolder", action) do |copy_folder|
    build_copy_folder!(copy_folder)
  end
  parse_copy_folder(resp)
end

#copy_item(item_ids, folder_id) ⇒ Object

Copies items and puts the items in a different folder

Parameters:

  • item_ids (Array) —

    An Array of item ids

  • folder_id (String, Symbol) —

    either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

See Also:



602
603
604
605
606
607
608
609
610
611
 
# File 'lib/soap/handsoap/ews_service.rb', line 602

def copy_item(item_ids, folder_id)
  action = "#{SOAP_ACTION_PREFIX}/CopyItem"
  resp = invoke("#{NS_EWS_MESSAGES}:CopyItem", action) do |root|
    build!(root) do
      to_folder_id!(root, folder_id)
      item_ids!(root, item_ids)
    end
  end
  parse!(resp)
end

#create_attachment(parent_id, files = [], items = []) ⇒ Object

TODO:

Need to implement attachment of Item types

Creates either an item or file attachment and attaches it to the specified item.

Parameters:

  • parent_id (String, Hash) —

    The id of the Item. If this is a Hash it should contain the Id and the ChangeKey.

  • files (Array<Hash>) (defaults to: []) —

    An Array of Base64 encoded Strings with an associated name hash format= :name => <name>, :content => <Base64 encoded string>

  • items (Array) (defaults to: []) —

    Exchange Items to attach to this Item

Options Hash (parent_id):

  • :id (String) —

    The item Id

  • :change_key (String) —

    The ChangeKey

See Also:



623
624
625
626
627
628
629
630
631
632
 
# File 'lib/soap/handsoap/ews_service.rb', line 623

def create_attachment(parent_id, files = [], items = [])
  action = "#{SOAP_ACTION_PREFIX}/CreateAttachment"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateAttachment", action) do |root|
    build!(root) do
      item_id!(root, parent_id, "#{NS_EWS_MESSAGES}:ParentItemId")
      attachments!(root, files, items)
    end
  end
  parse!(resp)
end

#create_calendar_item(folder_id, items, send_invites = 'SendToAllAndSaveCopy') ⇒ Object

Operation is used to create calendar items

Parameters:

  • folder_id (String, Symbol) —

    The folder to create this item in. Either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • items (Hash, Array) —

    An array of item Hashes or a single item Hash. Hash This Hash will eventually be passed to add_hierarchy! in the builder so it is in that format. Values should be based on values found here: msdn.microsoft.com/en-us/library/aa564765.aspx

  • send_invites (String) (defaults to: 'SendToAllAndSaveCopy') —

    “SendToNone/SendOnlyToAll/SendToAllAndSaveCopy”

See Also:



470
471
472
473
474
475
476
477
478
 
# File 'lib/soap/handsoap/ews_service.rb', line 470

def create_calendar_item(folder_id, items, send_invites = 'SendToAllAndSaveCopy')
  action = "#{SOAP_ACTION_PREFIX}/CreateItem"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateItem", action) do |node|
    build!(node) do
      create_item!(folder_id, items, message_disposition=false, send_invites, 'calendar')
    end
  end
  parse!(resp)
end

#create_contact_item(folder_id, items) ⇒ Object

Operation is used to create contact items This is actually a CreateItem operation but they differ for different types of Exchange objects so it is named appropriately here.

Parameters:

  • folder_id (String, Symbol) —

    The folder to save this task in. Either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • items (Hash, Array) —

    An array of item Hashes or a single item Hash. Hash values should be based on values found here: msdn.microsoft.com/en-us/library/aa581315.aspx This Hash will eventually be passed to add_hierarchy! in the builder so it is in that format.

See Also:

  • http://msdn.microsoft.com/en-us/library/aa580529.aspx


512
513
514
515
516
517
518
519
520
 
# File 'lib/soap/handsoap/ews_service.rb', line 512

def create_contact_item(folder_id, items)
  action = "#{SOAP_ACTION_PREFIX}/CreateItem"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateItem", action) do |node|
    build!(node) do
      create_item!(folder_id, items, nil, false, 'contact')
    end
  end
  parse!(resp)
end

#create_folder(parent_folder_id, folder_name) ⇒ Object

Creates folders, calendar folders, contacts folders, tasks folders, and search folders.

Parameters:

See Also:



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/soap/handsoap/ews_service.rb', line 244

def create_folder(parent_folder_id, folder_name)
  action = "#{SOAP_ACTION_PREFIX}/CreateFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateFolder", action) do |root|
    build!(root) do
      root.add("#{NS_EWS_MESSAGES}:ParentFolderId") do |pfid|
        folder_id!(pfid, parent_folder_id)
      end
      folder_name = (folder_name.is_a?(Array)) ? folder_name : [folder_name]
      root.add("#{NS_EWS_MESSAGES}:Folders") do |fids|
        folder_name.each do |f|
          add_hierarchy!(fids, {:folder => {:display_name => {:text => f}}})
        end
      end
    end
  end
  parse!(resp)
end

#create_managed_folder ⇒ Object 



656
657
658
659
660
661
662
 
# File 'lib/soap/handsoap/ews_service.rb', line 656

def create_managed_folder
  action = "#{SOAP_ACTION_PREFIX}/CreateManagedFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateManagedFolder", action) do |create_managed_folder|
    build_create_managed_folder!(create_managed_folder)
  end
  parse_create_managed_folder(resp)
end

#create_message_item(folder_id, items, message_disposition = 'SaveOnly') ⇒ Object

Operation is used to create e-mail messages This is actually a CreateItem operation but they differ for different types of Exchange objects so it is named appropriately here.

Parameters:

  • folder_id (String, Symbol) —

    The folder to save this message in. Either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • items (Hash, Array) —

    An array of item Hashes or a single item Hash. Hash This Hash will eventually be passed to add_hierarchy! in the builder so it is in that format. Values should be based on values found here: msdn.microsoft.com/en-us/library/aa494306.aspx

  • message_disposition (String) (defaults to: 'SaveOnly') —

    “SaveOnly/SendOnly/SendAndSaveCopy” See: msdn.microsoft.com/en-us/library/aa565209.aspx

See Also:



451
452
453
454
455
456
457
458
459
 
# File 'lib/soap/handsoap/ews_service.rb', line 451

def create_message_item(folder_id, items, message_disposition = 'SaveOnly')
  action = "#{SOAP_ACTION_PREFIX}/CreateItem"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateItem", action) do |node|
    build!(node) do
      create_item!(folder_id, items, message_disposition, send_invites=false, 'message')
    end
  end
  parse!(resp)
end

#create_task_item(folder_id, items, message_disposition = 'SaveOnly') ⇒ Object

Operation is used to create task items This is actually a CreateItem operation but they differ for different types of Exchange objects so it is named appropriately here.

Parameters:

  • folder_id (String, Symbol) —

    The folder to save this task in. Either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • items (Hash, Array) —

    An array of item Hashes or a single item Hash. Hash values should be based on values found here: msdn.microsoft.com/en-us/library/aa494306.aspx This Hash will eventually be passed to add_hierarchy! in the builder so it is in that format.

  • message_disposition (String) (defaults to: 'SaveOnly') —

    “SaveOnly/SendOnly/SendAndSaveCopy” See: msdn.microsoft.com/en-us/library/aa565209.aspx

See Also:



492
493
494
495
496
497
498
499
500
 
# File 'lib/soap/handsoap/ews_service.rb', line 492

def create_task_item(folder_id, items, message_disposition = 'SaveOnly')
  action = "#{SOAP_ACTION_PREFIX}/CreateItem"
  resp = invoke("#{NS_EWS_MESSAGES}:CreateItem", action) do |node|
    build!(node) do
      create_item!(folder_id, items, message_disposition, false, 'task')
    end
  end
  parse!(resp)
end

#delete_attachment ⇒ Object 



634
635
636
637
638
639
640
 
# File 'lib/soap/handsoap/ews_service.rb', line 634

def delete_attachment
  action = "#{SOAP_ACTION_PREFIX}/DeleteAttachment"
  resp = invoke("#{NS_EWS_MESSAGES}:DeleteAttachment", action) do |delete_attachment|
    build_delete_attachment!(delete_attachment)
  end
  parse_delete_attachment(resp)
end

#delete_folder(folder_id, delete_type = 'MoveToDeletedItems') ⇒ Object

Deletes folders from a mailbox.

Parameters:

See Also:



268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/soap/handsoap/ews_service.rb', line 268

def delete_folder(folder_id, delete_type = 'MoveToDeletedItems')
  action = "#{SOAP_ACTION_PREFIX}/DeleteFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:DeleteFolder", action) do |root|
    build!(root) do
      root.set_attr('DeleteType', delete_type)
      folder_id = (folder_id.is_a?(Array)) ? folder_id : [folder_id]
      folder_ids!(root, folder_id)
    end
  end
  parse!(resp)
end

#delete_item(item_ids, delete_type, send_meeting_cancellations = nil, affected_task_occurrences = nil) ⇒ Object

Delete an item from a mailbox in the Exchange store

Parameters:

  • item_ids (Array) —

    An Array of item ids

  • delete_type (String) —

    Type of deletion: “HardDelete/SoftDelete/MoveToDeletedItems”

  • send_meeting_cancellations (String, nil) (defaults to: nil) —

    “SendToNone/SendOnlyToAll/SendToAllAndSaveCopy” This is only applicable to CalendarItems and should be nil otherwise, which is the default

  • affected_task_occurrences (String, nil) (defaults to: nil) —

    “AllOccurrences/SpecifiedOccurrenceOnly” This is really only related to tasks and can be nil otherwise, which is the default.

See Also:



530
531
532
533
534
535
536
537
538
539
540
541
 
# File 'lib/soap/handsoap/ews_service.rb', line 530

def delete_item(item_ids, delete_type, send_meeting_cancellations = nil, affected_task_occurrences = nil)
  action = "#{SOAP_ACTION_PREFIX}/DeleteItem"
  resp = invoke("#{NS_EWS_MESSAGES}:DeleteItem", action) do |root|
    build!(root) do
      root.set_attr('DeleteType', delete_type)
      root.set_attr('SendMeetingCancellations', send_meeting_cancellations) unless send_meeting_cancellations.nil?
      root.set_attr('AffectedTaskOccurrences', affected_task_occurrences) unless affected_task_occurrences.nil?
      item_ids!(root, item_ids)
    end
  end
  parse!(resp)
end

#expand_dl(dist_email) ⇒ Object

TODO:

Fully support all of the ExpandDL operations. Today it just supports taking an e-mail address as an argument

Exposes the full membership of distribution lists.

Parameters:

  • dist_email (String) —

    The e-mail address associated with the Distribution List

See Also:



129
130
131
132
133
134
135
136
137
 
# File 'lib/soap/handsoap/ews_service.rb', line 129

def expand_dl(dist_email)
  action = "#{SOAP_ACTION_PREFIX}/ExpandDL"
  resp = invoke("#{NS_EWS_MESSAGES}:ExpandDL", action) do |root|
    build!(root) do
      mailbox!(root, {:email_address => {:text => dist_email}})
    end
  end
  parse!(resp)
end

#find_folder(parent_folder_ids = [:root], traversal = 'Shallow', folder_shape = {:base_shape => 'Default'}, opts = {}) ⇒ Object

Find subfolders of an identified folder

Parameters:

  • parent_folder_ids (Array) (defaults to: [:root]) —

    An Array of folder ids, either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • traversal (String) (defaults to: 'Shallow') —

    Shallow/Deep/SoftDeleted

  • folder_shape (Hash) (defaults to: {:base_shape => 'Default'}) —

    defines the FolderShape node See: msdn.microsoft.com/en-us/library/aa494311.aspx

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

    optional parameters to this method

Options Hash (folder_shape):

See Also:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/soap/handsoap/ews_service.rb', line 151

def find_folder(parent_folder_ids = [:root], traversal = 'Shallow', folder_shape = {:base_shape => 'Default'}, opts = {})
  action = "#{SOAP_ACTION_PREFIX}/FindFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:FindFolder", action) do |root|
    build!(root) do
      restriction = opts.delete(:restriction)
      root.set_attr('Traversal', traversal)
      folder_shape!(root, folder_shape)
      root.add("#{NS_EWS_MESSAGES}:Restriction") do |r|
        add_hierarchy!(r, restriction)
      end unless restriction.nil?
      parent_folder_ids!(root, parent_folder_ids)
    end
  end
  parse!(resp)
end

#find_item(parent_folder_ids, traversal = 'Shallow', item_shape = {:base_shape => 'Default'}, opts = {}) ⇒ Object

Identifies items that are located in a specified folder

Parameters:

  • parent_folder_ids (Array) —

    An Array of folder ids, either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • traversal (String) (defaults to: 'Shallow') —

    Shallow/Deep/SoftDeleted

  • item_shape (Hash) (defaults to: {:base_shape => 'Default'}) —

    defines the FolderShape node See: msdn.microsoft.com/en-us/library/aa494311.aspx

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

    optional parameters to this method

Options Hash (item_shape):

Options Hash (opts):

  • :calendar_view (Hash) —

    Limit FindItem by a start and end date => {:max_entries_returned => 2, :start => <DateTime Obj>, :end => <DateTime Obj>}

See Also:



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/soap/handsoap/ews_service.rb', line 181

def find_item(parent_folder_ids, traversal = 'Shallow', item_shape = {:base_shape => 'Default'}, opts = {})
  action = "#{SOAP_ACTION_PREFIX}/FindItem"
  resp = invoke("#{NS_EWS_MESSAGES}:FindItem", action) do |root|
    build!(root) do
      root.set_attr('Traversal', traversal)
      item_shape!(root, item_shape)
      query_strings = opts.delete(:query_string)
      restriction = opts.delete(:restriction)
      if(opts.has_key?(:calendar_view))
        cal_view = opts[:calendar_view]
        cal_view.each_pair do |k,v|
          cal_view[k] = v.to_s
        end
      end
      add_hierarchy!(root, opts, NS_EWS_MESSAGES)
      #query_strings!(query_strings)
      root.add("#{NS_EWS_MESSAGES}:Restriction") do |r|
        add_hierarchy!(r, restriction)
      end unless restriction.nil?
      parent_folder_ids!(root, parent_folder_ids)
    end
  end
  parse!(resp)
end

#get_attachment(attachment_ids) ⇒ Object

Used to retrieve existing attachments on items in the Exchange store

Parameters:

  • attachment_ids (Array) —

    Attachment Ids to fetch

See Also:



645
646
647
648
649
650
651
652
653
654
 
# File 'lib/soap/handsoap/ews_service.rb', line 645

def get_attachment(attachment_ids)
  action = "#{SOAP_ACTION_PREFIX}/GetAttachment"
  resp = invoke("#{NS_EWS_MESSAGES}:GetAttachment", action) do |root|
    build!(root) do
      attachment_shape!(root)
      attachment_ids!(root, attachment_ids)
    end
  end
  parse!(resp)
end

#get_delegate(owner) ⇒ Object

Retrieves the delegate settings for a specific mailbox.

Parameters:

  • owner (String) —

    The user that is delegating permissions

See Also:



668
669
670
671
672
673
674
675
676
677
 
# File 'lib/soap/handsoap/ews_service.rb', line 668

def get_delegate(owner)
  action = "#{SOAP_ACTION_PREFIX}/GetDelegate"
  resp = invoke("#{NS_EWS_MESSAGES}:GetDelegate", action) do |root|
    root.set_attr('IncludePermissions', 'true')
    build!(root) do
      mailbox!(root, {:email_address => {:text => owner}})
    end
  end
  parse!(resp)
end

#get_events(subscription_id, watermark) ⇒ Object

Used by pull subscription clients to request notifications from the Client Access server

Parameters:

  • subscription_id (String) —

    Subscription identifier

  • watermark (String) —

    Event bookmark in the events queue

See Also:



358
359
360
361
362
363
364
365
366
367
 
# File 'lib/soap/handsoap/ews_service.rb', line 358

def get_events(subscription_id, watermark)
  action = "#{SOAP_ACTION_PREFIX}/GetEvents"
  resp = invoke("#{NS_EWS_MESSAGES}:GetEvents", action) do |root|
    build!(root) do
      subscription_id!(root, subscription_id)
      watermark!(root, watermark)
    end
  end
  parse!(resp)
end

#get_folder(folder_ids, folder_shape = {:base_shape => 'Default'}, act_as = nil) ⇒ Object

Gets folders from the Exchange store

Parameters:

  • folder_ids (Array) —

    An Array of folder ids, either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • folder_shape (Hash) (defaults to: {:base_shape => 'Default'}) —

    defines the FolderShape node See: msdn.microsoft.com/en-us/library/aa494311.aspx

  • act_as (String, nil) (defaults to: nil) —

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

  • opts (Hash) —

    optional parameters to this method

Options Hash (folder_shape):

See Also:



219
220
221
222
223
224
225
226
227
228
 
# File 'lib/soap/handsoap/ews_service.rb', line 219

def get_folder(folder_ids, folder_shape = {:base_shape => 'Default'}, act_as = nil)
  action = "#{SOAP_ACTION_PREFIX}/GetFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:GetFolder", action) do |root|
    build!(root) do
      folder_shape!(root, folder_shape)
      folder_ids!(root, folder_ids, act_as)
    end
  end
  parse!(resp)
end

#get_item(item_ids, item_shape = {}) ⇒ Object

Gets items from the Exchange store

Parameters:

Options Hash (item_shape):

See Also:



427
428
429
430
431
432
433
434
435
436
437
 
# File 'lib/soap/handsoap/ews_service.rb', line 427

def get_item(item_ids, item_shape = {})
  action = "#{SOAP_ACTION_PREFIX}/GetItem"
  item_shape[:base_shape] = 'Default' unless item_shape.has_key?(:base_shape)
  resp = invoke("#{NS_EWS_MESSAGES}:GetItem", action) do |root|
    build!(root) do
      item_shape!(root, item_shape)
      item_ids!(root, item_ids)
    end
  end
  parse!(resp)
end

#get_user_availability ⇒ Object

Provides detailed information about the availability of a set of users, rooms, and resources within a specified time window.

See Also:



731
732
733
734
735
736
737
 
# File 'lib/soap/handsoap/ews_service.rb', line 731

def get_user_availability
  action = "#{SOAP_ACTION_PREFIX}/GetUserAvailability"
  resp = invoke("#{NS_EWS_MESSAGES}:GetUserAvailability", action) do |get_user_availability|
    build_get_user_availability!(get_user_availability)
  end
  parse_get_user_availability(resp)
end

#get_user_oof_settings(mailbox) ⇒ Object

Gets a mailbox user’s Out of Office (OOF) settings and messages.

See Also:



741
742
743
744
745
746
747
748
749
 
# File 'lib/soap/handsoap/ews_service.rb', line 741

def get_user_oof_settings(mailbox)
  action = "#{SOAP_ACTION_PREFIX}/GetUserOofSettings"
  resp = invoke("#{NS_EWS_MESSAGES}:GetUserOofSettingsRequest", action) do |root|
    build!(root) do
      mailbox!(root,mailbox[:mailbox],NS_EWS_TYPES)
    end
  end
  parse!(resp)
end

#move_folder ⇒ Object 



288
289
290
291
292
293
294
 
# File 'lib/soap/handsoap/ews_service.rb', line 288

def move_folder
  action = "#{SOAP_ACTION_PREFIX}/MoveFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:MoveFolder", action) do |move_folder|
    build_move_folder!(move_folder)
  end
  parse_move_folder(resp)
end

#move_item(item_ids, folder_id) ⇒ Object

Used to move one or more items to a single destination folder.

Parameters:

  • item_ids (Array) —

    An Array of item ids

  • folder_id (String, Symbol) —

    either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

See Also:



586
587
588
589
590
591
592
593
594
595
 
# File 'lib/soap/handsoap/ews_service.rb', line 586

def move_item(item_ids, folder_id)
  action = "#{SOAP_ACTION_PREFIX}/MoveItem"
  resp = invoke("#{NS_EWS_MESSAGES}:MoveItem", action) do |root|
    build!(root) do
      to_folder_id!(root, folder_id)
      item_ids!(root, item_ids)
    end
  end
  parse!(resp)
end

#on_after_create_http_request(req) ⇒ Object 



84
85
86
87
88
89
90
 
# File 'lib/soap/handsoap/ews_service.rb', line 84

def on_after_create_http_request(req)
  begin
    req.set_auth @@user, @@pass
  rescue NameError => e
    raise EwsLoginError, "Please remember to set your credential information."
  end
end

#on_create_document(doc) ⇒ Object 



65
66
67
68
69
70
 
# File 'lib/soap/handsoap/ews_service.rb', line 65

def on_create_document(doc)
  doc.alias NS_EWS_TYPES, 'http://schemas.microsoft.com/exchange/services/2006/types'
  doc.alias NS_EWS_MESSAGES, 'http://schemas.microsoft.com/exchange/services/2006/messages'
  header = doc.find('Header')
  header.add("#{NS_EWS_TYPES}:RequestServerVersion") { |rsv| rsv.set_attr('Version','Exchange2007_SP1') }
end

#on_http_error(response) ⇒ Object

Raises:



92
93
94
 
# File 'lib/soap/handsoap/ews_service.rb', line 92

def on_http_error(response)
  raise EwsLoginError, "Failed to login to EWS at #{uri}. Please check your credentials." if(response.status == 401)
end

#on_response_document(doc) ⇒ Object

Adds knowledge of namespaces to the response object. These have to be identical to the URIs returned in the XML response. For example, I had some issues with the ‘soap’ namespace because my original URI did not end in a ‘/’

Examples:

Won't work: http://schemas.xmlsoap.org/soap/envelope
Works: http://schemas.xmlsoap.org/soap/envelope/


78
79
80
81
82
 
# File 'lib/soap/handsoap/ews_service.rb', line 78

def on_response_document(doc)
  doc.add_namespace NS_SOAP, 'http://schemas.xmlsoap.org/soap/envelope/'
  doc.add_namespace NS_EWS_TYPES, 'http://schemas.microsoft.com/exchange/services/2006/types'
  doc.add_namespace NS_EWS_MESSAGES, 'http://schemas.microsoft.com/exchange/services/2006/messages'
end

#push_subscribe(folder_ids, event_types, url, watermark = nil, status_frequency = 5) ⇒ Object

Used to subscribe client applications to either push or pull notifications.

See Also:



328
329
330
331
332
333
334
335
336
337
 
# File 'lib/soap/handsoap/ews_service.rb', line 328

def push_subscribe(folder_ids, event_types, url, watermark=nil, status_frequency=5)
  action = "#{SOAP_ACTION_PREFIX}/Subscribe"
  resp = invoke("#{NS_EWS_MESSAGES}:Subscribe", action) do |root|
    build!(root) do
      push_subscription_request!(folder_ids, event_types, url, watermark, status_frequency)
    end
  end
  parse!(resp)

end

#remove_delegate(owner, delegate) ⇒ Object

Removes one or more delegates from a user’s mailbox.

Parameters:

  • owner (String) —

    The user that is delegating permissions

  • delegate (String) —

    The user that is being given delegate permission

See Also:



701
702
703
704
705
706
707
708
709
 
# File 'lib/soap/handsoap/ews_service.rb', line 701

def remove_delegate(owner, delegate)
  action = "#{SOAP_ACTION_PREFIX}/RemoveDelegate"
  resp = invoke("#{NS_EWS_MESSAGES}:RemoveDelegate", action) do |root|
    build!(root) do
      remove_delegate!(owner, delegate)
    end
  end
  parse!(resp)
end

#resolve_names(name, full_contact_data = true, opts = {}) ⇒ Object

Resolve ambiguous e-mail addresses and display names

Parameters:

  • name (String) —

    an unresolved entry

  • full_contact_data (Boolean) (defaults to: true) —

    whether or not to return full contact info

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

    optional parameters to this method

Options Hash (opts):

  • :search_scope (String) —

    where to seach for this entry, one of SOAP::Contacts, SOAP::ActiveDirectory, SOAP::ActiveDirectoryContacts (default), SOAP::ContactsActiveDirectory

  • :parent_folder_id (String, FolderId) —

    either the name of a folder or it’s numerical ID. @see msdn.microsoft.com/en-us/library/aa565998.aspx

See Also:



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/soap/handsoap/ews_service.rb', line 111

def resolve_names(name, full_contact_data = true, opts = {})
  action = "#{SOAP_ACTION_PREFIX}/ResolveNames"
  resp = invoke("#{NS_EWS_MESSAGES}:ResolveNames", action) do |root|
    build!(root) do
      root.set_attr('ReturnFullContactData',full_contact_data)
      root.add("#{NS_EWS_MESSAGES}:UnresolvedEntry",name)
    end
  end
  parse!(resp)
end

#send_item(item_ids, save_item = true, saved_item_folder = nil) ⇒ Object

Used to send e-mail messages that are located in the Exchange store.

Parameters:

  • item_ids (Array<Hash>) —

    An Array of item ids. These item_ids should be a Hash of :id and :change_key.

  • save_item (Boolean) (defaults to: true) —

    Save item after sending (Think sent-items)

  • saved_item_folder (String, Symbol, nil) (defaults to: nil) —

    The folder to save this item in. Either a DistinguishedFolderId (must me a Symbol) or a FolderId (String). Just leave it blank for the default :sentitems

See Also:



569
570
571
572
573
574
575
576
577
578
579
 
# File 'lib/soap/handsoap/ews_service.rb', line 569

def send_item(item_ids, save_item=true, saved_item_folder=nil)
  action = "#{SOAP_ACTION_PREFIX}/SendItem"
  resp = invoke("#{NS_EWS_MESSAGES}:SendItem", action) do |root|
    build!(root) do
      root.set_attr('SaveItemToFolder', save_item)
      item_ids!(root,item_ids)
      saved_item_folder_id!(root,saved_item_folder) unless saved_item_folder.nil?
    end
  end
  parse!(resp)
end

#set_user_oof_settings(mailbox, oof_state, ext_audience, dt_start, dt_end, int_msg, ext_mg) ⇒ Object

Sets a mailbox user’s Out of Office (OOF) settings and message.

See Also:



753
754
755
756
757
758
759
 
# File 'lib/soap/handsoap/ews_service.rb', line 753

def set_user_oof_settings(mailbox, oof_state, ext_audience, dt_start, dt_end, int_msg, ext_mg)
  action = "#{SOAP_ACTION_PREFIX}/SetUserOofSettings"
  resp = invoke("#{NS_EWS_MESSAGES}:SetUserOofSettings", action) do |root|
    build!(root)
  end
  parse!(resp)
end

#subscribe(folder_ids, event_types, timeout = 10) ⇒ Object

TODO:

Decide how/if to handle the optional SubscribeToAllFolders attribute of the PullSubscriptionRequest element.

Used to subscribe client applications to either push or pull notifications.

Parameters:

  • folder_ids (Array) —

    An Array of folder ids, either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • event_types (Array) —

    An Array of EventTypes that we should track. Available types are, CopiedEvent, CreatedEvent, DeletedEvent, ModifiedEvent, MovedEvent, NewMailEvent, FreeBusyChangedEvent

  • timeout (Integer) (defaults to: 10) —

    The number of minutes in which the subscription will timeout after not receiving a get_events operation.

See Also:



316
317
318
319
320
321
322
323
324
 
# File 'lib/soap/handsoap/ews_service.rb', line 316

def subscribe(folder_ids, event_types, timeout = 10)
  action = "#{SOAP_ACTION_PREFIX}/Subscribe"
  resp = invoke("#{NS_EWS_MESSAGES}:Subscribe", action) do |root|
    build!(root) do
      pull_subscription_request!(folder_ids, event_types, timeout)
    end
  end
  parse!(resp)
end

#sync_folder_hierarchy ⇒ Object

Defines a request to synchronize a folder hierarchy on a client

See Also:



371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/soap/handsoap/ews_service.rb', line 371

def sync_folder_hierarchy
  sync_state = nil
  folder_id = :publicfoldersroot
  action = "#{SOAP_ACTION_PREFIX}/SyncFolderHierarchy"
  resp = invoke("#{NS_EWS_MESSAGES}:SyncFolderHierarchy", action) do |root|
    build!(root) do
      folder_shape!(root, {:base_shape => 'Default'})
      root.add("#{NS_EWS_MESSAGES}:SyncFolderId") do |sfid|
        folder_id!(sfid, folder_id)
      end
      sync_state!(root, sync_state) unless sync_state.nil?
    end
  end
  parse!(resp)
end

#sync_folder_items(folder_id, sync_state = nil, max_changes = 256, item_shape = {:base_shape => 'Default'}, opts = {}) ⇒ Object

Synchronizes items between the Exchange server and the client

Parameters:

  • folder_id (String, Symbol) —

    either a DistinguishedFolderId (must me a Symbol) or a FolderId (String)

  • sync_state (String) (defaults to: nil) —

    Base-64 encoded string used to determine where we are in the sync process.

  • max_changes (Integer) (defaults to: 256) —

    The amount of items to sync per call to SyncFolderItems

  • item_shape (Hash) (defaults to: {:base_shape => 'Default'}) —

    defines the ItemShape node See: msdn.microsoft.com/en-us/library/aa565261.aspx

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

    optional parameters to this method

Options Hash (item_shape):

See Also:



402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/soap/handsoap/ews_service.rb', line 402

def sync_folder_items(folder_id, sync_state = nil, max_changes = 256, item_shape = {:base_shape => 'Default'}, opts = {})
  action = "#{SOAP_ACTION_PREFIX}/SyncFolderItems"
  resp = invoke("#{NS_EWS_MESSAGES}:SyncFolderItems", action) do |root|
    build!(root) do
      item_shape!(root, item_shape)
      root.add("#{NS_EWS_MESSAGES}:SyncFolderId") do |sfid|
        folder_id!(sfid, folder_id)
      end
      sync_state!(root, sync_state) unless sync_state.nil?
      root.add("#{NS_EWS_MESSAGES}:MaxChangesReturned", max_changes)
    end
  end
  parse!(resp)
end

#unsubscribe(subscription_id) ⇒ Object

End a pull notification subscription.

Parameters:

  • subscription_id (String) —

    The Id of the subscription

See Also:



343
344
345
346
347
348
349
350
351
 
# File 'lib/soap/handsoap/ews_service.rb', line 343

def unsubscribe(subscription_id)
  action = "#{SOAP_ACTION_PREFIX}/Unsubscribe"
  resp = invoke("#{NS_EWS_MESSAGES}:Unsubscribe", action) do |root|
    build!(root) do
      subscription_id!(root, subscription_id)
    end
  end
  parse!(resp)
end

#update_delegate(owner, delegate, permissions) ⇒ Object

Updates delegate permissions on a principal’s mailbox

Parameters:

  • owner (String) —

    The user that is delegating permissions

  • delegate (String) —

    The user that is being given delegate permission

  • permissions (Hash) —

    A hash of permissions that will be delegated. This Hash will eventually be passed to add_hierarchy! in the builder so it is in that format.

See Also:



718
719
720
721
722
723
724
725
726
 
# File 'lib/soap/handsoap/ews_service.rb', line 718

def update_delegate(owner, delegate, permissions)
  action = "#{SOAP_ACTION_PREFIX}/UpdateDelegate"
  resp = invoke("#{NS_EWS_MESSAGES}:UpdateDelegate", action) do |root|
    build!(root) do
      add_delegate!(owner, delegate, permissions)
    end
  end
  parse!(resp)
end

#update_folder ⇒ Object 



280
281
282
283
284
285
286
 
# File 'lib/soap/handsoap/ews_service.rb', line 280

def update_folder
  action = "#{SOAP_ACTION_PREFIX}/UpdateFolder"
  resp = invoke("#{NS_EWS_MESSAGES}:UpdateFolder", action) do |update_folder|
    build_update_folder!(update_folder)
  end
  parse_update_folder(resp)
end

#update_item(item_ids, changes, opts = {:message_disposition => 'SaveOnly', :conflict_resolution => 'AutoResolve'}) ⇒ Object

Used to modify the properties of an existing item in the Exchange store

Parameters:

  • item_ids (Array) —

    An Array of item ids

  • changes (Hash) —

    a Hash of changes to be fed to auto_hierarchy!

  • opts (Hash) (defaults to: {:message_disposition => 'SaveOnly', :conflict_resolution => 'AutoResolve'}) —

    various attributes to set for this update. See the Technet docs for more info

See Also:



548
549
550
551
552
553
554
555
556
557
558
559
 
# File 'lib/soap/handsoap/ews_service.rb', line 548

def update_item(item_ids, changes, opts = {:message_disposition => 'SaveOnly', :conflict_resolution => 'AutoResolve'})
  action = "#{SOAP_ACTION_PREFIX}/UpdateItem"
  resp = invoke("#{NS_EWS_MESSAGES}:UpdateItem", action) do |root|
    build!(root) do
      root.set_attr('MessageDisposition', opts[:message_disposition]) if opts.has_key?(:message_disposition)
      root.set_attr('ConflictResolution', opts[:conflict_resolution]) if opts.has_key?(:message_disposition)
      root.set_attr('SendMeetingInvitationsOrCancellations', opts[:send_meeting_invitations_or_cancellations]) if opts.has_key?(:send_meeting_invitations_or_cancellations)
      item_changes!(root, item_ids, changes)
    end
  end
  parse!(resp)
end