NetIDMgr Message Queue


Detailed Description

The Network Identity Manager Message Queue handles all the messaging within the application and all loaded plug-ins.

For information about the messaging system and how it is used, please see Messages and Message Queues .


Modules

 Message Types

Data Structures

struct  tag_kmq_response
 A single response. More...
struct  tag_kmq_message
 A single message. More...

Defines

#define KMQ_WM_DISPATCH   (WM_APP+0x100)
 Window message for kmq.

Typedefs

typedef DWORD kmq_thread_id
typedef DWORD kmq_timer
typedef khm_int32(KHMAPI *) kmq_callback_t (khm_int32 msg_type, khm_int32 msg_sub_type, khm_ui_4 uparam, void *vparam)
 A message callback.
typedef tag_kmq_response kmq_response
 A single response.
typedef tag_kmq_message kmq_message
 A single message.
typedef kmq_messagekmq_call
 A handle to a call.
typedef void(KHMAPI *) kmq_msg_completion_handler (kmq_message *)
 A completion handler for a message.

Functions

KHMEXP khm_int32 KHMAPI kmq_register_type (wchar_t *name, khm_int32 *new_id)
 Register a message type.
KHMEXP khm_int32 KHMAPI kmq_find_type (wchar_t *name, khm_int32 *id)
 Find a message type.
KHMEXP khm_int32 KHMAPI kmq_unregister_type (khm_int32 id)
 Unregister a message type.
KHMEXP khm_int32 KHMAPI kmq_subscribe (khm_int32 type, kmq_callback_t cb)
 Subscribte to a message type.
KHMEXP khm_int32 KHMAPI kmq_subscribe_hwnd (khm_int32 type, HWND hwnd)
 Subscribe a window to a message type.
KHMEXP LRESULT KHMAPI kmq_wm_begin (LPARAM lparm, kmq_message **m)
 Begins handling a KMQ_WM_DISPATCH message.
KHMEXP LRESULT KHMAPI kmq_wm_end (kmq_message *m, khm_int32 rv)
 Ends handling a KMQ_WM_DISPATCH message.
KHMEXP LRESULT KHMAPI kmq_wm_dispatch (LPARAM lparm, kmq_callback_t cb)
 Dispatches a KMQ_WM_DISPATCH message to a callback.
KHMEXP khm_int32 KHMAPI kmq_unsubscribe (khm_int32 type, kmq_callback_t cb)
 Unsubscribe a callback from a message type.
KHMEXP khm_int32 KHMAPI kmq_unsubscribe_hwnd (khm_int32 type, HWND hwnd)
 Unsubscribe a window from a message type.
KHMEXP khm_int32 KHMAPI kmq_create_subscription (kmq_callback_t cb, khm_handle *result)
 Create an ad-hoc subscription.
KHMEXP khm_int32 KHMAPI kmq_create_hwnd_subscription (HWND hw, khm_handle *result)
 Create an ad-hoc subscription for a window.
KHMEXP khm_int32 KHMAPI kmq_delete_subscription (khm_handle sub)
 Delete an ad-hoc subscription.
KHMEXP khm_int32 KHMAPI kmq_post_sub_msg (khm_handle sub, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
 Post a message to a subscription.
KHMEXP khm_int32 KHMAPI kmq_post_sub_msg_ex (khm_handle sub, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam, kmq_call *call)
 Post a message to a subscription and acquire a handle to the call.
KHMEXP khm_int32 KHMAPI kmq_send_sub_msg (khm_handle sub, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
 Send a synchronous message to a subscription.
KHMEXP khm_int32 KHMAPI kmq_post_subs_msg (khm_handle *subs, khm_size n_subs, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
 Post a message to a group of subscriptions.
KHMEXP khm_int32 KHMAPI kmq_post_subs_msg_ex (khm_handle *subs, khm_int32 n_subs, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam, kmq_call *call)
 Post a message to a group of subscriptions and acquire a handle to the call.
KHMEXP khm_int32 KHMAPI kmq_send_subs_msg (khm_handle *subs, khm_int32 n_subs, khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *vparam)
 Send a synchronous message to a group of subscriptions.
KHMEXP khm_int32 KHMAPI kmq_dispatch (kmq_timer timeout)
 Dispatch a message for the current thread.
KHMEXP khm_int32 KHMAPI kmq_send_message (khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *blob)
 Send a message.
KHMEXP khm_int32 KHMAPI kmq_post_message (khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *blob)
 Post a message.
KHMEXP khm_int32 KHMAPI kmq_post_message_ex (khm_int32 type, khm_int32 subtype, khm_ui_4 uparam, void *blob, kmq_call *call)
 Post a message and acquire a handle to the call.
KHMEXP khm_int32 KHMAPI kmq_free_call (kmq_call call)
 Free a handle to a call obtained through kmq_post_message_ex().
KHMEXP khm_int32 KHMAPI kmq_send_thread_quit_message (kmq_thread_id thread, khm_ui_4 uparam)
 Sends a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.
KHMEXP khm_int32 KHMAPI kmq_post_thread_quit_message (kmq_thread_id thread, khm_ui_4 uparam, kmq_call *call)
 Post a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.
KHMEXP khm_int32 KHMAPI kmq_get_next_response (kmq_call call, void **resp)
KHMEXP khm_boolean KHMAPI kmq_has_completed (kmq_call call)
 Check if a specific call has completed.
KHMEXP khm_int32 KHMAPI kmq_wait (kmq_call call, kmq_timer timeout)
 Wait for a call to complete.
KHMEXP khm_int32 KHMAPI kmq_abort_call (kmq_call call)
 Abort a call.
KHMEXP khm_boolean KHMAPI kmq_is_call_aborted (void)
 Check if the last dispatched message was aborted.
KHMEXP khm_int32 KHMAPI kmq_set_completion_handler (khm_int32 type, kmq_msg_completion_handler hander)
 Sets the completion handler for a specified message type.


Define Documentation

#define KMQ_WM_DISPATCH   (WM_APP+0x100)

Window message for kmq.

This message is sent to the window procedure of a window if that window is a subscriber to KMQ messages.

See also:
kmq_subscribe_hwnd() for more information about handling this window message


Typedef Documentation

typedef khm_int32(KHMAPI *) kmq_callback_t(khm_int32 msg_type, khm_int32 msg_sub_type, khm_ui_4 uparam, void *vparam)

A message callback.

Should return TRUE if the message is properly handled. Otherwise return FALSE

typedef void(KHMAPI *) kmq_msg_completion_handler(kmq_message *)

A completion handler for a message.

Each message type can have a completion handler. Once a message of this a specific type has been broadcast and handled by all the subscripbers, the message will be passed down to the completion handler before the associated data structures are freed. This allows applications that define message type to also define clean up for each message. For example, the completion handler can initiate another message if the messages form a sequence or free up blocks of memory that was passed as the parameter to the message.

typedef struct tag_kmq_response kmq_response

A single response.

Certain broadcast messages may user scatter-gather type notification and result gathering. Individual subscribers to a message attach their individual responses to a kmq_response object and attach that to the message which can later be read by the sender of the message.


Function Documentation

KHMEXP khm_int32 KHMAPI kmq_abort_call ( kmq_call  call  ) 

Abort a call.

Abort a pending call. The call handle should have been obtained using a prior call to kmq_post_message_ex().

Note that this function may not abort the call immediately. It merely marks the message as being in an aborted state. It is upto the individual handlers of the message to check if the message has been aborted and act accordingly.

The handlers are expected to call kmq_is_call_aborted() periodicially during the processing of specially lengthy operations during the course of handling a message. That function will return TRUE if the last dispatched message is now in an aborted state. In which case, the handler is expected to abort handling the message and return control to the dispatcher.

KHMEXP khm_int32 KHMAPI kmq_create_hwnd_subscription ( HWND  hw,
khm_handle result 
)

Create an ad-hoc subscription for a window.

An ad-hoc subscription describes a window that will be dispatched messages individually without broadcasting.

See also:
kmq_post_sub_msg(), kmq_post_sub_msg_ex(), kmq_send_sub_msg(), kmq_post_subs_msg(), kmq_post_subs_msg_ex(), kmq_send_subs_msg(), kmq_delete_subscription()

KHMEXP khm_int32 KHMAPI kmq_create_subscription ( kmq_callback_t  cb,
khm_handle result 
)

Create an ad-hoc subscription.

An ad-hoc subscription describes a callback point in a thread that can be dispatched messages to individually without broadcasting.

See also:
kmq_post_sub_msg(), kmq_post_sub_msg_ex(), kmq_send_sub_msg(), kmq_post_subs_msg(), kmq_post_subs_msg_ex(), kmq_send_subs_msg(), kmq_delete_subscription()

KHMEXP khm_int32 KHMAPI kmq_delete_subscription ( khm_handle  sub  ) 

Delete an ad-hoc subscription.

Deletes a subscriptoin that was created using kmq_create_subscription()

KHMEXP khm_int32 KHMAPI kmq_dispatch ( kmq_timer  timeout  ) 

Dispatch a message for the current thread.

This function opens the message list for the current thread and dispatches the first message instance that is found. Note that if multiple callbacks subscribe to the same message type in the same thread, then when a message of that type is received, multiple message instances are added to the message queue corresponding to each subscription.

If no message instances are waiting in the queue, kmq_dispatch() waits for the timeout period for a message.

Parameters:
[in] timeout The timeout period in milliseconds. Specify INFINITE for kmq_dispatch() to wait indefinitely.
Return values:
KHM_ERROR_SUCCESS A message instance was dispatched
KHM_ERROR_TIMEOUT The timeout period elapsed
KHM_ERROR_EXIT The message found on the queue was <KMSG_SYSTEM,KMSG_SYSTEM_EXIT>

KHMEXP khm_int32 KHMAPI kmq_find_type ( wchar_t *  name,
khm_int32 id 
)

Find a message type.

Find the message type with the given name. If found, the type ID is returned in id.

Return values:
KHM_ERROR_SUCCESS A message type with the given name was found.
KHM_ERROR_NOT_FOUND A message type with the given name was not found.

KHMEXP khm_int32 KHMAPI kmq_free_call ( kmq_call  call  ) 

Free a handle to a call obtained through kmq_post_message_ex().

All call handles obtained through kmq_post_message_ex() must be freed via a call to kmq_free_call().

KHMEXP khm_boolean KHMAPI kmq_has_completed ( kmq_call  call  ) 

Check if a specific call has completed.

Returns:
TRUE if the call has completed. FALSE otherwise.

KHMEXP khm_boolean KHMAPI kmq_is_call_aborted ( void   ) 

Check if the last dispatched message was aborted.

The sender of a message may abort it using a call to kmq_abort_call(). This function checks if the last dispatched message was aborted.

A handler of a message is expected to call this function periodically if handling the message is going to take a specially long time (e.g. more than 5 or 10 seconds). If the message is found to be aborted, the handler is expected to abort handling the message, perform any necessary cleanup and return control to the dispatcher.

Doing this allows operations like new credentials acquisition to be cleanly aborted by the user if she so wishes. Otherwise, Network Identity Manager has to wait for the message to complete processing since it has no means of cleanly terminating an executing plug-in thread.

KHMEXP khm_int32 KHMAPI kmq_post_message ( khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  blob 
)

Post a message.

The specified message will be posted to all the subscribers of the message type. The function returns immediately.

If you want to be able to wait for all the subscribers to finish processing the message, you should use kmq_post_message_ex() instead.

Parameters:
[in] type The type of the message
[in] subtype The subtype
[in] uparam The khm_ui_4 parameter for the message
[in] blob The parameter blob for the message

KHMEXP khm_int32 KHMAPI kmq_post_message_ex ( khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  blob,
kmq_call call 
)

Post a message and acquire a handle to the call.

The specified message is posted to all the subscribers. In addition, a handle is obtained for the call which can be used in subsequent call to kmq_free_call() or kmq_wait().

Call kmq_free_call() to free the handle.

Parameters:
[in] type The type of the message
[in] subtype The subtype
[in] uparam The khm_ui_4 parameter for the message
[in] blob The parameter blob for the message
[out] call Receives the call handle. Set to NULL if the call handle is not required.
See also:
kmq_free_call()

KHMEXP khm_int32 KHMAPI kmq_post_sub_msg ( khm_handle  sub,
khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  vparam 
)

Post a message to a subscription.

Equivalent of kmq_post_msg() but only posts the message to the specified subscription.

KHMEXP khm_int32 KHMAPI kmq_post_subs_msg ( khm_handle subs,
khm_size  n_subs,
khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  vparam 
)

Post a message to a group of subscriptions.

The block of memory pointed to by subs should be an array of subscriptions. The number of elements in that array should be n_subs. A message as specified by the remaining parameters will be dispatched to all of the subscription points in the array.

KHMEXP khm_int32 KHMAPI kmq_post_subs_msg_ex ( khm_handle subs,
khm_int32  n_subs,
khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  vparam,
kmq_call call 
)

Post a message to a group of subscriptions and acquire a handle to the call.

The block of memory pointed to by subs should be an array of subscriptions. The number of elements in that array should be n_subs. A message as specified by the remaining parameters will be dispatched to all of the subscription points in the array, and a handle to the call will be returned in call.

The returned call will reference all of the dispatches that were made.

KHMEXP khm_int32 KHMAPI kmq_post_thread_quit_message ( kmq_thread_id  thread,
khm_ui_4  uparam,
kmq_call call 
)

Post a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.

The message itself will not be received by any callback function, however, any kmq_dispatch() function that is currently active of becomes active will exit with a KHM_ERROR_EXIT code. kmq_post_thread_quit_message() will return immediately.

KHMEXP khm_int32 KHMAPI kmq_register_type ( wchar_t *  name,
khm_int32 new_id 
)

Register a message type.

Registers a custom message type. The name parameter specifies a language independent name for the message type and must be unique and must be less than KMQ_MAXCCH_TYPE_NAME characters.

Parameters:
[in] name Name of the message type. Upto KMQ_MAXCCH_TYPE_NAME characters including terminating NULL. The name cannot be a zero length string.
[out] new_id Receives the new message type ID. Specify NULL if the new message type is not required.
See also:
kmq_find_type() and kmq_unregister_type()
Return values:
KHM_ERROR_INVALID_PARAM The name parameter was invalid.
KHM_ERROR_EXISTS A message type with that name already exists.
KHM_ERROR_NO_RESOURCES Can't register any more message types.
KHM_ERROR_SUCCESS The operation succeeded.

KHMEXP khm_int32 KHMAPI kmq_send_message ( khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  blob 
)

Send a message.

The specified message will be posted to all the subscribers of the message type. Then the function will wait for all the subscribers to finish processing the message before returning.

Parameters:
[in] type The type of the message
[in] subtype The subtype
[in] uparam The khm_ui_4 parameter for the message
[in] blob The parameter blob for the message
Note:
The internal timeout for this function is INFINITE. If you it is desirable to use a different timeout, use kmq_post_message_ex() and kmq_wait() functions.
Return values:
KHM_ERROR_SUCCESS The call succeeded and no subscribers returned errors
KHM_ERROR_PARTIAL The call succeeded but at least one subscriber returned an error

KHMEXP khm_int32 KHMAPI kmq_send_sub_msg ( khm_handle  sub,
khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  vparam 
)

Send a synchronous message to a subscription.

Return values:
KHM_ERROR_SUCCESS The call succeeded, and no subscribers reported errors
KHM_ERROR_PARTIAL The call succeeded, but at least one subscriber reported errors

KHMEXP khm_int32 KHMAPI kmq_send_subs_msg ( khm_handle subs,
khm_int32  n_subs,
khm_int32  type,
khm_int32  subtype,
khm_ui_4  uparam,
void *  vparam 
)

Send a synchronous message to a group of subscriptions.

The block of memory pointed to by subs should be an array of subscriptions. The number of elements in that array should be n_subs. A message as specified by the remaining parameters will be dispatched to all of the subscription points in the array. The function will not return until all of the calls have succeeded.

Return values:
KHM_ERROR_SUCCESS The call succeeded, and no subscribers reported errors
KHM_ERROR_PARTIAL The call succeeded, but at least one subscriber reported errors

KHMEXP khm_int32 KHMAPI kmq_send_thread_quit_message ( kmq_thread_id  thread,
khm_ui_4  uparam 
)

Sends a <KMSG_SYSTEM,KMSG_SYSTEM_EXIT> message to the specified thread.

The message itself will not be received by any callback function, however, any kmq_dispatch() function that is currently active of becomes active will exit with a KHM_ERROR_EXIT code. kmq_send_thread_quit_message() will wait for this to happen before returning.

KHMEXP khm_int32 KHMAPI kmq_set_completion_handler ( khm_int32  type,
kmq_msg_completion_handler  hander 
)

Sets the completion handler for a specified message type.

Note:
Only one completion handler can exist for one message type. Calling this function overwrites the previous completion handler.

KHMEXP khm_int32 KHMAPI kmq_subscribe ( khm_int32  type,
kmq_callback_t  cb 
)

Subscribte to a message type.

Adds a subscription to messages of type type. Subscriptions are managed per thread. Therefore the subscription is actually added to the subscription list for the current thread (the thread which calls kmq_subscribe()).

When a message of type type is received by the thread, it is dispatched to the callback function identified by cb within the context of this thread.

Note:
Calling kmq_subscribe() from within multiple threads with the same type and cb will result in multiple subscriptions.
See also:
kmq_unsubscribe()

kmq_dispatch()

KHMEXP khm_int32 KHMAPI kmq_subscribe_hwnd ( khm_int32  type,
HWND  hwnd 
)

Subscribe a window to a message type.

Adds the window specified by hwnd to the subscription list for the message type type. When a message of this type is posted, then the window procedure of the window hwnd receives a message KMQ_WM_DISPATCH.

When a window receives a KMQ_WM_DISPATCH message, it means that a message has been posted which is of a type that the window has subscribed for. Because of the way Windows handles window messages and the way NetIDMgr message queues work, a thread which has a window (or thread) procedure can not call kmq_dispatch() to handle these messages. For threads that have window or thread message loops, they must call kmq_subscribe_hwnd() to subscribe a particular window (for thread message loops, this would be the HWND of the message window for the thread) to NetIDMgr messages.

There are two supported ways of handling the KMQ_WM_DISPATCH message. Examples of both are provided below.

Handling the message inline:

    LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    kmq_message * m;
    khm_int32 rv;
    ...
    switch(uMsg) {
    case WM_CREATE:
       ...
       kmq_subscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    case WM_DESTROY:
       ...
       kmq_unsubscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    ...
    case KMQ_WM_DISPATCH:
        kmq_wm_begin(lParam,&m);

    if(m->type == KMSG_CRED && m->subtype == KMSG_CRED_ROOTDELTA) {
    // do something
        rv = KHM_ERROR_SUCCESS;
    }

    return kmq_wm_end(m, rv);
    ...
    };
    ...
    }

The other method is to dispatch the KMQ_WM_DISPATCH message to a secondary callback function:

    khm_int32 msg_handler(khm_int32 t, khm_int32 st, khm_ui_4 up, void * pb) {
        khm_int32 rv = KHM_ERROR_SUCCESS;

        //handle message

    return rv;
    }

    LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    kmq_message * m;
    khm_int32 rv;
    ...
    switch(uMsg) {
    ...

    case WM_CREATE:
       ...
       kmq_subscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    case WM_DESTROY:
       ...
       kmq_unsubscribe_hwnd(KMSG_CRED, hwnd);
       ...
       break;

    ...
    case KMQ_WM_DISPATCH:
        return kmq_wm_dispatch(lParam, msg_handler);
    ...
    };
    ...
    }

Note:
Make sure you unsubscribe from the message type when the window is destroyed.
See also:
kmq_unsubscribe_hwnd()

kmq_wm_begin()

kmq_wm_end()

kmq_wm_dispatch()

KHMEXP khm_int32 KHMAPI kmq_unregister_type ( khm_int32  id  ) 

Unregister a message type.

Unregisters a message type that was registered using kmq_register_type().

Return values:
KHM_ERROR_SUCCESS The specified message type was successfully unregistered.
KHM_ERROR_NOT_FOUND The message type was not found.

KHMEXP khm_int32 KHMAPI kmq_unsubscribe ( khm_int32  type,
kmq_callback_t  cb 
)

Unsubscribe a callback from a message type.

Removes the subscription for message type type for callback function cb from the subscription list for the current thread (the thread that calls kmq_unsubscribe()).

Note:
kmq_unsubscribe() can only remove subscriptions for the subscription list for the current thread.
See also:
kmq_subscribe()

kmq_dispatch()

KHMEXP khm_int32 KHMAPI kmq_unsubscribe_hwnd ( khm_int32  type,
HWND  hwnd 
)

Unsubscribe a window from a message type.

Removes the specific window from the subsription list for message type type.

See also:
kmq_subscribe_hwnd()

KHMEXP khm_int32 KHMAPI kmq_wait ( kmq_call  call,
kmq_timer  timeout 
)

Wait for a call to complete.

Waits for the specified call to complete. If the call dispatched to multiple recipients, the function waits for all dispatches to complete.

If the call has already completed, then the function returns immediately.

If more than one thread is waiting for a single message to complete, then only one of them will be released when the message compeltes. Each subsequent thread will be released as each released thread calls kmq_free_call().

Parameters:
[in] call A handle to a call.
[in] timeout Specifies, in milliseconds, the amount of time to wait for the call to complete. Specify INFINITE to wait indefinitely.
Return values:
KHM_ERROR_SUCCESS The call completed
KHM_ERROR_TIMEOUT The timeout period expired
KHM_ERROR_INVALID_PARAM One of the parameters were invalid.

KHMEXP LRESULT KHMAPI kmq_wm_begin ( LPARAM  lparm,
kmq_message **  m 
)

Begins handling a KMQ_WM_DISPATCH message.

Returns:
The return value of this function should be ignored.
See also:
kmq_subscribe_hwnd() for more details about handling KMQ_WM_DISPATCH

KHMEXP LRESULT KHMAPI kmq_wm_dispatch ( LPARAM  lparm,
kmq_callback_t  cb 
)

Dispatches a KMQ_WM_DISPATCH message to a callback.

Returns:
The return value of this function should be the return value of the window procedure. See kmq_subscribe_hwnd() documentation for example.
See also:
kmq_subscribe_hwnd() for more details about handling KMQ_WM_DISPATCH

KHMEXP LRESULT KHMAPI kmq_wm_end ( kmq_message m,
khm_int32  rv 
)

Ends handling a KMQ_WM_DISPATCH message.

Returns:
The return value of this function should be the return value of the window procedure. See kmq_subscribe_hwnd() documentation for example
See also:
kmq_subscribe_hwnd() for more details about handling KMQ_WM_DISPATCH


Generated on Fri Aug 3 08:27:14 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu