About the GetEventDetails Subroutine

For every event that takes place in the monitored public folder, the Event Service automatically passes the intrinsic EventDetails object to the folder agent. The EventDetails object, part of the Event Service of Microsoft Exchange Server, has the following properties:

• EventDetails.Session. The CDO Session object that represents the CDO session the agent is currently logged on as. Because a script is handed this logged-in CDO session, it automatically has access to all CDO objects such as messages, appointment items, and Exchange directory information for look-ups.
• EventDetails.FolderID. The entry identifier of the folder in which the event took place.
• EventDetails.MessageID. A message identifier, if a message (and not a timer event) triggered the event.

The folder agent, by receiving an EventDetails object with its Session property, has in effect logged on to CDO, and by extension, to MAPI. (For more information, see EventDetails Gives Access to CDO.) This means that the agent can use all elements of the CDO object model, and can access MAPI properties. In other words, the EventDetails object gives the agent and its script full control over the form in the public folder.

Note  The Event Service also supports the IEventExchangeHandler interface, making its methods available to the agent. For information on the IEventExchangeHandler interface, query for "IEventExchangeHandler" in the Microsoft Platform SDK.

The following code from the LitCrit agent script file shows how the EventDetails properties are retrieved by the GetEventDetails subroutine. This code retrieves the MAPI entryIDs of the folder being monitored and the message (the LitCrit form) to which the event applies:

'------------------------------------------------------------
' DESCRIPTION: Get the details of the event that fired
'------------------------------------------------------------
Private Sub GetEventDetails()
   Dim idTargetFolder,idTargetMessage

   On Error Resume Next

   idTargetFolder = EventDetails.FolderID
   idTargetMessage = EventDetails.MessageID

After this code is run, the entryIDs of the monitored folder and the affected message are available for future use. You can now, for example, use the retrieved entryIDs and the CDO Session object to open the message.

GetEventDetails now continues by starting a CDO session, which gives the script access to all CDO functions. If this is a new critique that needs approval, the code prepares to send a message by opening the Outbox associated with the CDO session.

Set CDOSession = EventDetails.Session
Call DebugReport("EventDetails.Session",True)

If Err.Number = 0 Then
  ' We will send a msg, so let's get the Outbox here
  Set fldrOutbox = CDOSession.Outbox
  Call DebugReport("CDOSession.Outbox",True)

Next, the following code opens the message associated with the event. This step must be performed before working with the fields (accessed as MAPI properties) of that message:

  If Err.Number = 0 Then
  Set fldrTarget = CDOSession.GetFolder( idTargetFolder, Null )
    Call DebugReport("CDOSession.GetFolder",True)

      If Err.Number = 0 Then
    Set msgTarget = CDOSession.GetMessage( idTargetMessage, Null )
    Call DebugReport("CDOSession.GetMessage",True)
      End If
  End If
End If

One important accomplishment of the preceding GetEventDetails code is setting the value of the msgTarget variable to the message that triggered the event. This variable is used frequently in both the Folder_OnMessageCreated and Message_OnChange subroutines, which call GetEventDetails before any other actions.