am_sso_add_sso_token_listener()

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

Syntax

#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);

Parameters

This function takes the following parameters:

sso_token_handle

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.

listener

The token change event listener.

args

Arguments to pass to the listener.

dispatch_to_sep_thread

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.

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 URL 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 a listener has been called it is removed from memory; a listener is called only once.