SyncObject Events

A child object of the NameSpace object, SyncObject represents a Send/Receive group that controls offline synchronization in Outlook 2002. In Outlook 2000, a Send/Receive group is known as a Quick Synchronization group. You cannot establish a SyncObject programmatically by using an Add method of the SyncObjects collection object. Both the SyncObjects collection object and the SyncObject object are read-only objects, meaning that you cannot change the properties of a SyncObject or create a new SyncObject programmatically. You can, however, create a SyncObject (known in Outlook 2002 as a Send/Receive group) through the Outlook user interface. For additional information about creating and modifying Send/Receive groups, see "Make the Folder Available for Offline Use" in Chapter 8, "Folders."

NEW TO OUTLOOK 2002 Although you cannot create a SyncObject programmatically, there is one SyncObject you can modify programmatically in Outlook 2002: the Application Folders SyncObject. By using the InAppFolderSyncObject property of a MAPIFolder object, you can programmatically synchronize folders for the Application Folders SyncObject. If the Application Folders Send/Receive group does not exist when you set InAppFolderSyncObject to True, the Application Folders SyncObject is created automatically. The user does not have to create this group through the Outlook user interface. Keep in mind that other properties of the Application Folders Send/Receive group must be modified through the user interface. You cannot programmatically control other Send/Receive settings such as Synchronize Forms, Download Offline Address Book, or Make Folder Home Pages Available Offline.

If you need to enumerate the defined SyncObjects for the current logged-on user, use the SyncObjects collection object of the NameSpace object. Figure 9-10 illustrates a UserForm populated with Send/Receive groups. The following code block demonstrates how to populate a list box with SyncObjects and start synchronization when the user clicks the Start Sync command button. Notice that a default group of All Folders is defined, in addition to custom Send/Receive groups.

'Place this declaration in the general section of frmSync code window
Dim colSyncObjects As Outlook.SyncObjects

Private Sub cmdCancel_Click()
    Unload Me
End Sub

Private Sub cmdStart_Click()
    Set ThisOutlookSession.objSyncObject = _
      colSyncObjects.Items(lstSync.ListIndex + 1)
    colSyncObjects.Item(lstSync.ListIndex + 1).Start
    Unload Me
End Sub

Private Sub lstSync_DblClick(ByVal Cancel As MSForms.ReturnBoolean)
    Call cmdStart_Click
End Sub

Private Sub UserForm_Initialize()
    Set colSyncObjects = ThisOutlookSession.objNS.SyncObjects
    For i = 1 To colSyncObjects.Count
        lstSync.AddItem colSyncObjects.Item(i)
    Next
End Sub

Figure 9.10 - Show a UserForm to select and start the synchronization of a Send/Receive group

OnError

The OnError event fires when an error occurs during synchronization of a Quick Synchronization group represented by a SyncObject. The following code example displays a message to the Help Desk when the OnError event for a SyncObject fires. Notice that objSyncObject is instantiated in the Quick Synchronization group's UserForm example shown earlier. When the user selects a synchronization profile in the UserForm and clicks the Start Sync command button, a reference is set to objSyncObject declared in ThisOutlookSession.

Private Sub objSyncObject_OnError(ByVal Code As Long, _
ByVal Description As String)
    Dim objMsg As Outlook.MailItem
    strText = Now() & " Sync Error " & CStr(Code) & Space(1) & Description
    Set objMsg = Application.CreateItem(olMailItem)
    With objMsg
        .Recipients.Add ("Help Desk")
        .Recipients.ResolveAll
        .Body = strText
        .Display
    End With
End Sub

Progress

Use the Progress event to inform a user about the completion percentage of a synchronization job for a Send/Receive group. Notice that the Progress event provides several values that let you provide information to the user. The Value variable specifies the current value of the synchronization process based on the number of items synchronized; Max represents the total number of items to be synchronized; and State identifies the current state of the synchronization process where state has one of two values representing whether synchronization has started or stopped. The following example updates the label named lblCaption on frmProgress during the synchronization process:

Private Sub objSyncObject_Progress(ByVal State As Outlook.OlSyncState, _
  ByVal Description As String, ByVal Value As Long, ByVal Max As Long)
    Dim strCaption As String
    If State = olSyncStarted Then 
        strCaption = "Synchronization started: "
    Else
        strCaption = "Synchronization stopped: "
    End If
    strCaption = strCaption & Str(Value / _
      Max * 100) & "% " & Description
    frmProgress.lblCaption = strCaption
End Sub

SyncEnd

The SyncEnd event takes place when the synchronization of a Send/Receive group is completed. The code example unloads a UserForm that showed the synchronization progress to the user.

Private Sub objSyncObject_SyncEnd()
    Unload frmProgress
End Sub

SyncStart

The SyncStart event takes place when the synchronization of a Quick Synchronization group begins. The code example displays a UserForm that uses the Progress event to inform the user about synchronization progress.

Private Sub objSyncObject_SyncStart()
    frmProgress.Show
End Sub