kzu_message_dispatcher.h File Reference

Message dispatcher. More...

Classes

struct  kanzi::TimerMessageArguments
 
class  kanzi::MessageDispatcherProperties
 
class  kanzi::MessageDispatcherProperties::WriteLogMessageArguments
 
class  kanzi::MessageDispatcherProperties::TimerMessageArguments
 

Namespaces

 kanzi
 

Typedefs

typedef kzsError(* KzuMessageHandlerFunction) (kanzi::MessageArguments *message, void *userData)
 Message callback prototype. More...
 
typedef kzsError(* KzuMessageDispatchFunction) (const kanzi::MessageArguments *message, void *userData)
 Application message callback prototype. More...
 
typedef function< void(const TimerMessageArguments &)> kanzi::TimerFunction
 
typedef shared_ptr< void > kanzi::TimerSubscriptionToken
 

Enumerations

enum  KzuTimerMessageMode { KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT, KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH }
 Timer mode. More...
 

Functions

KANZI_API kzsError kzuMessageDispatcherCreate (const struct KzcMemoryManager *memoryManager, struct KzuMessageDispatcher **out_messageDispatcher)
 Create a message dispatcher. More...
 
KANZI_API kzsError kzuMessageDispatcherDelete (struct KzuMessageDispatcher *messageDispatcher)
 Destroy a message dispatcher. More...
 
KANZI_API kzsError kzuMessageDispatcherAddHandler (const struct KzuMessageDispatcher *messageDispatcher, kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, kanzi::Node *messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
 Adds a message handler. More...
 
KANZI_API kzsError kzuMessageDispatcherAddTunnellingHandler (const struct KzuMessageDispatcher *messageDispatcher, kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, kanzi::Node *messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
 Adds a message handler for tunneling phase. More...
 
KANZI_API kzsError kzuMessageDispatcherIsHandlerSubscriptionValid (const struct KzuMessageDispatcher *messageDispatcher, const kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, KzuMessageHandlerFunction handlerFunction, const void *userData, kzBool *out_valid)
 Checks if a handler subscription is valid. More...
 
KANZI_API kzsError kzuMessageDispatcherRemoveHandler (const struct KzuMessageDispatcher *messageDispatcher, const kanzi::Node *subscriptionSiteNode, const struct KzuMessageType *messageType, KzuMessageHandlerFunction handlerFunction, const void *userData)
 Removes a message handler. More...
 
KANZI_API kzsError kzuMessageDispatcherDispatchMessage (struct KzuMessageDispatcher *messageDispatcher, kanzi::MessageArguments *message, kanzi::Node *source)
 Dispatches a message. More...
 
KANZI_API kzsError kzuMessageDispatcherDispatchQueuedMessages (struct KzuMessageDispatcher *messageDispatcher, kzUint elapsedTime=0)
 Dispatches queued messages. More...
 
KANZI_API kzsError kzuMessageDispatcherNotifyObjectDeleted (const struct KzuMessageDispatcher *messageDispatcher, const kanzi::Node *objectNode)
 Notifies the message dispatcher that an object node is being destroyed. More...
 
KANZI_API kzsError kzuMessageDispatcherAddTimerHandler (KzuMessageDispatcher *messageDispatcher, kzUint interval, enum KzuTimerMessageMode mode, KzuMessageHandlerFunction handlerFunction, void *userData)
 Registers a timer handler. More...
 
KANZI_API kzsError kzuMessageDispatcherRemoveTimerHandler (KzuMessageDispatcher *messageDispatcher, KzuMessageHandlerFunction handlerFunction, const void *userData)
 Unregisters a timer handler. More...
 
KANZI_API kanzi::optional< kanzi::chrono::milliseconds > kzuMessageDispatcherGetProposedSleepTime (const KzuMessageDispatcher *messageDispatcher)
 Gets the proposed sleep time from message dispatcher. More...
 
KANZI_API kzUint kzuMessageDispatcherGetTime (const struct KzuMessageDispatcher *messageDispatcher)
 Returns current time of message dispatcher in milliseconds. More...
 
KANZI_API TimerSubscriptionToken kanzi::addTimerHandler (KzuMessageDispatcher *messageDispatcher, chrono::milliseconds interval, KzuTimerMessageMode mode, TimerFunction callback)
 
KANZI_API void kanzi::removeTimerHandler (KzuMessageDispatcher *messageDispatcher, TimerSubscriptionToken token)
 

Detailed Description

Message dispatcher.

Provides a system to exchange messages between different parts of an application. Messages can be used to notify of an event or request operations and data.

Copyright 2008-2017 by Rightware. All rights reserved.

Typedef Documentation

typedef kzsError(* KzuMessageHandlerFunction) (kanzi::MessageArguments *message, void *userData)

Message callback prototype.

typedef kzsError(* KzuMessageDispatchFunction) (const kanzi::MessageArguments *message, void *userData)

Application message callback prototype.

Enumeration Type Documentation

Timer mode.

Enumerator
KZU_TIMER_MESSAGE_MODE_ONCE 

Timer will be called once after the specified interval elapses.

Unsubscribe still needed.

KZU_TIMER_MESSAGE_MODE_REPEAT 

Timer will be called repeatedly at specified intervals.

Timers in this mode should be disabled when the application update cycle is called infrequently, for example in low power situations, as this generates excessive number of messages.

KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH 

Same as KZU_TIMER_MESSAGE_MODE_REPEAT, but the system dispatches only the last message when a timer has several pending messages.

Function Documentation

KANZI_API kzsError kzuMessageDispatcherCreate ( const struct KzcMemoryManager memoryManager,
struct KzuMessageDispatcher **  out_messageDispatcher 
)

Create a message dispatcher.

KANZI_API kzsError kzuMessageDispatcherDelete ( struct KzuMessageDispatcher messageDispatcher)

Destroy a message dispatcher.

KANZI_API kzsError kzuMessageDispatcherAddHandler ( const struct KzuMessageDispatcher messageDispatcher,
kanzi::Node subscriptionSiteNode,
const struct KzuMessageType messageType,
kanzi::Node messageSource,
KzuMessageHandlerFunction  handlerFunction,
void *  userData 
)

Adds a message handler.

Parameters
messageDispatcherThe message dispatcher to use.
subscriptionSiteNodeObject node that is associated with the message subscription created by this function.
messageTypeType of the message to match.
messageSourceSource of the message (as returned by kzuMessageGetSource) to match.
handlerFunctionFunction to call when a matching message appears.
userDataUser data pointer passed to handlerFunction.
KANZI_API kzsError kzuMessageDispatcherAddTunnellingHandler ( const struct KzuMessageDispatcher messageDispatcher,
kanzi::Node subscriptionSiteNode,
const struct KzuMessageType messageType,
kanzi::Node messageSource,
KzuMessageHandlerFunction  handlerFunction,
void *  userData 
)

Adds a message handler for tunneling phase.

KANZI_API kzsError kzuMessageDispatcherIsHandlerSubscriptionValid ( const struct KzuMessageDispatcher messageDispatcher,
const kanzi::Node subscriptionSiteNode,
const struct KzuMessageType messageType,
KzuMessageHandlerFunction  handlerFunction,
const void *  userData,
kzBool out_valid 
)

Checks if a handler subscription is valid.

KANZI_API kzsError kzuMessageDispatcherRemoveHandler ( const struct KzuMessageDispatcher messageDispatcher,
const kanzi::Node subscriptionSiteNode,
const struct KzuMessageType messageType,
KzuMessageHandlerFunction  handlerFunction,
const void *  userData 
)

Removes a message handler.

KANZI_API kzsError kzuMessageDispatcherDispatchMessage ( struct KzuMessageDispatcher messageDispatcher,
kanzi::MessageArguments message,
kanzi::Node source 
)

Dispatches a message.

The associated handlers are called immediately.

KANZI_API kzsError kzuMessageDispatcherDispatchQueuedMessages ( struct KzuMessageDispatcher messageDispatcher,
kzUint  elapsedTime = 0 
)

Dispatches queued messages.

Generally should be called once per frame.

KANZI_API kzsError kzuMessageDispatcherNotifyObjectDeleted ( const struct KzuMessageDispatcher messageDispatcher,
const kanzi::Node objectNode 
)

Notifies the message dispatcher that an object node is being destroyed.

This will cancel all messages where the specified node is the source of the message or the current site during routing.

KANZI_API kzsError kzuMessageDispatcherAddTimerHandler ( KzuMessageDispatcher messageDispatcher,
kzUint  interval,
enum KzuTimerMessageMode  mode,
KzuMessageHandlerFunction  handlerFunction,
void *  userData 
)

Registers a timer handler.

Parameters
messageDispatcherThe message dispatcher to use.
intervaltimeout in milliseconds in case of a one-shot timer, and the interval in case of a repeating timer.
modeKZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT or KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH. KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH is recommended for a repeating timer because it calls handlerFunction only once when the interval has been exceeded several times over.
handlerFunctionThe function to call when the timer expires.
userDataUser data pointer passed to handlerFunction.
KANZI_API kzsError kzuMessageDispatcherRemoveTimerHandler ( KzuMessageDispatcher messageDispatcher,
KzuMessageHandlerFunction  handlerFunction,
const void *  userData 
)

Unregisters a timer handler.

KANZI_API kanzi::optional<kanzi::chrono::milliseconds> kzuMessageDispatcherGetProposedSleepTime ( const KzuMessageDispatcher messageDispatcher)

Gets the proposed sleep time from message dispatcher.

This equals the smallest interval when a timer would be next executed. If no timers are present, returns an empty optional.

Parameters
messageDispatcherMessage dispatcher to query.
Returns
Time until next timer handler should trigger (always nonnegative). Empty optional if no timer handlers present.
KANZI_API kzUint kzuMessageDispatcherGetTime ( const struct KzuMessageDispatcher messageDispatcher)

Returns current time of message dispatcher in milliseconds.