Overview
C API (Component Interface)
struct Event { Symbol type; UINT32 flags; void* object; void* data; }; typedef Symbol (EventHandlerFunction) (struct Event*);

Components offer services to the Engine (and to other components) by exporting a function to handle events. All component processing is done during the servicing of these events. The EventHandler() function is the entry point for all events fired on the component. It is usually called by the Engine, but other components may also call it - in particular, process components access the content of data components through this interface, and process and data components access the services offered by utility components through this interface. The function must have the form defined above, returning a Symbol representing a return code. Data is passed in and out of the event function via the Event structure, which has one field, data, in which event-specific data is passed in and out.

When authoring the Events interface of a new component, you can start by servicing no events. The framework will tell you when failure to service a particular event has caused a problem. A process will need to service two or three events to function properly.

Notes
  • In all events, the data structure (Event::data) is created by the framework and passed in to the event.

Fields

Symbol type IN
The type of event being fired (see below).
UINT32 flags IN
Flags which carry information to the component about the event. Specific flags are listed under the individual events. The flags listed below may be set on any event.
void* object IN
The object of the event. A module may create multiple component instances, and this field will be a pointer to the particular instance that is having its event fired. The value placed here is whatever the module returned whilst servicing EVENT_MODULE_CREATE, so this value is NULL until that event is fired.
void* data IN/OUT
Additional event data (event-specific). May be used to pass data in to the event, to pass data back, or both.
Symbol <return code> OUT
Specific return codes are listed under the individual events. The following codes may be returned from any event: S_NULL event was not processed; C_OK event was processed without error.

Flags

F_FIRST_CALL
If set, this is the first call to this event in this event-burst. This flag is only set for events that receive multiple calls.
F_LAST_CALL
If set, this is the last call to this event in this event-burst. This flag is only set for events that receive multiple calls.
F_GLOBAL_ERROR
If set, an error condition has been raised somewhere in the system and the execution will be coming to an end prematurely. You can use this flag as you see fit, but it is good practice to close down in a fail-safe way anyway, so it may be safest to ignore it.
F_LOCAL_ERROR
The local error flag is also set if the error was raised by the component servicing the current event.

Event types

The event types defined by the framework are listed below (components may define their own events too). Each type links to a page describing the event type in more detail. The documentation for individual event types should be largely self-explanatory. To see all these events as they appear in the context of an execution, see Life Cycles.

Notes
  • The event-specific data structure used by the event appears at the top of each event documentation page. It is this structure that will be passed in event->data.
  • "Actions" is a list of actions that you might want to perform depending on conditions, rather than a list of actions that you must perform.

Module-level Events

This interface is used to manage Component instances through a Component Module.

EVENT_MODULE_INIT Initialise module, return module-specific information.

EVENT_MODULE_TERM Terminate module.

EVENT_MODULE_CREATE Create a new component instance.

EVENT_MODULE_DESTROY Destroy an existing component instance.

EVENT_MODULE_DUPLICATE Duplicate an existing component instance.

Component-level Events

All Components

Framework

This interface is used exclusively by the framework to access the functionality of all Component objects.

EVENT_STATE_SET Set component state from an XML node.

EVENT_STATE_GET Retrieve component state as an XML node.

EVENT_LOG_INIT Advise component it should log during upcoming execution.

EVENT_LOG_TERM Retrieve component's log.

Processes

Framework

This interface is used exclusively by the framework to access the functionality of Process objects.

EVENT_INIT_PRECONNECT The process input interface now has its structure finalised (though the ports are currently all empty).

EVENT_INIT_CONNECT This event is fired multiple times, with more input ports filled on each call. The process may create outputs on any call.

EVENT_INIT_POSTCONNECT The connection phase has finished, and all input ports are now connected and filled. The system-wide base sample rate has been calculated, and all timing values are now finalized.

If you receive EVENT_RUN_PLAY, you will receive EVENT_RUN_STOP, even if you raised an error whilst servicing EVENT_RUN_PLAY. If you receive EVENT_RUN_RESUME, you will receive EVENT_RUN_PAUSE, even if you raised an error whilst servicing EVENT_RUN_RESUME. In general, if you raise an error at any time in the run phase, you will receive the necessary events to walk you back down to a STOP state.

EVENT_RUN_PLAY The process is now running in its run-phase environment. Do expensive run-phase environment initialisation now (e.g. GUI construction).

EVENT_RUN_RESUME Execution is moving from pause state to run state.

EVENT_RUN_SERVICE The Engine requests the process to service its interfaces.

EVENT_RUN_PAUSE Execution is moving from run state to pause state.

EVENT_RUN_STOP The process is running in its run-phase environment for the last time. Do expensive run-phase environment termination now (e.g. GUI deconstruction).

Data

Warnings
  • It is currently strongly recommended that you do not attempt to author Data components, since their interface may change in future.

Framework

This interface is used exclusively by the framework to access the functionality of Data objects.

EVENT_LOG_SERVICE The component has just been written and should log its current state into its log. Note that a process should service its log, if keeping one, during EVENT_RUN_SERVICE.

EVENT_CONTENT_SET Set data content from a byte stream (i.e. unserialize).

EVENT_CONTENT_GET Retrieve data content as a byte stream (i.e. serialize).

Native

This interface is used by native Process objects to access the functionality of Data objects. All Data objects will fill this interface with events that allow access to their state in a structured way. Note that Datas should define inline accessors in the header file that simplify use of this interface from C++, so C++ Processes should never need to fire these events directly.

Generic

This interface is used by non-native Process objects to access the functionality of Data objects. This interface will be used exclusively by language bindings, and Data access will be translated for non-native Processes by the bindings onto an interface appropriate for the language.

We describe the complete state of any component using the term "State". Data objects have, in addition, a distinction made between their "Structure" (that which does not change over time) and their "Content" (that which does).

EVENT_GENERIC_STRUCTURE_GET Return the state structure as a string.

EVENT_GENERIC_STRUCTURE_SET Set the state structure from a string.

EVENT_GENERIC_FORM_ADVANCE Return the form of the "generic" representation of the state content in advance.

EVENT_GENERIC_FORM_CURRENT Return the form of the "generic" representation of the current state content.

EVENT_GENERIC_CONTENT_GET Return the "generic" representation of the current state content.

EVENT_GENERIC_CONTENT_SET Set the current state content from the "generic" representation.

Utility only

Warnings
  • It is currently strongly recommended that you do not attempt to author Utility components, since their interface may change in future.

Framework

Utility objects have no framework interface, since the framework does not need to call them.

Native

This interface is used by native Components to access the functionality of Utility objects. All Utility objects will fill this interface with events that allow access to their functionality in a structured way. Note that Utilities should define inline accessors in the header file that simplify use of this interface from C++, so C++ Processes should never need to fire these events directly.

Generic

This interface is used by non-native Components to access the functionality of Utility objects. This interface will be used exclusively by language bindings, and Utility functionality will be translated for non-native Processes by the bindings onto an interface appropriate for the language.

EVENT_FUNCTION_GET The utility object should return usage information for the specified utility function.

EVENT_FUNCTION_CALL The utility object should provide functionality by servicing this event.