Properties and Methods Common to Outlook Items
| This chapter has discussed the 16 Outlook item types: AppointmentItem, ContactItem, DistListItem, DocumentItem, JournalItem, MailItem, MeetingItem, NoteItem, PostItem, RemoteItem, ReportItem, TaskItem, TaskRequestAcceptItem, TaskRequestDeclineItem, TaskRequestItem, and TaskRequestUpdateItem. We group these object model types because all these types have many common properties and methods, listed in Table 11.8. The properties and methods in this table are found on all Outlook item types. The properties and methods marked in this table with an asterisk are found on all Outlook item types except NoteItem. NoteItem is a special case in the Outlook item family and has a subset of the properties and methods that the other Outlook item types share.
Now we consider several of these common properties and methods. Even though we talk about Outlook Items as though there were an OutlookItem type in the Outlook object model, there is no such type; the OutlookItem type is a conceptual way of talking about the properties and methods common to the 16 Outlook item types in the Outlook object model. So when we talk about the Save method, for example, that method is found on ContactItem, PostItem, MailItem, and all the other Outlook item types. Given an object that you know is 1 of the 16 Outlook item types, you can cast it to the correct Outlook item type, or you can talk to the object via late-bound properties if you are talking to a property common to all Outlook items. Some of the code listings in this section use late-bound properties and have illustrated this point. Usually, it is preferable to cast the object to the specific item type rather than use late binding. Creating an Outlook ItemYou learned the two primary ways in which you can create an Outlook item earlier in this chapter, in the section "Adding an Outlook Item to an Items Collection." You can call either the Items collection's Add method or the Application object's CreateItem method. These methods take a member of the OlItemType enumeration and return an object that can be cast to the Outlook item type corresponding to the OlItemType enumeration, as shown in Table 11.9.
Notice that there are eight items in this table, which leaves out seven Outlook item types. How do you create the other seven remaining Outlook item types? The remaining types are created by Outlook or created as a result of other actions you take with an existing Outlook item type. Table 11.10 identifies how the other Outlook item types are created.
Identifying the Specific Type of an Outlook ItemYou can determine the specific type of an Outlook item given to you as type Object by using the TypeOf operator to determine whether the Outlook item is a particular type, as shown in Listing 11.21. The code gets an Outlook item out of the Inbox and then uses the TypeOf operator to determine whether it is an Outlook MailItem. If the Outlook item is a MailItem, the code proceeds to call the late-bound subject property to display the subject of the mail message. Listing 11.21. A VSTO Add-In That Uses the TypeOf Operator on an Outlook Item of Type Object
You can also use declare a variable to a specific Outlook item type and set the variable to the Object representing the Outlook item. This will give you a variable that can be talked to in a strongly typed way. This technique is shown in Listing 11.22. A second technique is to use the CType operator to cast the Object to a particular Outlook item type. This approach is also shown in Listing 11.22. Listing 11.22. A VSTO Add-In That Uses the Is Operator on an Outlook Item of Type Object
A final way to determine the type of an Outlook item of type Object is to call the late-bound Class property, which is found on every Outlook item type. The Class property returns a member of the OlObjectClass enumeration. Table 11.11 shows the correspondence between OlObjectClass enumerated values and Outlook item types.
Listing 11.23 shows some add-in code that calls the Class property on an Outlook item of type Object. Then it uses a Select Case statement, which for illustration purposes contains all the members of the OlObjectClass enumeration that correspond to Outlook item types. The code in Listing 11.23 would be more efficient than using the IsType operator if your code needs to cast to multiple specific Outlook item types, given an Outlook item of type Object. The code in Listing 11.15, for example, would be more efficient if it were rewritten to use the approach in Listing 11.23. The approach in Listing 11.23 needs to make only one late-bound property call to get the Class value and then one cast to get the specific Outlook item type. Listing 11.23. A VSTO Add-In That Uses the Class Property to Determine the Outlook Item Type
Other Properties Associated with All Outlook ItemsThis section covers several commonly used properties associated with all Outlook item types (with the possible exception of NoteItem). When we say properties in the context of Outlook items, some confusion can arise. Some properties are on the actual Outlook item type. The Subject property, for example, is a callable property on all Outlook item object types. There are a MailItem.Subject property, PostItem.Subject, ContactItem.Subject, and so on. Sometimes, a property that is on an Outlook item object type is also accessible via the OutlookItem.ItemProperties collection. If you iterate over the ItemProperties collection, you will find an ItemProperty object where ItemProperty.Name returns "Subject". The creators of the Outlook object model exposed some of the properties in the ItemProperties collection as first-class properties on the object types themselves. So the Subject property can be accessed by using either OutlookItem.Subject or OutlookItem.ItemProperties("Subject"). Other properties that are more obscure were not exposed out as properties on the objects themselves. The EnableSharedAttachments property, for example, can be accessed only via OutlookItem.ItemProperties("EnableSharedAttachments"). You learn more about the ItemProperties collection later in this chapter. Table 11.12 lists several properties callable on all Outlook item object types. Properties marked with an asterisk are not available on the NoteItem object.
Copying or Moving an Outlook Item to a New LocationAn Outlook item can be copied or moved from one folder to another. The Outlook item's Copy method creates a copy of the Outlook item and returns the newly created item as an Object. The Outlook item's Move method moves an Outlook item from one folder to another. It takes a DestFldr parameter of type MAPIFolder to which you pass the folder to which you want to move the Outlook item. Deleting an Outlook ItemTo delete an Outlook item, call the Outlook item's Delete method. Doing so causes the Outlook item to be moved to the Deleted Items folder, where it stays until the user empties the Deleted Items folder. If you do not want the item to appear in the Deleted Items folder, you must call Delete twice. The first call moves the item to the Deleted Items folder, and the second call deletes it from the Deleted Items folder, as shown in Listing 11.24. Listing 11.24. A VSTO Add-In That Deletes an Item and Then Deletes It Permanently by Removing It from the Deleted Items Folder
Note in Listing 11.24 that we cannot find the item we just deleted in the Deleted Items folder using the EntryID because the EntryID changes when you delete the Outlook item. Instead, we use the Subject, which is not ideal because the Subject is not guaranteed to be unique. A better approach to deleting an item permanently and preventing it from showing up in the Deleted Items folder is using the Collaboration Data Objects (CDO) object model that was briefly described in Chapter 9, "Programming Outlook." Listing 11.25 shows this approach. We assume the VSTO Outlook add-in has a reference to the CDO object model interop assembly that adds the MAPI name space to the project. We use the GetMessageFromOutlookItem method, introduced in Listing 9.4 in Chapter 9. Listing 11.25. A VSTO Add-In That Uses CDO to Delete an Outlook Item Permanently
Displaying an Outlook Item in an Inspector WindowThe Outlook item's GetInspector method gives you an Inspector object to display an Outlook item. You can configure the inspector window before showing it by calling the Inspector object's Display method. The Display method takes an optional Modal parameter of type Object to which you can pass TRue to show the inspector window as a modal dialog box or False to show it as a modeless dialog box. If you do not need to configure the inspector window before you display it, you can just use the Display method on an Outlook item. The Display method displays an inspector window and takes an optional Modal parameter of type Object to which you can pass TRue to show the inspector window as a modal dialog box or False to show it as a modeless dialog box. If an inspector window is open for a given Outlook item, you can close the inspector window by using the Close method on the Outlook item being displayed. The Close method takes a SaveMode parameter of type OlInspectorClose. You can pass a member of the OlInspectorClose enumeration to this parameter: olDiscard to discard changes made in the inspector window, olPromptForSave to prompt the user to save if changes were made, and olSave to save without prompting. Listing 11.26 creates a PostItem in the Inbox folder and calls the Display method to display an inspector window for it. Then it calls the Close method passing OlInspectorClose.olDiscard to close the inspector window. Note that we have to cast the PostItem to the Outlook._PostItem interface to distinguish between the Close method and the Close event, which collide on Outlook item objects. Listing 11.26. A VSTO Add-In That Uses the Display and Close Method
Working with Built-In and Custom Properties Associated with an Outlook ItemThe ItemProperties property returns the ItemProperties collection associated with an Outlook item. This collection contains ItemProperty objects for each property associated with the Outlook item. By property, we mean a namevalue pair that may or may not also have a get/set property on the Outlook item type. The ItemProperties collection can be iterated over using the For Each loop. It also supports Visual Basic's index operator (). You can pass a String as the index representing the name of the ItemProperty you want to access. You can also pass a 1-based index for the ItemProperty you want to access in the collection. Listing 11.27 shows code that gets an ItemProperty object associated with a newly created PostItem using the index operator with a String and numeric index. Listing 11.27 also illustrates iterating over all the ItemProperty objects in the ItemProperties collection using For Each. Listing 11.27. A VSTO Add-In That Works with ItemProperty Objects
You can add your own custom properties to an Outlook item. Custom properties that you have added are accessed by using the UserProperties property. An Outlook item's UserProperties property returns a UserProperties collection that contains UserProperty objects representing custom properties you have added to an Outlook item. Just as with the ItemProperties collection, the UserProperties collection can be iterated over using the For Each loop. A particular UserProperty in the collection can be accessed using the index operator () to which you pass a String representing the name of the UserProperty or the 1-based index of the UserProperty in the collection. To add your own custom property, use the UserProperties collection's Add method. This method takes a required Name parameter of type String to which you pass the name of the new custom property. You must also specify the type of the new property by passing a member of the OlUserPropertyType enumeration. Common members of that enumeration you might use include olDateTime, olNumber, olText, and olYesNo. Other types are also supported; consult the Outlook object model documentation for more information. The Add method also takes two optional parameters that we omit: AddToFolderFields and DisplayFormat. Note that you can add custom properties to all Outlook item types except the NoteItem and DocumentItem types. Listing 11.28 shows the creation of several custom properties using the UserProperties.Add method. Listing 11.28. A VSTO Add-In That Works with Custom Properties
Saving an Outlook ItemAs you have already seen, when you create an Outlook item, you have to call the Save method, or the newly created item gets discarded when your variable containing the newly created item goes out of scope. You can check whether an Outlook item needs to be saved by accessing the Saved property. In Listing 11.28, for example, if we examine the Saved property right before we call postItem.Save at the end of the function, Saved would return False because some changes were made to the Outlook item (user properties were added) after the Save method was invoked earlier in the function. The code in Listing 11.28 works even when you omit the last call to Save. Consider what happens, however, if we omit the last call to Save. If you examine the newly created item, its Saved state is still False after this function runs. If you double-click the newly created item to display an Inspector view and then close the Inspector view without making any changes, Outlook prompts users to save the changes made to the item, which is confusing to users because they did not make any changes. Outlook prompts to save because it still detects that it needs to save the changes made to the user properties by the add-in code. If you exit Outlook, Outlook will save the changes to the newly created item, and on the next run of Outlook, the saved state of the new item will be back to true. Showing the Categories Dialog Box for an Outlook ItemYou can show the Categories dialog box in Figure 11.9 by using the Outlook item's ShowCategoriesDialog method. This dialog box allows the user to select categories to associate with an Outlook item. As described earlier, the Outlook item's Categories property enables you to examine what categories an Outlook item is associated with. The Categories property returns a String value with each category associated with the Outlook item in a comma-delimited list. Figure 11.9. Outlook's Categories dialog box. Mail Properties and MethodsSeveral commonly used properties and methods are associated with items that would be found in a mail folder, such as a MailItem or a PostItem. The BodyFormat property tells you what format the body of a mail message is in. It sets or gets a member of the OlBodyFormat enumeration: olFormatHTML, olFormatPlain, olFormatRichText, or olFormatUnspecified. When a message is set to have its BodyFormat in olFormatHTML, the HTML for the body of the message can be set or get via the HTMLBody property. This property gets and sets the String value, which is the HTML content of the message. Listing 11.29 shows add-in code that creates a PostItem using the BodyFormat and HTMLBody properties. Figure 11.10 shows the PostItem created by Listing 11.29. Listing 11.29. A VSTO Add-In That Creates a PostItem with BodyFormat Set to olFormatHTML
Figure 11.10. PostItem created by Listing 11.29. The Forward method returns a new Outlook item that can be forwarded to a recipient. Given a MailItem, for example, the MailItem object's Forward method returns a new MailItem. Then this MailItem can be given a recipient. Recipients of a MailItem are accessed via the Recipients property, which returns a Recipients collection. A new Recipient can be added by using the Recipients collection's Add method, which takes a String representing the display name of the recipient. When a recipient is added, the Outlook item can be sent in e-mail by calling the Outlook item's Send method. Listing 11.30 illustrates working with the Forward method, the Recipients collection, and the Send method. It creates a PostItem that it then forwards as a MailItem to a recipient. Listing 11.30. A VSTO Add-In That Creates a PostItem and Then Forwards It As a MailItem
An identical pattern is followed to reply or reply all to an Outlook item. The original item has its Reply or ReplyAll method called, which generates a new MailItem object. The Recipients collection of the new MailItem object is modified if needed. Finally, the new MailItem object's Send method is invoked to send the new MailItem. |
EAN: 2147483647
Pages: 221