Chapter 10 Miscellaneous Functions

This chapter provides a reference to various Sun Java^TM System Access Manager functions that do not belong in other collections. Function summaries include a short description, syntax, parameters and returns, and header file.

The following functions are included in this chapter:

• am_cleanup()

• am_notify()

• am_string_set_allocate()

• am_string_set_destroy()

• am_status_to_name()

• am_status_to_string()

• am_http_cookie_encode()

• am_http_cookie_decode()

am_cleanup()

Cleans up any memory allocated by C SDK.

This function must be called when a caller is done with C SDK interfaces to cleanup memory allocated by the C SDK.

Syntax

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

Parameters

This function takes no parameters.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If XML message was successfully parsed and processed.

AM_INVALID_ARGUMENT

If any input parameter is invalid.

AM_FAILURE

If any other error occurred.

Details

This should be called only once at the end of C SDK calls, after which the initialize functions am_*_init() must be called again to initialize the C SDK before using any of its interfaces.

Any properties input parameter given to the init functions am_sso_init(), am_auth_init() or am_policy_init() should be destroyed only after am_cleanup is called.

am_notify()

Parses and processes an SSO or policy notification message as an XML string. If the message is an SSO notification, any SSO Token listeners registered using am_sso_add_listener() will be called. If the notification 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 if the policy module in the C SDK has been initialized (using am_policy_init() and am_policy_service_init() ).

Syntax

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

Parameters

This function takes the following parameters:

Parameter

Description

xmlmsg

XML message containing the notification message.

policy_handle_t

The policy handle created from am_policy_service_init(). NULL if policy is not initialized or not used.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If XML message was successfully parsed and processed.

AM_INVALID_ARGUMENT

If any input parameter is invalid.

AM_ERROR_PARSING_XML

If there was an error parsing the XML message.

AM_ERROR_DISPATCH_LISTENER

If there was an error dispatching the listener(s).

AM_FAILURE

If any other error occurred.

Details

This function should be called by the service listening on the notification URL given in the properties file if notification is enabled.

am_string_set_allocate()

Allocates space for an am_string_set_t and space for size strings. Also initializes size to the given size.

Syntax

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

Parameters

This function takes the following parameters:

Parameter

Description

size

Size of set to allocate.

Returns

This function returns a pointer to allocated am_string_set_t, or NULL if size is less than 0.

am_string_set_destroy()

Frees memory held by the parameter, by freeing each string in the set of strings, followed by the strings pointer, followed by the struct 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 parameters:

Parameter

Description

string_set

The am_string_set_t pointer to be freed.

Returns

None

am_status_to_name()

Returns the name of the given status code as a string. For example, the name of AM_SUCCESS is AM_SUCCCESS.

Syntax

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

Parameters

This function takes the following parameters:

Parameter

Description

status

The status code.

Returns

This function returns the name of the status code as a const char * .

am_status_to_string()

Returns the message for the given status code. For example, the message for AM_SUCCESS issuccess.

Syntax

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

Parameters

This function takes the following parameters:

Parameter

Description

status

The status code.

Returns

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

Details

The header file for this function is am_types.h

am_http_cookie_encode()

URL encodes a HTTP cookie.

Syntax

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

Parameters

This function takes the following parameters:

Parameter

Description

cookie

The cookie to be URL encoded.

buf

The buffer to put the encoded cookie.

len

The size of the buffer.

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the cookie was successfully encoded and copied into buf.

AM_INVALID_ARGUMENT

If the cookie or buffer was NULL or len was smaller than the size of the encoded value.

AM_FAILURE

Other error occurred while encoding cookie.

am_http_cookie_decode()

URL decodes a HTTP cookie.

Syntax

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

Parameters

This function takes the following parameters:

Parameter

Description

cookie

The cookie to be URL decoded.

buf

The buffer to put the decoded cookie

len

The size of the buffer

Returns

This function returns am_status_t with one of the following values:

Value

Description

AM_SUCCESS

If the cookie was successfully decoded and copied into buf.

AM_INVALID_ARGUMENT

If the cookie or buffer was NULL or len was smaller than the size of the decoded value.

AM_FAILURE

Other error occurred while decoding cookie.