Working with the Application Object


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 Objects

Name

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 Collections

Property 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 Method

Parameter 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.




Visual Studio Tools for Office(c) Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath
Visual Studio Tools for Office: Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath
ISBN: 0321411757
EAN: 2147483647
Year: N/A
Pages: 221

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net