Next: CreateCallback

Defines a callback function for intercepting game events.

Syntax

AurieStatus CreateCallback(
    [in] AurieModule*  Module,
    [in] EventTriggers Trigger,
    [in] PVOID         Routine,
    [in] int32_t       Priority
);

Parameters

Module

A pointer to the module that is registering this callback. If a valid module is not supplied, the tool may fail to automatically unregister the callback when the module that registered the callback unloads. In such cases, the module that registered the callback must manually call RemoveCallback before it is unloaded by the Framework. If a valid module is specified, the tool automatically unregisters all callbacks for the given module when it unloads. Callers should, unless needed, specify g_ArSelfModule.

Trigger

The specific event to listen for. Values here must not be bitwise-ORed together, as the system is not meant to handle one function being registered for multiple triggers. The trigger type specified here dictates the parameters passed into the function pointed-to by the Routine argument.

Routine

A pointer to a function responsible for handling the callback. Each routine registered must be unique, making it impossible to create a callback handler that handles multiple types of callbacks. The prototype for a callback function must be as follows:

void ExampleFunction(
    IN FWCodeEvent& FunctionContext // replace FWCodeEvent& with the corresponding type
);

The templated parameters provided to FunctionWrapper are dependant upon the Trigger parameter passed into the function. Predefined types exist for the callbacks handled by the tool, and are listed in the table below, together with their uses.

Trigger	Type	Target event
EVENT_OBJECT_CALL	FWCodeEvent	Object events (Create, Step, ...)
EVENT_FRAME	FWFrame	Frame rendering (Present)
EVENT_RESIZE	FWResize	Window resizing (ResizeBuffers)
EVENT_SCRIPT_CALL	FWScriptEvent	Script invocations (VM-only)
EVENT_WNDPROC	FWWndProc	Generic window events

Priority

The order in which callbacks are called by the tool is determined based off their priority. Callbacks are called from highest-priority to lowest-priority, with the default priority being 0. Unless specifically needed, callers should pass 0 for this parameter.

Return Value

The function returns AURIE_SUCCESS on success, otherwise returns a matching error code. If the routine is already registered for the given module, the function returns AURIE_OBJECT_ALREADY_EXISTS.