am_sso_add_sso_token_listener()

Adds a listener for any and all event changes related to the referenced single sign-on token handle.

am_sso_add_sso_token_listener() is removed from memory after it is called once, differentiating its functionality from am_sso_add_listener().

Details

The caller must do one of the following:

• Provide a URL to this function.

• Enable notification and provider a valid notification URL in the AMAgent.properties file passed to am_sso_init().

See Listening and Notification for more information.

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

Pointer to the session information object containing the session token to which the listener corresponds. The handle will be filled with the session information from the notification message, overwriting any existing contents.

---

Note –

The session token is a randomly-generated string that represents an authenticated user.

---

listener

The listener as described in am_sso_token_listener_func_t.

---

Note –

When the listener is called, updated session information from Access Manager is passed in a temporary sso_token_handle.

---

args

Arguments to pass to the listener.

dispatch_to_sep_thread

Takes one of the values based on the boolean_t (defined in the <am_types.h> header file) that indicates whether the listener function should be called in the calling thread or dispatched to a thread from the internal thread pool managed by the C SDK.

---

Note –

Calling the listener in a thread from an internal thread pool 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 one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the listener was successfully added.

AM_INVALID_ARGUMENT

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

AM_NOTIF_NOT_ENABLED

If notification is not enabled and the notification URL parameter is invalid.

AM_FAILURE

If any other error occurred.