| This chapter examines some of the major objects in the Outlook object model, starting with the Application object. Many of the objects in the Outlook object model are very large, and it is beyond the scope of this book to describe these objects completely. Instead, this chapter focuses on the most commonly used methods and properties associated with these objects. The Application object is the root object in the Outlook object model hierarchy, meaning that you can access all the other objects in the object model by starting at the Application object and accessing its properties and methods and the properties and methods of objects it returns. A companion object to the Application object is the NameSpace object, which is retrieved by using the Application object's Session property. Some confusion can arise because functionality that you would expect to be on the Application object is often found on the NameSpace object. The way to get to the root folders that are open in Outlook, for example, is through the NameSpace object's Folders property. The Application object has no Folders property. Methods and Properties That Return Active or Selected Objects The Application object has a number of methods and properties that return active objectsobjects representing things that are active or selected within Outlook. Table 11.1 shows some of these properties and methods. Table 11.1. Application Properties and Methods That Return Active ObjectsName | Type | What It Does |
|---|
ActiveExplorer() | Explorer | Returns the active Explorer objectthe Explorer window that has focus within Outlook. If an inspector window is active, this returns the Explorer window that is frontmost in the stack of Outlook windows. If no Explorer windows are open, this method returns Nothing. | ActiveInspector() | Inspector | Returns the active Inspector objectthe inspector window that has focus within Outlook. If an Explorer window is active, this returns the inspector window that is frontmost in the stack of Outlook windows. If no inspector windows are open, this method returns Nothing. | ActiveWindow() | Object | Returns the active window as an Object. If no windows are open, this method returns Nothing. The returned Object can be cast to either an Explorer or an Inspector object. | Session | Session | A property that returns the NameSpace object. | GetNameSpace() | Session | A method that returns the NameSpace object. Takes the type of NameSpace to return as a string. The only string you can pass to GetNameSpace, however, is the string "MAPI". This is an older way to get the NameSpace object. The newer way to access the NameSpace object that is used in this book is through the Session property. |
Properties That Return Important Collections The Application object has a number of properties that return collections that you will frequently use. Table 11.2 shows several of these properties. Listing 11.1 shows some code from a VSTO Outlook add-in that works with the active object methods and properties shown in Table 11.1 and the collections shown in Table 11.2. Table 11.2. Application Properties That Return Important CollectionsProperty Name | Type | What It Does |
|---|
Explorers | Explorers | Returns the Explorers collection, which enables you to access any open Explorer windows | Inspectors | Inspectors | Returns the Inspectors collection, which enables you to access any open inspector windows | Reminders | Reminders | Returns the Reminders collection, which enables you to access all the current reminders |
Listing 11.1. A VSTO Add-In That Works with Active Objects and Collections| Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim activeExplorer As Outlook.Explorer = Me.ActiveExplorer() If activeExplorer IsNot Nothing Then MsgBox(String.Format("The active explorer is {0}.", _ activeExplorer.Caption)) End If Dim activeInspector As Outlook.Inspector activeInspector = Me.ActiveInspector() If activeInspector IsNot Nothing Then MsgBox(String.Format("The Active Inspector is {0}.", _ activeInspector.Caption)) End If Dim activeWindow As Object = Me.ActiveWindow() If TypeOf activeWindow Is Outlook.Explorer Then Dim explorer1 As Outlook.Explorer = activeWindow MsgBox(String.Format( _ "The active window is an Explorer: {0}.", _ explorer1.Caption)) ElseIf TypeOf activeWindow Is Outlook.Inspector Then Dim inspector1 As Outlook.Inspector = activeWindow MsgBox(String.Format( _ "The active window is an Inspector: {0}.", _ inspector1.Caption)) Else MsgBox("No Outlook windows are open") End If Dim ns As Outlook.NameSpace = Me.Session MsgBox(String.Format("There are {0} root folders.", _ ns.Folders.Count)) MsgBox(String.Format("There are {0} explorer windows.", _ Me.Explorers.Count)) For Each explorer As Outlook.Explorer In Me.Explorers MsgBox(explorer.Caption) Next MsgBox(String.Format("There are {0} inspector windows.", _ Me.Inspectors.Count)) For Each inspector As Outlook.Inspector In Me.Inspectors MsgBox(inspector.Caption) Next MsgBox(String.Format("There are {0} reminders.", _ Me.Reminders.Count)) Dim reminders As New System.Text.StringBuilder() For Each reminder As Outlook.Reminder In Me.Reminders reminders.AppendLine(reminder.Caption) Next MsgBox(reminders.ToString()) End Sub End Class |
Performing a Search and Creating a Search Folder Outlook provides an AdvancedSearch method on the Application object that allows you to perform a search in Outlook. The AdvancedSearch method works asynchronously and raises the AdvancedSearchComplete event when the search has completed. You can also save a search you perform using the AdvancedSearch method as an Outlook Search folder. AdvancedSearch takes four parameters, as shown in Table 11.3. Table 11.3. Parameters for the AdvancedSearch MethodParameter Name | Type | Description |
|---|
Scope | String | Pass the name of the folder or folders that you want to search. To search the Inbox, for example, pass the string "'Inbox'". To search the Inbox and Calendar, pass "'Inbox', 'Calendar'". | | | | You can pass the full name of a folder, including the path to the folder, to search a folder within a folder. The scope string "'Reference\Reviews'"searches a folder called Reviews nested in a folder called Reference in the default Outlook Store. | | | | You can search a folder in another PST Outlook data file that is open inside Outlook. The Scope string "'\\Archive\Backup'" searches a folder called Backup in a PST file called Archive that is open in Outlook. | Filter | optional Object | Pass the filter string that specifies what you want to search for. You will learn how to construct this string below. | SearchSubFolders | optional Object | Pass TRue to also search any subfolders under the folders specified in Scope. | Tag | optional Object | Pass a String to name the search uniquely so that when you handle the Application.AdvancedSearchComplete event, you can distinguish between a search created by you and other searches created by other loaded add-ins. This is critical; you cannot assume that you are the only add-in that is handling this event. You must carefully tag your searches with a unique string to ensure that your add-in does not act on an advanced search started by another add-in. |
Now we consider how to construct the filter string that is mentioned in Table 11.3. The easiest way to do this is to let Outlook's built-in user interface for constructing filters build the string for you. To do this, first select the folder you want to search. From the Arrange By menu in the View menu, choose Custom to display the Customize View dialog box (see Figure 11.1). Figure 11.1. The Customize View dialog box.
Click the Filter button to display the Filter dialog box. You can use this dialog box to create the filter you want. In Figure 11.2, we have simply set the filter to show messages in which the word review is in the Subject field. Figure 11.2. The Filter dialog box. After you have edited the filter to yield the results you want, click the SQL tab, shown in Figure 11.3. Check the Edit These Criteria Directly check box. Doing so enables you to select the filter string and copy and paste it into your code. After you have copied the filter string to the clipboard, you can cancel out of the Filter dialog box and the Customize View dialog box. Figure 11.3. The SQL tab of the Filter dialog box displays a filter string.
Finally, paste the filter string into your code. You will want to expand all quotation marks to be double quotation marks. For our example, the Visual Basic 2005 code would look like this: Dim filter As String filter = """urn:schemas:httpmail:subject"" LIKE '%review%'" Listing 11.2 shows a complete example of using AdvancedSearch. Note that because the search proceeds asynchronously, we must handle the AdvancedSearchComplete event to determine when the search is finished. We also save the completed search as a search folder by calling Save on the completed Search object. Listing 11.2. A VSTO Add-In That Uses the AdvancedSearch Method| Public Class ThisApplication Const searchTag As String = "'review' Search In Inbox" Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim scope As String = "'Inbox'" Dim filter As String filter = """urn:schemas:httpmail:subject"" LIKE '%review%'" Dim searchSubfolders As Boolean = True Try MsgBox("Starting search") Me.AdvancedSearch(scope, filter, searchSubfolders, _ searchTag) Catch ex As Exception MsgBox(ex.Message) End Try End Sub Public Sub ThisApplication_AdvancedSearchStopped( _ ByVal searchObject As Outlook.Search) _ Handles Me.AdvancedSearchStopped If searchObject.Tag = searchTag Then MsgBox(String.Format("Search completed. " & _ Found {0} results.", _ searchObject.Results.Count)) ' Save this search as a search folder searchObject.Save(searchTag) End If End Sub Public Sub ThisApplication_AdvancedSearchComplete( _ ByVal searchObject As Outlook.Search) _ Handles Me.AdvancedSearchComplete If searchObject.Tag = searchTag Then MsgBox(String.Format("Search was stopped. " & _ Found {0} results.", _ searchObject.Results.Count)) End If End Sub End Class |
Copying a File into an Outlook Folder Outlook provides a method to copy an existing document, such as a spreadsheet on your desktop, to an Outlook folder. The Application object's CopyFile method takes as a parameter a FilePath as a String, which is the full path to the document you want to copy into the Outlook folder. It also takes a DestFolderPath parameter, which is the name of the Outlook folder you want to copy the document to. Listing 11.3 shows an example of using CopyFile to put a spreadsheet called mydoc.xls in the Inbox and a second spreadsheet called mydoc2.xls in a folder called Reviews nested within a folder called Reference. Listing 11.3. A VSTO Add-In That Uses the CopyFile Method| Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Me.CopyFile("c:\mydoc.xls", "Inbox") Me.CopyFile("c:\mydoc2.xls", "Reference\Reviews") End Sub End Class |
Quitting Outlook The Quit method can be used to exit Outlook. If any unsaved Outlook items are opened, Outlook prompts the user to save each unsaved Outlook item. When users are prompted to save, they get a dialog box that gives them a Cancel button. If the user clicks Cancel, Outlook does not quit. |