This chapter provides information and a reference guide to the data types and functions not documented elsewhere. This includes those described in the <am.h>, <am_notify.h>, <am_string_set.h>, <am_types.h>, and <am_util.h> header files. Reference summaries include a short description, syntax, parameters and returns. This chapter contains the following sections:
<am.h> contains the am_cleanup() function which cleans up all internal data structures created by am_sso_init(), am_auth_init(), or am_policy_init(). It needs to be called only once at the end of any calls. After cleanup, the relevant initialize function must be called again before using any of its interfaces.
Any properties passed to the initialization functions am_sso_init(), am_auth_init(), or am_policy_init() should be destroyed only after am_cleanup() is called.
#include "am.h" AM_EXPORT am_status_t am_cleanup(void);
This function takes no parameters.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If successfully cleaned up.
Netscape Portable Runtime (NSPR) error.
If any other error occurred.
<am_notify.h> contains the am_notify() function which parses and processes a session or policy notification message as an XML string. If the message is a session notification, any token handle listeners registered using am_sso_add_listener() will be called. If the message is a policy notification, the internal policy cache maintained by the policy module in the C SDK will be updated with the notification information only if the policy module has been initialized (using am_policy_init() and am_policy_service_init()).
#include "am_notify.h" AM_EXPORT am_status_t am_notify(const char *xmlmsg, am_policy_t policy_handle);
This function takes the following parameters:
Pointer to the XML message containing the notification.
Reference to the policy evaluation object.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the XML was successfully parsed and processed.
If any input parameter is invalid.
If an error occurred parsing the XML.
If an error occurred dispatching the listener.
If any other error occurred.
<am_string_set.h> contains public data types and functions intended to manipulate strings. The sample sources (located in the /AccessManager-base/SUNWam/samples/csdk directory) demonstrate basic usage of the string set API. This chapter contains the following sections:
The string data type defined in <am_string_set.h> is am_string_set_t. The type holds a set of strings.
am_string_set_allocate() and am_string_set_destroy() are used to allocate and free space for this type.
#include "am_string_set.h" typedef struct { int size; char **strings; } am_string_set_t;
am_string_set_t has the following members:
Number of strings
Pointer to a pointer to a list of strings.
The string functions defined in <am_string_set.h> are:
Allocates memory and initializes the string set size.
#include "am_string_set.h" AM_EXPORT am_string_set_t * am_string_set_allocate(int size);
This function takes the following parameter:
Number of strings in the set.
This function returns the allocated am_string_set_t, or NULL if size is less than zero.
Releases memory in the specified string set object by freeing each string in the set, then freeing the associated pointers, and finally, the structure itself.
#include "am_string_set.h" AM_EXPORT void am_string_set_destroy(am_string_set_t *string_set);
This function takes the following parameter:
Pointer to the specified string set object.
This function returns no values.
<am_types.h> contains defined types and corresponding functions. They are:
Defines true or false boolean with the syntax:
#include "am_types.h" typedef enum { B_FALSE, B_TRUE } boolean_t;
Defines true or false boolean with the syntax:
#include "am_types.h" typedef enum { AM_FALSE = 0, AM_TRUE } am_bool_t;
Defines error codes with the syntax:
#include "am_types.h" typedef enum { AM_SUCCESS = 0, AM_FAILURE, AM_INIT_FAILURE, AM_AUTH_FAILURE, AM_NAMING_FAILURE, AM_SESSION_FAILURE, AM_POLICY_FAILURE, AM_NO_POLICY, AM_INVALID_ARGUMENT, AM_INVALID_VALUE, AM_NOT_FOUND, AM_NO_MEMORY, AM_NSPR_ERROR, AM_END_OF_FILE, AM_BUFFER_TOO_SMALL, AM_NO_SUCH_SERVICE_TYPE, AM_SERVICE_NOT_AVAILABLE, AM_ERROR_PARSING_XML, AM_INVALID_SESSION, AM_INVALID_ACTION_TYPE, AM_ACCESS_DENIED, AM_HTTP_ERROR, AM_INVALID_FQDN_ACCESS, AM_FEATURE_UNSUPPORTED, AM_AUTH_CTX_INIT_FAILURE, AM_SERVICE_NOT_INITIALIZED, AM_INVALID_RESOURCE_FORMAT, AM_NOTIF_NOT_ENABLED, AM_ERROR_DISPATCH_LISTENER, AM_REMOTE_LOG_FAILURE, AM_LOG_FAILURE, AM_REMOTE_LOG_NOT_INITIALIZED, AM_NUM_ERROR_CODES /* This should always be the last. */ } am_status_t;
Returns a message for the given error code.
#include "am_types.h" AM_EXPORT const char *am_status_to_string(am_status_t status);
This function takes the following parameter:
Given error code
This function returns the appropriate message for the status code as a const char *
Success.
Failure.
Initialization failure.
Access Manager Authentication Service failure.
Access Manager Naming Service failure.
Access Manager Session Service failure.
Access Manager Policy Service failure.
No policy found.
Invalid argument.
Invalid value.
Access Manager not found.
No memory.
NSPR error.
Reached end of file.
If the defined size of the buffer is smaller than the encoded value.
No such service type found.
Service is not available.
Error found during XML parsing.
Invalid session.
Reached end of file.
Invalid action type.
Access denied.
HTTP error.
Invalid fully qualified domain name (FQDN) access.
The feature or configuration is unsupported.
Authentication context initialization failed.
Specified service was not initialized.
Specified resource name does not follow the format required by the service.
Notification Service is not enabled or no notification URL is set.
Error occurred dispatching single sign-on (SSO) listener.
Remote Logging Service encountered an error.
Log encountered an error.
Remote Logging Service is not initialized.
<am_utils.h> contains functions to encode and decode cookies. The functions are:
Encodes an HTTP cookie.
#include "am.h" AM_EXPORT am_status_t am_http_cookie_encode(const char *cookie, char *buf, int len);
This function takes the following parameters:
Pointer to the cookie.
Pointer to the buffer where the encoded cookie will be stored.
The size of the buffer.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the cookie was successfully encoded and stored.
If the cookie or buffer is NULL..
If the defined size is smaller than the encoded value.
If any other error occurred.
Decodes an HTTP cookie.
#include "am.h" AM_EXPORT am_status_t am_http_cookie_decode(const char *cookie, char *buf, int len);
This function takes the following parameters:
Pointer to the cookie.
Pointer to the buffer where the encoded cookie will be stored.
The size of the buffer.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the cookie was successfully decoded and coped.
If the cookie or buffer is NULL..
If the defined size is smaller than the decoded value.
If any other error occurred.