Server Extension Programmer's Guide:
Using Synchronous Events

What Are Synchronous Events?

The SAAPI Synchronous Events functionality allows you to develop custom code that is triggered by eRoom events. When one of these eRoom events occurs, eRoom makes a synchronous call into your custom code. That means that eRoom will wait for your custom code to return control before continuing to process the event. By allowing you to write custom code that can halt or resume eRoom functionality, Synchronous Events provide a high degree of interactivity between your custom code and the eRoom server.

Note: SEAPI, eRoom’s obsolete asynchronous event mechanism, and it’s ”r;Extension Manager” service have been replaced with Synchronous events. The new ”r;Extension Manager” that is used to configure all types of eRoom server extensions should not be confused with the old V.6 and older ”r;Extension Manager Service” that executed SEAPI events.

There are no synchronous events for display settings on object- or member-specific item settings. With few exceptions, events are raised before and after most eRoom item property changes. Display settings and user-level settings on objects don’t fire events.  For example, setting the default sortColumn or user-specific sortColumn does not fire an event.

Tip: Log in to each eRoom server after making synchronous event handler configuration changes to ensure that components are properly deployed. This is essential, as eRoom will block all access to the server if there are errors loading or registering event handlers. This must be done for security reasons.

For important information that is common to multiple extension types, refer to the topic Common Extension Information.

For reference information on the SAAPI Synchronous Event interfaces, see the Synchronous Events book in the table of contents.

Event Handlers

In order to use the Synchronous Event functionality, you must develop an event handler in the form of a COM DLL. This event handler must implement the IERUEventHandler interface. You can register your handler to be notified either before or after an eRoom event occurs. Typical examples of "before" event handlers are passing a username or password to an external authentication engine before granting access to an eRoom or checking for viruses before uploading a file to an eRoom. Typical examples of "after" event handlers are running notification, logging, or cleanup routines after an eRoom event occurs.

Writing a Synchronous Event Handler

In order to take advantage of the Synchronous Event functionality, you must write an event handler. First, decide which eRoom event you want to handle. The choices are listed in the enum ERUSynchronousEventType. Next, create a COM DLL that implements the IERUEventHandler interface. For performance reasons, it is preferable that you implement event handlers in C++ rather than Visual Basic.

There is an example of an event handler in Toolkit\Samples\SynchronousEvents\AutoVersion. Use this as a guide when writing your event handlers. This section explains in detail how to implement each of the methods in the IERUEventHandler interface.

Development Tool Considerations

Synchronous event handlers are in process COM objects that implement the IERUEventHandler interface.  We recommend that event handlers be written using C++ using the apartment model. VB COM objects can be marshaled into another thread when called. Since eRoom security is tied to the thread, the VB event handler would have to establish a user context itself. (See the LogonUser and ERUUserContext objects.)

See also: Please see Programmer's Guide: Programming Guidelines and Recommendations for important details on Building Visual Basic .DLLs.

General Guidelines

• Use the provided synchronous event interfaces to get at objects from the event synchronous event object.

• You must establish an eroom user context (login) for the thread if you wish to get your own objects.

• If your component is a VisualBasic object (not free threaded), certain events (authentication and checkpassword) will be marshaled into another thread.  This other thread will have a user context established and IERUSEvent::LoggedInMember will return NOTHING (NULL). In this case, you must establish a user context for that thread prior to accessing the properties.  See IERUUserContext::ImpersonateUser() or IERUApplication::LoginUser() for more details.

HandleEvent

The HandleEvent() method is where you implement your custom code. Perform any operation that you wish in response to being notified about the event. This method has one parameter, an IERUSynchronousEvent interface pointer, which contains contextual information about the eRoom event you are handling. The IERUSynchronousEvent interface contains information that is generic to every type of Synchronous Event. To retrieve information that is particular to the event you are handling, you can query interface IERUSynchronousEvent for one of the interfaces listed in the table below. You can only query for the interface that matches the EventType and EventSequence properties on the IERUSynchronousEvent interface.

If you are handling a ”r;before” event, then you can discontinue the eRoom operation by returning the hresult, EROOM_E_SEVENTHANDLER_FAILED. If you return any other failed hresult, eRoom will still continue with the operation. For example, if you are handling the "Authenticate Before" event, and the user’s credentials are not valid, then return EROOM_E_SEVENTHANDLER_FAILED in order to deny that user access to the eRoom. If you use this hresult and you are writing the DLL in C++, be sure to include "ERReturnCodes.h," which defines the value for that hresult.

Register

In the Register() method, tell eRoom which event this DLL handles. eRoom passes to this method a pointer to an IERUSynchronousEventRegister interface. Call the RegisterForEvent() method on this interface to tell eRoom which event your DLL handles and whether it handles the event before or after it occurs.

GetErrorString

You need to implement this method only if your event handler handles "before" events. If your HandleEvent() method returned EROOM_E_SEVENTHANDLER_FAILED, then eRoom will call GetErrorString() in order to retrieve an error message to display to the user. If you don't specify a string in this method, a default eRoom error message will be displayed to the user.

Debugging a Synchronous Event

An access denied error prevents debugging a synchronous event handler (a COM+ component) in Visual Basic 6. This is a security issue, and Microsoft has posted a Knowledge Base article on how to work around this. The article (ID Q25975) is located at:

http://support.microsoft.com/default.aspx?scid=kb;EN-US;q259725

Installing the Synchronous Event Handler

Once you’ve finished writing your event handler, you must deploy it on the eRoom Server. Follow these procedures in the Configuring Your Server Extension topic.