Items Collection Events

Like the Folders collection object, the Items collection object gives you a great deal of control over what happens in folders and with the items contained within folders. You can use the Items collection events to respond to message created, changed, and deleted events. The Items collection does not have a timer event like the Exchange Event Service does, although you can readily construct a timer-based COM Add-in with a Visual Basic Timer control or Windows API calls. Unlike the Exchange 5.5 Event Service or Exchange 2000 event sinks, Items collection events do not provide server-based scalability and process isolation. Exchange 2000 offers the additional benefit of supporting both synchronous and asynchronous events for event sinks.

The following table compares the Exchange 5.5 Event Service, the Exchange 2000 event sinks, and a Visual Basic COM Add-in that uses Items collection object events.

Feature	Exchange 5.5 Event Service	Exchange 2000 Event Sink	COM Add-In
Development language	VBScript	Visual Basic or Visual C++	Visual Basic, Visual C++, or any other development tool for an ActiveX DLL
Object binding	Late-bound	Early-bound	Early-bound with proper declaration of variables
Variable types	Variant only	All supported types	All supported types
Scalability	Yes	Yes	Limited
Process location	Server	Server	Client
Error Logging	Windows NT Event Service	Windows NT Event Service	Error log on client must be created by developer

ItemAdd

The ItemAdd event occurs when an item is added to an Items collection object, either through user action or program code. The following example creates an Items collection object for an Exchange public folder named Customers that contains Contact items. When a new customer is added to the Customers folder, a message is sent to a distribution list for the correct regional sales team. This example requires another event procedure in order to instantiate the collection object for the Customers folder. So that you can better understand the code, each of these event procedures is listed below. See Chapter 11 for a complete listing of the OpenMAPIFolder function.

'Place these declarations in the general section of Class module
Public WithEvents colCustomersItems As Outlook.Items

'Instantiate collection object in objOutlook Startup event
 
Private Sub objOutlook_Startup()
    Dim strFolderPath As String
    StrFolderPath = "Public Folders\All Public Folders\" _
        & "Contact Management\Customers"
    Set colCustomersItems = OpenMAPIFolder(strFolderPath).Items
End Sub

'This event procedure sends a message to a DL
Private Sub colCustomersItems_ItemAdd(ByVal Item As Object)
Dim objContactItem As Outlook.ContactItem
Dim objMsgItem As Outlook.MailItem
Set objContactItem = Item
If objContactItem.MessageClass = "IPM.Contact.Customer" Then
    Select Case objContactItem.BusinessAddressState
        Case "CA", "NV", "WA", "OR", "AZ", "NM", "ID"
        strDL = "Sales Team West"
        Case "IL", "OH", "NE", "MN", "IA", "IN", "WI"
        strDL = "Sales Team Midwest"
        Case "ME", "NH", "NY", "NJ", "MD", "PA", "RI", "CT", "MA"
        strDL = "Sales Team East"
        Case Else
        strDL = "Sales Team National"
    End Select
    Set objMsgItem = objOutlook.CreateItem(olMailItem)
    objMsgItem.Subject = "New Customer - " & _
    objContactItem.CompanyName
    objMsgItem.Save
    objMsgItem.Attachments.Add objContactItem, olByValue
    'Must use trusted COM Add-in to prevent OM guard prompts
    objMsgItem.To = strDL
    objMsgItem.Send
End If

ItemChange

The ItemChange event occurs when an item in an Items collection object is changed, either by user action or program code. Continuing the example of the Customers folder described earlier, the following code writes a record to a SQL Server 7 database when an item changes in the Customers public folder. The StrClean function in the following procedure removes single quotes that could cause an error when the SQL statement executes:

Private Sub colCustomersItems_ItemChange(ByVal Item As Object)
    Dim objCont As Outlook.ContactItem
    Dim strSQL As String
    Const strSep = "','"
    Dim conDB As New ADODB.Connection
    Set objCont = Item
    If objCont.MessageClass <> "IPM.Contact.Customer" Then
        Exit Sub
    End If
    On Error GoTo AddContact_Error
    conDB.Open "Nwind", "sa", ""
    strSQL = "Insert Customers Values ('"
    strSQL = strSQL & StrClean(objCont.Account & strSep
    strSQL = strSQL & StrClean(objCont.CompanyName) & strSep
    strSQL = strSQL & StrClean(objCont.FullName) & strSep
    strSQL = strSQL & StrClean(objCont.JobTitle) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessAddress) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessAddressCity) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessAddressState) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessAddressPostalCode) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessAddressCountry) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessTelephoneNumber) & strSep
    strSQL = strSQL & StrClean(objCont.BusinessFaxNumber) & "')"
    conDB.Execute strSQL
    conDB.Close

    AddContact_Exit:
    Exit Sub

    AddContact_Error:
    Utility.ErrorTrap 'Writes error to event log or file
    Resume AddContact_Exit
End Sub

ItemRemove

The ItemRemove event occurs when an item is removed from a specified Items collection object, either through user action or programmatically. The following example expands on the FolderRemove example described earlier to show how to undelete an item programmatically. This example undeletes a custom form with a message class of IPM.Post.ContactSettings if a user deletes the item from the Settings subfolder of the Inbox.

'Place these declarations in the general section of ThisOutlookSession
Public WithEvents colDeletedItems As Outlook.Items
Public WithEvents colSettingsItems As Outlook.Items
Public blnDeleteItem As Boolean

Private Sub Application_Startup()
    Set objNS = Application.GetNameSpace("MAPI")
    Set colSettingsItems = _
      objNS.GetDefaultFolder(olFolderInbox).Folders("Settings")
    Set colDeletedItems = objNS.GetDefaultFolder(olFolderDeletedItems).Items
End Sub

Private Sub colSettingsItems_ItemRemove()
    blnDeleteItem = True
End Sub

Private Sub colDeletedItems_ItemAdd(ByVal Item As Object)
    If blnDeleteItem and Item.MessageClass = "IPM.Post.ContactSettings" Then
        Set objDestFolder = _
           objNS.GetDefaultFolder(olFolderInbox).Folders("Settings")
        Item.Move objDestFolder
    End If
    blnDeleteItem = False
End Sub