|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
Structure for the Event API version 20110330. More...
#include "eventapi.h"
Data Fields | |
| HqBool | valid |
| Is this API initialized? | |
| sw_rdr_result(* | register_handler )(sw_event_type, sw_event_handler *, sw_event_priority) |
| Register an Event Handler. More... | |
| sw_rdr_result(* | deregister )(sw_event_type, sw_event_handler *) |
| Deregister an Event Handler registered with SwRegisterHandler(). More... | |
| sw_event_result(* | event )(sw_event_type, void *, size_t) |
| Generate an event, calling relevant handlers in priority order. More... | |
| sw_event_result(* | event_tail )(sw_event *) |
| Call the remaining Handlers for the current Event, returning the value that would have been returned to the Issuer. More... | |
| sw_rdr_result(* | register_handlers )(sw_event_handlers *, int) |
| Register multiple Event Handlers atomically. More... | |
| sw_rdr_result(* | deregister_handlers )(sw_event_handlers *, int) |
| Deregister multiple Event Handlers. More... | |
| sw_rdr_result(* | safe_deregister )(sw_event_type, sw_event_handler *) |
| Deregister an Event Handler detecting Handler threading. More... | |
Structure for the Event API version 20110330.
| sw_rdr_result( * sw_event_api_20110330::deregister) (sw_event_type, sw_event_handler *) |
Deregister an Event Handler registered with SwRegisterHandler().
Deregisters a previously registered Handler. This can be called by the Handler itself.
Although this guarantees that the Handler will not be called again, it does NOT guarantee that the Handler is not currently threaded.
| [in] | type | The Event type. |
| [in] | handler | The sw_event_handler structure previously registered. |
| SW_RDR_SUCCESS | if successfully deregistered; |
| SW_RDR_ERROR_IN_USE | if the Handler was theaded; |
| SW_RDR_ERROR_UNKNOWN | if the Handler was not registered. |
Note that even if SW_RDR_ERROR_IN_USE is returned, the Handler HAS been successfully deregistered, though it may still be threaded. If so, this call can be repeated until it no longer returns SW_RDR_ERROR_IN_USE, or SwSafeDeregisterHandler() called instead to wait for the Handler to exit.
| sw_rdr_result( * sw_event_api_20110330::deregister_handlers) (sw_event_handlers *, int) |
Deregister multiple Event Handlers.
This deregisters a number of Handlers in one call, regardless of errors, and guarantees that they are not threaded on exit.
This is more concise than multiple calls to SwSafeDeregisterHandler(), but is entirely equivalent. If any Handler is not registered an error is returned after all other Handlers have been deregistered.
| [in] | handlers | An array of sw_event_handlers as previously passed to SwRegisterHandlers(). |
| [in] | count | The number of entries in this array. |
| SW_RDR_SUCCESS | if all successfully deregistered; |
| SW_RDR_ERROR_UNKNOWN | if any were not registered. Note that ALL Handlers will have been deregistered, this error is purely informational. |
Note that this call cannot be used by a Handler to deregister itself. Be careful not to use this call in any code that can be called from a Handler that is to be deregistered.
| sw_event_result( * sw_event_api_20110330::event) (sw_event_type, void *, size_t) |
Generate an event, calling relevant handlers in priority order.
The meaning, parameters and return values pertinent to a particular Event are defined by the Event owner. Some Events may merely be used as a signal to inform interested parties of a change in state. Some may contain data or a reference to a buffer. Others may require specific return codes for successful completion. This is all up to the Event owner.
| [in] | type | The event type. |
| [in] | message | The message pointer for this event. Note that much like the RDR system which underpins the Event system, no interpretation of this pointer is mandated - it may be a pointer to some information, or to a buffer to fill in, or some other arbitrary address such as a memory limit. It may often be NULL. |
| [in] | length | The length associated with the above message pointer. Once again, no interpretation is placed on the meaning of this value - it may refer to the length of the message or may be an arbitrary number. This is defined by the issuer of the Event in question. It may often be zero. |
>= SW_EVENT_ERROR. Error return values in that range can be defined on a per-Event basis, and may not actually indicate a fault for that Event definition! | sw_event_result( * sw_event_api_20110330::event_tail) (sw_event *) |
Call the remaining Handlers for the current Event, returning the value that would have been returned to the Issuer.
This call can only be made by a Handler, passing in the sw_event delivered to it. The remaining Handlers - the "tail" - can be called multiple times if the current Handler wishes. How the return values are combined or what value is ultimately returned is up to the current Handler.
Note that calling SwEventTail() does not automatically prevent the remaining Handlers from being called once more if the current Handler returns SW_EVENT_CONTINUE - see SW_EVENT_FORCE_UNHANDLED.
| [in] | event | The sw_event structure passed to the Handler. It is permissible for the Handler to change the message and length fields of the sw_event, but the opaque context field must be preserved for SwEventTail() to function. |
>= SW_EVENT_ERROR may be returned by the remaining Handlers, if any. The current Handler may choose to return some other value if it wishes. | sw_rdr_result( * sw_event_api_20110330::register_handler) (sw_event_type, sw_event_handler *, sw_event_priority) |
Register an Event Handler.
This registers a Handler with the Event system, or reregisters a previously registered handler with a different priority. This can be done by the Handler itself while being executed, if it wishes.
Note that SwRegisterHandler is just syntactic sugar for an RDR registration.
| [in] | type | The Event type. |
| [in] | handler | A sw_event_handler structure containing a pointer to the Event Handler function, and optionally its private context. This structure must continue to exist and not be modified externally until the corresponding SwDeregisterHandler() call. |
| [in] | priority | A priority, as for RDR registrations. |
| SW_RDR_SUCCESS | if successfully registered. |
| SW_RDR_ERROR | in the unlikely event of too many Handlers being registered. |
| sw_rdr_result( * sw_event_api_20110330::register_handlers) (sw_event_handlers *, int) |
Register multiple Event Handlers atomically.
This registers a number of Handlers in one call, and does so atomically - if any fail to register, any that have will be deregistered.
This is more concise than multiple calls to SwRegisterHandler(), but is entirely equivalent.
| [in] | handlers | An array of sw_event_handlers containing a pointer to the Event Handler function, its private context, the Event type and the priority. These structures must continue to exist and not be modified externally until the corresponding SwDeregisterHandlers() call. |
| [in] | count | The number of entries in the handlers array. |
| SW_RDR_SUCCESS | if successfully registered. |
| SW_RDR_ERROR | in the unlikely event of too many Handlers being registered. |
Should this call return an error it is guaranteed that no Handlers are registered or threaded. However, it cannot guarantee that none were called.
| sw_rdr_result( * sw_event_api_20110330::safe_deregister) (sw_event_type, sw_event_handler *) |
Deregister an Event Handler detecting Handler threading.
This deregisters a Handler immediately like SwDeregisterHandler() but also detects whether the Handler is currently threaded. If so it does not return until the Handler exits.
| [in] | type | The Event type. |
| [in] | handler | The sw_event_handler structure previously registered. |
| SW_RDR_SUCCESS | if successfully deregistered; |
| SW_RDR_ERROR_UNKNOWN | if the Handler is not registered. |
Note that this call cannot be used by a Handler to deregister itself. Be careful not to use this call in any code that can be called from the Handler that is to be deregistered.