C API (Component Interface)
The General Interface offers aspects of Engine functionality to all Components. The interface is accessed by sending Engine Events.
- User code will NOT generally have to call these events explicitly. Each binding provides wrapper functions for most of these events. See the documentation for your binding for more information.
ENGINE_EVENT_CREATE_UTILITY will usually be wrapped by the interface provided by the individual Utility Component. See the documentation for the specific Utility Component for more information.
Symbol hCaller IN
- This should always be set to the handle of the calling component, if possible. Failure to do so will raise an error in most events.
UINT32 flags IN
- None defined (must be zero).
Symbol type IN
- The Engine
Event being called.
- void* data IN/OUT
- The data associated with the event (can be NULL for some events).
Usually, just check the return value of using an
S_ERROR macro provided in the binding you are using. If it is an error, you can return it directly to the framework, ignoring its value, and the nature of the error will be reported when execution terminates. If not, you can assume it is a valid return value as specified by the interface function, and continue processing. More information follows, if you are curious.
- Many events in the interface require a pointer to a data structure to be passed in as
data. If this argument is
NULL to one of these events,
E_NULL_ARG is returned. Some events, in addition, will return
E_NULL_ARG when one or more fields of
- Many events require the caller to pass one or more handles to objects in fields of
data (and, at least,
hCaller to specify the calling component). One of the following errors will be raised if one of these handles is no good.
- Any event may return an error code that is not listed in the documentation, so you should test all return codes with the
S_ERROR function provided in each of the bindings (1065, 1199 or 1266). If you encounter an error, and either you don't recognise it or you don't want to check what it is, you should return the error code directly to the framework as the return code of your
event() function. Internal errors in the framework will, for instance, return unlisted error codes, which you will not be able to identify.
- Any function that does not return data in its return value will return
on successful completion.