|
| |
| Sun Java System Access Manager 2005Q1 Developer's Reference | |
Chapter 3
Logging FunctionsThis chapter provides a reference to public functions in the C SDK for logging on the local system or on Sun Java™ System Access Manager 6 2005Q1. Function summaries include a short description, syntax, parameters and returns.
The following functions are contained in the header file am_log.h:
am_log_add_module()Adds a new module to the list of known logging modules.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_add_module(const char *name, am_log_module_id_t *id_ptr);Parameters
This function takes the following parameters:
Parameter
Description
name
The name to associate with the new module.
id_ptr
Where to store the id of the logging module.
Returns
This function returns am_status_t with one of the following values:
Details
If a module of the same name already exists, then the module ID of that module is returned.
am_log_flush_remote_log()Flushes all the log records in the log buffer.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_flush_remote_log();Parameters
This function takes no parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If Flush to remote log was successful.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_init()Initializes logging.
This must be called before using any am_log_* interfaces.
If any SSO, auth or policy initialization functions, am_sso_init(), am_auth_init(), or am_policy_init(), is called, then am_log_init() does not need to be called separately. Any of those functions will call am_log_init() internally with the same properties parameter that was used to initialize sso, auth or policy.
See the agents documentation on parameters related to logging that can be used to initialize log.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_init(const am_properties_t log_init_params);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If log initialization is successful.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_is_level_enabled()Determines whether a logging message at the specified level and associated with the specified module would be emitted.Syntax
#include "am_log.h"
AM_EXPORT boolean_t
am_log_is_level_enabled(am_log_module_id_t moduleID,
am_log_level_t level);Parameters
This function takes the following parameters:
Parameter
Description
module
The ID of the module to be examined.
level
The logging level to be checked.
Returns
This function returns boolean_t with one of the following values:
am_log_log()Log the given message for the given module and at the given level.
Syntax
#include "am_log.h"
AM_EXPORT boolean_t
am_log_log(am_log_module_id_t moduleID,
am_log_level_t level,
const char *format, ...);Parameters
This function takes the following parameters:
Parameter
Description
module
The ID of the module to be associated with the message.
level
The logging level of the message.
format
A printf-style format string.
Returns
This function returns boolean_t with one of the following values.
The set of addition arguments needed by the format string either enumerated directly or passed using the standard va_list mechanism as appropriate to the call.
Details
The message is emitted only if the current level of the specified module is greater than or equal to the specified level.
am_log_log_record()Logs the given log record to the given log_name on the Access Manager.
am_log_record_* interfaces can be used to set information in the log record.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_log_record(am_log_record_t record,
const char *log_name,
const char *logged_by_token_id);Start here
Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the log operation was successful
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_add_loginfo()Updates the log record with additional information.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_add_loginfo(am_log_record_t record,
const char *key,
const char *value);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the key and value was successfully added to the given log record.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_create()Creates a log record and initializes it with the given log level and message.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_create(am_log_record_t *record_ptr,
am_log_record_log_level_t log_level,
const char *message);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the key and value was successfully added to the given log record.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_destroy()Destroys the log record returned by am_log_record_create.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_destroy(am_log_record_t record);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the log record was successfully destroyed.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_populate()Updates the log record with user's SSO token information.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_populate(am_log_record_t record,
const char *user_token_id);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the operation was successful.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_set_log_level()Convenience functions.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_log_level(am_log_record_t record,
am_log_record_log_level_t log_level);Parameters
This function takes the following parameters:
Parameter
Description
record
Opaque handle to the log record.
log level
Log level to set in the log record.
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the log level was successfully set.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_set_log_message()Convenience function.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_log_message(am_log_record_t record,
const char *message);Parameters
This function takes the following parameters:
Parameter
Description
record
Opaque handle to the log record.
message
The message to set in the log record.
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If the message was successfully added to the log record.
AM_*
If any error occurs, the type of error indicated by the status value.
am_log_record_set_loginfo_props()Updates the log record with additional information.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_record_set_loginfo_props(am_log_record_t record,
am_properties_t log_info);Parameters
This function takes the following parameters:
Parameter
Description
record
Opaque handle to the log record.
log_info
Key value pairs to be set in the log record.
Returns
This function returns am_status_t with one of the following values:
Value
Description
AM_SUCCESS
If log_info was successfully added.
AM_*
If any error occurs, the type of error indicated by the status value.
Details
Sets all log info values as properties map.
The log_info is expected to have the required log info fields as key value pairs and user is expected to delete the am_properties_t pointer only when he is done with amsdk.
am_log_set_levels_from_string()Sets the logging level for the modules listed in specified string.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_levels_from_string(const char *module_level_string);Parameters
This function takes the following parameter:
Returns
This function returns am_status_t with one of the following values:
Details
The format of the string is:
<ModuleName>[:<Level>][,<ModuleName>[:<Level>]]*
Optional spaces may occur before and after any commas.
am_log_set_log_file()Sets the name of the file to use for logging.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_log_file(const char *name);Parameters
This function takes the following parameter:
Returns
This function returns am_status_twith one of the following values:
Value
Description
AM_SUCCESS
If the logging file could be set
AM_NO_MEMORY
If unable to allocate memory for internal data structures
AM_FAILURE
If any other error is detected
Details
If the specified name is NULL or empty, then logging messages will be sent to the stderr * stream.
am_log_set_module_level()Sets the logging level for the specified module.
Syntax
#include "am_log.h"
AM_EXPORT am_log_level_t
am_log_set_module_level(am_log_module_id_t moduleID,
am_log_level_t level);Parameters
This function takes the following parameters:
Parameter
Description
moduleID
The ID of the module to be modified.
level
The new logging level for the module.
Returns
This function returns am_log_level_t with one of the following values:
Value
Description
The previous logging level of the module.
When the logging level is set properly.
LOG_NONE
If the specified module is invalid.
am_log_set_remote_info()Sets information about Access Manager log service for the remote log module.
This must be called before calling am_log_message() with AM_LOG_REMOTE_MODULE as the log module.
Otherwise use am_log_log() with a log record and SSO token ID to log to Access Manager.
Syntax
#include "am_log.h"
AM_EXPORT am_status_t
am_log_set_remote_info(const char *rem_log_url,
const char *sso_token_id,
const char *rem_log_name,
const am_properties_t log_props);Parameters
This function takes the following parameters:
Returns
This function returns am_status_t with one of the following values:
am_log_vlog()Logs a message for the given module at the given level.
Syntax
#include "am_log.h"
AM_EXPORT boolean_t
am_log_vlog(am_log_module_id_t moduleID,
am_log_level_t level,
const char *format, ...);Parameters
This function takes the following parameters:
Parameter
Description
module
The ID of the module to be associated with the message.
level
The logging level of the message.
format
A printf-style format string.
Returns
The set of addition arguments needed by the format string either enumerated directly or passed using the standard va_list mechanism as appropriate to the call.
Details
The message is emitted only if the current level of the specified module is greater than or equal to the specified level.