Creating an Event

Declaring Event Handlers

VBScript supports implicit binding, which means that you only have to supply a function implementation in the following format for successful binding:

       sub EventSource_EventName( argument_list )
           ' event handler code goes here
       end sub

Compiled handlers need to hook into XSI, which makes them more involved to deal with, but you can use the callback function for the API you are using:

• To use the XSIOnEvent callback function to declare your event handler (COM API)

• To use the XSIOnEventCPP callback function to declare your event handler (C++ API)

To use the XSIOnEvent callback function to declare your event handler (COM API)

This is the simplest way to handle events: you need to provide an external DLL or SO that includes the XSIOnEvent function containing a case for each bound event:

    HRESULT WINAPI XSIOnEvent
    (
       LONG        in_lEventID,
       LPVARIANT   in_pVar,
       LONG        in_lNum
    )
    {
       switch (in_lEventID)
       {
           case siOnBeginSceneSave:
           {
              if (!CanSaveMyCurrentScene())
              {
                  // abort the operation using the predefined abort argument
                  LPVARIANT pVar = V_VARIANTREF(&in_pVar[1]);
                  V_BOOL(pVar) = VARIANT_TRUE;
              }
           }
           break;
       };
       return S_OK;
    }

The XSIOnEvent callback function takes these arguments:

Type | Description
[in] DISPID | Identifies the event that was fired by XSI.
[in] VARIANT* | Contains the argument value(s) specific to a particular event; for instance the OnEndSceneOpen will have the name of the scene being opened as argument.
[in] LONG | Number of arguments contained in the array.

It returns an HRESULT with one possible value:

Type | Description
S_OK | Indicates a successful operation.

| To abort the operation, set the Abort argument to TRUE. The position of this argument in the argument array is specific to the event itself.

| Not all events support an Abort argument. For example, OnTerminate cannot be interrupted.

To use the XSIOnEventCPP callback function to declare your event handler (C++ API)

You need to provide an external DLL or SO that includes the XSIOnEventCPP:

       XSI::CStatus XSIOnEventCPP( long in_eventID,  XSI::CValueArray& in_args);

Parameter | Description
in_eventID | Event ID to process
in_args | Array of arguments for this specific event

Exporting Event Handlers

As is the case with developing any compiled function as part of a plug-in for XSI, you need to export your function with a DEF file so that XSI can find it.

To export your event handler function

- Specify a a DEF file similar to this one:

       LIBRARY MYHNDL
       DESCRIPTION "Event and command handler function."
       EXPORTS
           XSIOnEvent @1 PRIVATE
           XSIOnCommand @1 PRIVATE

| XSIOnEvent needs to be exported only if it is defined in the .dll.

| Remember that for calling callback functions, XSI uses the name of the function, not its ordinal value.

How To Capture XSI's Initialization And Termination

You can use the DllMain function in your DLL to run any customization routines while XSI loads your DLL(DLL_PROCESS_ATTACH) or terminates (DLL_PROCESS_DETACH). For example, you may want to perform some process initialization local to the DLL. For more information, see the MSDN Library.