Sun Java System Access Manager 7 2005Q4 C API Reference


Adds an SSO token listener for the SSO token’s change events.


#include "am_sso.h"
AM_EXPORT am_status_t
am_sso_add_sso_token_listener(am_sso_token_handle_t sso_token_handle,
                                const am_sso_token_listener_func_t listener,
                                void  *args,
                                boolean_t dispatch_to_sep_thread);


This function takes the following parameters:


The session handle containing the SSO token id to listen for. The handle will be filled with the session information from the notification message. Any existing contents will be overwritten.


The token change event listener.


Arguments to pass to the listener.


Calls the listener in a separate thread from an internal thread pool. This allows am_notify to return immediately upon parsing the notification message rather than waiting for the listener function(s) to finish before returning.


This function returns am_status_t with one of the following values:


If the listener was successfully added.


If sso_token_handle or listener is invalid, or if notification_url is not set and no notification URL is provided in the properties file.


If notification is not enabled and the notification_url input parameter is invalid.


If any other error occurred.


Caller must either provide a URL to this function or have notification enabled with a valid notification URL in the properties file used to initialize SSO in am_sso_init(). The URL must point to a HTTP host and port that listens for notification messages from the server.

Notification messages are in XML. XML Notification messages received from the server should be passed to as a string (const char *) to am_notify(), which will parse the message and invoke listeners accordingly.

See the C API samples for more information.

When the listener is called, the sso_token_handle that is passed to the listener is a temporary one containing the updated session information from the server. Note that it is not the original sso_token_handle passed to am_sso_add_sso_token_listener().

Once a listener has been called it is removed from memory; a listener is called only once.