dispatch_handler()

Arguments:

ctp

A pointer to a dispatch_context_t structure that was allocated by dispatch_context_alloc().

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The dispatch_handler() function handles events received by dispatch_block() and does one of the following:

• It calls the message subsystem. A search is made (based upon the message type or pulse code) for a matching function (that was attached with message_attach() or pulse_attach()). If a match is found, the attached function is called.
• If the message type is in the range handled by the resource manager (e.g., I/O messages) and pathnames were attached using resmgr_attach(), then the resmgr subsystem is called and handles the resource manager messages.
• If a pulse is received, it may be dispatched to the resmgr subsystem if it's one of the codes (unblock and disconnect pulses) handled by the resource manager. If a select_attach() was done and the pulse matches the one used by select_attach(), then the select subsystem is called and dispatches that event.
• If a message is received, and no matching handler is found for that message type, MsgError() returns ENOSYS to the sender.

This function is part of the dispatch layer of a resource manager. For more information, see Layers in a resource manager in the Bones of a Resource Manager chapter of Writing a Resource Manager.

Returns:

0

Success.

-1

One of the following occurred:

• The ctp was NULL.
• The rcvid in the ctp was -1 and no timeout handler was found.
• The message length was less than 2 bytes. A 2-byte message type is required at the beginning of the message so that a handler function can be found or identified. When there's no 2-byte message type, MsgError() is called to return EINVAL to the client.
• No matching handler was found for the message or pulse received. In this case, MsgError() is called to return ENOSYS to the client.
• A handler was found for the message, but the handler determined that there was a problem.

Examples:

#include <stdlib.h>
#include <sys/dispatch.h>

int main( int argc, char **argv ) {
   dispatch_context_t   *ctp;
   …

   for(;;) {
     if( dispatch_block( ctp ) ) {
       dispatch_handler( ctp );
     }
   }
   return EXIT_SUCCESS;
}

For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().

Classification:

QNX OS

Caveats:

This function might or might not be a cancellation point, depending on the implementation of the handler.