am_sso_add_listener()

Adds a listener for the any SSO token’s change events.

Syntax

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

Parameters

This function takes the following parameters:

listener

The token change event listener.

args

Arguments to pass to the listener.

dispatch_to_sep_thread

Call 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 functions to finish before returning.

Returns

This function returns am_status_t with one of the following values:

AM_SUCCESS

If the listener was successfully added.

AM_INVALID_ARGUMENT

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

AM_NOTIF_NOT_ENABLED

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

AM_FAILURE

If any other error occurred.

Details

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 added the listener will be called for any and all session event change notification. It will not be removed after it is called once like am_sso_add_sso_token_listener .