Chapter 9 Additional Data Types and Functions

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>

• <am_notify.h>

• <am_string_set.h>

• <am_types.h>

• <am_utils.h>

<am.h>

<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.

---

Note –

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.

---

am_cleanup() Syntax

#include "am.h"
AM_EXPORT am_status_t
am_cleanup(void);

am_cleanup() Parameters

This function takes no parameters.

am_cleanup() 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 successfully cleaned up.

AM_NSPR_ERROR

Netscape Portable Runtime (NSPR) error.

AM_FAILURE

If any other error occurred.

<am_notify.h>

<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()).

am_notify() Syntax

#include "am_notify.h"
AM_EXPORT am_status_t 
am_notify(const char *xmlmsg, 
          am_policy_t policy_handle);

am_notify() Parameters

This function takes the following parameters:

xmlmsg

Pointer to the XML message containing the notification.

policy_handle

Reference to the policy evaluation object.

am_notify() 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 XML was successfully parsed and processed.

AM_INVALID_ARGUMENT

If any input parameter is invalid.

AM_ERROR_PARSING_XML

If an error occurred parsing the XML.

AM_ERROR_DISPATCH_LISTENER

If an error occurred dispatching the listener.

AM_FAILURE

If any other error occurred.

<am_string_set.h>

<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:

• String Data Types

• String Functions

String Data Types

The string data type defined in <am_string_set.h> is am_string_set_t. The type holds a set of strings.

Details

am_string_set_allocate() and am_string_set_destroy() are used to allocate and free space for this type.

Syntax

#include "am_string_set.h"
typedef struct {
    int size;
    char **strings;
} am_string_set_t;

Members

am_string_set_t has the following members:

size

Number of strings

strings

Pointer to a pointer to a list of strings.

String Functions

The string functions defined in <am_string_set.h> are:

• am_string_set_allocate()

• am_string_set_destroy()

am_string_set_allocate()

Allocates memory and initializes the string set size.

Syntax

#include "am_string_set.h"
AM_EXPORT am_string_set_t *
am_string_set_allocate(int size);

Parameters

This function takes the following parameter:

size

Number of strings in the set.

Returns

This function returns the allocated am_string_set_t, or NULL if size is less than zero.

am_string_set_destroy()

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.

Syntax

#include "am_string_set.h"
AM_EXPORT void 
am_string_set_destroy(am_string_set_t *string_set);

Parameters

This function takes the following parameter:

string_set

Pointer to the specified string set object.

Returns

This function returns no values.

<am_types.h>

<am_types.h> contains defined types and corresponding functions. They are:

• boolean_t

• bool_t

• am_status_t

• am_status_to_string()

boolean_t

Defines true or false boolean with the syntax:

#include "am_types.h"
typedef enum { 
    B_FALSE, 
    B_TRUE 
} boolean_t;

bool_t

Defines true or false boolean with the syntax:

#include "am_types.h"
typedef enum {
    AM_FALSE = 0,
    AM_TRUE
} am_bool_t;

am_status_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;

am_status_to_string()

Returns a message for the given error code.

Syntax

#include "am_types.h"
AM_EXPORT const char *am_status_to_string(am_status_t status);

Parameters

This function takes the following parameter:

status

Given error code

Returns

This function returns the appropriate message for the status code as a const char *

AM_SUCCESS

Success.

AM_FAILURE

Failure.

AM_INIT_FAILURE

Initialization failure.

AM_AUTH_FAILURE

Access Manager Authentication Service failure.

AM_NAMING_FAILURE

Access Manager Naming Service failure.

AM_SESSION_FAILURE

Access Manager Session Service failure.

AM_POLICY_FAILURE

Access Manager Policy Service failure.

AM_NO_POLICY

No policy found.

AM_INVALID_ARGUMENT

Invalid argument.

AM_INVALID_VALUE

Invalid value.

AM_NOT_FOUND

Access Manager not found.

AM_NO_MEMORY

No memory.

AM_NSPR_ERROR

NSPR error.

AM_END_OF_FILE

Reached end of file.

AM_BUFFER_TOO_SMALL

If the defined size of the buffer is smaller than the encoded value.

AM_NO_SUCH_SERVICE_TYPE

No such service type found.

AM_SERVICE_NOT_AVAILABLE

Service is not available.

AM_ERROR_PARSING_XML

Error found during XML parsing.

XML AM_INVALID_SESSION

Invalid session.

AM_END_OF_FILE

Reached end of file.

AM_INVALID_ACTION_TYPE

Invalid action type.

AM_ACCESS_DENIED

Access denied.

AM_HTTP_ERROR

HTTP error.

AM_INVALID_FQDN_ACCESS

Invalid fully qualified domain name (FQDN) access.

AM_FEATURE_UNSUPPORTED

The feature or configuration is unsupported.

AM_AUTH_CTX_INIT_FAILURE

Authentication context initialization failed.

AM_SERVICE_NOT_INITIALIZED

Specified service was not initialized.

AM_INVALID_RESOURCE_FORMAT

Specified resource name does not follow the format required by the service.

AM_NOTIF_NOT_ENABLED

Notification Service is not enabled or no notification URL is set.

AM_ERROR_DISPATCH_LISTENER

Error occurred dispatching single sign-on (SSO) listener.

AM_REMOTE_LOG_FAILURE

Remote Logging Service encountered an error.

AM_LOG_FAILURE

Log encountered an error.

AM_REMOTE_LOG_NOT_INITIALIZED

Remote Logging Service is not initialized.

<am_utils.h>

<am_utils.h> contains functions to encode and decode cookies. The functions are:

• am_http_cookie_encode()

• am_http_cookie_decode()

am_http_cookie_encode()

Encodes an HTTP cookie.

Syntax

#include "am.h"
AM_EXPORT am_status_t
am_http_cookie_encode(const char *cookie, 
                      char *buf, 
                      int len);

Parameters

This function takes the following parameters:

cookie

Pointer to the cookie.

buf

Pointer to the buffer where the encoded cookie will be stored.

len

The size of the buffer.

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 cookie was successfully encoded and stored.

AM_INVALID_ARGUMENT

If the cookie or buffer is NULL..

AM_BUFFER_TOO_SMALL

If the defined size is smaller than the encoded value.

AM_FAILURE

If any other error occurred.

am_http_cookie_decode()

Decodes an HTTP cookie.

Syntax

#include "am.h"
AM_EXPORT am_status_t
am_http_cookie_decode(const char *cookie, 
                      char *buf, 
                      int len);

Parameters

This function takes the following parameters:

cookie

Pointer to the cookie.

buf

Pointer to the buffer where the encoded cookie will be stored.

len

The size of the buffer.

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 cookie was successfully decoded and coped.

AM_INVALID_ARGUMENT

If the cookie or buffer is NULL..

AM_BUFFER_TOO_SMALL

If the defined size is smaller than the decoded value.

AM_FAILURE

If any other error occurred.