Sun Java System Identity Server 2004Q2 Developer's Reference |
Chapter 9
Miscellaneous FunctionsThis chapter provides a reference to various Sun Java System Identity Server 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()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:
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:
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:
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:
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 is "success".
Syntax
#include "am_types.h"
AM_EXPORT const char *
am_status_to_string(am_status_t status);Parameters
This function takes the following parameters:
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:
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: