The logging functions defined in <am_log.h> are:
Adds a new logging file (for a specific function or feature) to the OpenSSO Enterprise Logging Service.
The currently used module file names are:
AuthService
NamingService
PolicyService
SessionService
PolicyEngine
ServiceEngine
Notification
PolicyAgent
RemoteLog
all
#include "am_log.h" AM_EXPORT am_status_t am_log_add_module(const char *name, am_log_module_id_t *id_ptr);
This function takes the following parameters:
Pointer to the name associated with the new module.
Pointer to the location where the identifier for the logging module is stored.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If a module of the same name already exists, the module identifier of the existing module is returned.
If the addition was successful.
If name or id_ptr is NULL.
If unable to initialize the logging framework.
If unable to allocate memory for the new module.
If any other error is detected.
Flushes all the log records in the OpenSSO Enterprise log buffer.
#include "am_log.h" AM_EXPORT am_status_t am_log_flush_remote_log();
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 the flush was successful.
The appropriate code based on the error.
Initializes the Logging Service.
am_log_init() writes events to the logs on the OpenSSO Enterprise server.
#include "am_log.h" AM_EXPORT am_status_t am_log_init(const am_properties_t log_init_params);
This function takes the following parameter:
Properties used to initialize the Logging Service.
See am_properties_t for more information.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If log initialization is successful.
If any error occurs, the type of error indicated by the status value.
Checks whether an event at the specified level intended for the specified logging module should generate a logging message.
If the level of the event is not equal to or higher than the level of the logging module, a logging message will not be generated.
#include "am_log.h" AM_EXPORT boolean_t am_log_is_level_enabled(am_log_module_id_t moduleID, am_log_level_t level);
This function takes the following parameters:
The identifier of the logging module.
The level of the event. Possible values are defined in the following am_log_level_t enumeration. The default value is AM_LOG_INFO.
typedef enum am_log_level { AM_LOG_ALWAYS = -1, /* always logged */ AM_LOG_NONE, /* never logged, typically used to turn off a module */ AM_LOG_ERROR, /* used for error messages */ AM_LOG_WARNING, /* used for warning messages */ AM_LOG_INFO, /* used for informational messages */ AM_LOG_DEBUG, /* used for debug messages */ AM_LOG_MAX_DEBUG, /* used for more detailed debug messages */ AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */ AM_LOG_AUTH_LOCAL = 256 } am_log_level_t;
This function returns one of the following values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system.
If a message will be generated.
If a message will not be generated.
Produces a logging message from the specified event string.
When using am_log_log(), consider the following:
The message is produced only if the level defined for the specified module is greater than or equal to the level defined for the message. See am_log_is_level_enabled().
am_log_log() directly enumerates arguments for the format string. See am_log_vlog() for another method.
#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, ...);
This function takes the following parameters:
The identifier of the OpenSSO Enterprise logging module to which the message is relevant.
The level of the message. Each message has an associated level that defines the amount of detail that will be logged. Possible values are defined in the am_log_level_t enumeration. The default value is AM_LOG_INFO.
typedef enum am_log_level { AM_LOG_ALWAYS = -1, /* always logged */ AM_LOG_NONE, /* never logged, typically used to turn off a module */ AM_LOG_ERROR, /* used for error messages */ AM_LOG_WARNING, /* used for warning messages */ AM_LOG_INFO, /* used for informational messages */ AM_LOG_DEBUG, /* used for debug messages */ AM_LOG_MAX_DEBUG, /* used for more detailed debug messages */ AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */ AM_LOG_AUTH_LOCAL = 256 } am_log_level_t;
Pointer to a printf-style character string detailing the event.
The set of additional arguments needed by format are either enumerated directly or passed using the standard va_list mechanism as appropriate to the call. See am_log_vlog().
This function returns one of the values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system.
If the message is logged.
If the message will not be logged.
Writes the given log record to the specified logging module.
#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);
This function takes the following parameters:
The log record pointer.
Pointer to the name of the logging module to which the log record will be written.
Pointer to a valid SSOTokenID identifying the user to whom the log record applies.
This is required to access the Logging Service on OpenSSO Enterprise.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If log record is written.
If any error occurs, the type of error indicated by the status value.
Updates a log record with additional information.
#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);
This function takes the following parameters:
A log record pointer.
Pointer to the log field being updated.
See Chapter 15, Recording Events with the Logging Service, in Sun OpenSSO Enterprise 8.0 Technical Overview for information regarding events that are logged and the log fields to which they are written.
Pointer to the value with which the log field will be modified.
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Instantiates a log record, initializing it with a message and the message's corresponding level.
#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);
This function takes the following parameters:
Pointer to a log record pointer.
The level with which the log record will be instantiated. Each log record has an associated level that defines its relative importance and urgency. Possible values are defined in the am_log_record_log_level_t enumeration.
typedef enum am_log_record_log_level { /* Log Level as defined by JDK 1.4 */ AM_LOG_LEVEL_SEVERE = 1000, AM_LOG_LEVEL_WARNING = 900, AM_LOG_LEVEL_INFORMATION = 800, AM_LOG_LEVEL_CONFIG = 700, AM_LOG_LEVEL_FINE = 500, AM_LOG_LEVEL_FINER = 400, AM_LOG_LEVEL_FINEST = 300, /* Log Levels defined by Access Manager */ AM_LOG_LEVEL_SECURITY = 950, AM_LOG_LEVEL_CATASTROPHE = 850, AM_LOG_LEVEL_MISCONF = 750, AM_LOG_LEVEL_FAILURE = 650, AM_LOG_LEVEL_WARN = 550, AM_LOG_LEVEL_INFO = 450, AM_LOG_LEVEL_DEBUG = 350, AM_LOG_LEVEL_ALL = 250 } am_log_record_log_level_t;
Pointer to the log message to be written to the log record.
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Destroys the specified log record.
#include "am_log.h" AM_EXPORT am_status_t am_log_record_destroy(am_log_record_t record);
This function takes the following parameter:
A log record pointer.
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Updates a log record with the user’s session identifier (also known as an SSOTokenID).
See Single Sign-on Token Handles for more information.
#include "am_log.h" AM_EXPORT am_status_t am_log_record_populate(am_log_record_t record, const char *user_token_id);
This function takes the following parameters:
A log record pointer.
Pointer to a valid session identifier (also known as an SSOTokenID).
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Sets the level for the specified log record.
#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);
This function takes the following parameters:
A log record pointer.
The level to which the log record will be set. Each log record has an associated level that defines its relative importance and urgency. Possible values are defined in the am_log_record_log_level_t enumeration.
typedef enum am_log_record_log_level { /* Log Level as defined by JDK 1.4 */ AM_LOG_LEVEL_SEVERE = 1000, AM_LOG_LEVEL_WARNING = 900, AM_LOG_LEVEL_INFORMATION = 800, AM_LOG_LEVEL_CONFIG = 700, AM_LOG_LEVEL_FINE = 500, AM_LOG_LEVEL_FINER = 400, AM_LOG_LEVEL_FINEST = 300, /* Log Levels defined by Access Manager */ AM_LOG_LEVEL_SECURITY = 950, AM_LOG_LEVEL_CATASTROPHE = 850, AM_LOG_LEVEL_MISCONF = 750, AM_LOG_LEVEL_FAILURE = 650, AM_LOG_LEVEL_WARN = 550, AM_LOG_LEVEL_INFO = 450, AM_LOG_LEVEL_DEBUG = 350, AM_LOG_LEVEL_ALL = 250 } am_log_record_log_level_t;
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Sets the log message to the log record before localization and formatting.
#include "am_log.h" AM_EXPORT am_status_t am_log_record_set_log_message(am_log_record_t record, const char *message);
This function takes the following parameters:
A log record pointer.
Pointer to the log message to be written to the log record.
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Updates the specified log record with additional information.
log_info is expected to have the information formatted as key/value pairs in a properties map. Delete the am_properties_t pointer only when finished with the SDK. See am_properties_t for more information.
#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);
This function takes the following parameters:
A log record pointer.
Pointer to the properties that contain the information to be set in the log record.
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Sets the level for the logging modules listed in a specified string.
The format of the string must be:
ModuleName[:Level][,ModuleName[:Level]]* |
Optional spaces may occur before and after any commas. The comma, brackets and asterisk in the second term signifies that it can occur 0 or more times.
#include "am_log.h" AM_EXPORT am_status_t am_log_set_levels_from_string(const char *module_level_string);
This function takes the following parameter:
Pointer to the string containing the list of modules and the respective levels.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the levels were successfully set.
If module_level_string is NULL.
If any other error is detected.
Sets the name of the file to use for logging.
#include "am_log.h" AM_EXPORT am_status_t am_log_set_log_file(const char *name);
This function takes the following parameter:
Pointer to the name of the file to which log records are recorded.
If NULL or empty, logging messages are sent to the stderr stream.
This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):
If the logging file is successfully set.
If unable to allocate memory for internal data structures.
If an error of any type occurs.
Sets the level for the specified logging module.
#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);
This function takes the following parameters:
The identifier of the logging module.
The level to which the logging module will be set. Each module has an associated level that defines the amount of detail that will be logged. Possible values are defined in the following enumeration. The default value is AM_LOG_INFO.
typedef enum am_log_level { AM_LOG_ALWAYS = -1, /* always logged */ AM_LOG_NONE, /* never logged, typically used to turn off a module */ AM_LOG_ERROR, /* used for error messages */ AM_LOG_WARNING, /* used for warning messages */ AM_LOG_INFO, /* used for informational messages */ AM_LOG_DEBUG, /* used for debug messages */ AM_LOG_MAX_DEBUG, /* used for more detailed debug messages */ AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */ AM_LOG_AUTH_LOCAL = 256 } am_log_level_t;
This function returns am_log_level_t with one of the following values:
If the logging level is set properly.
If the specified module is invalid.
Initializes the remote log service.
This must be called before am_log_log() with AM_LOG_REMOTE_MODULE as the log module. Initialization is done only once. Subsequently, only remote logging calls are done.
#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);
This function takes the following parameters:
Pointer to the URL of the OpenSSO Enterprise Logging Service being used for the remote logging.
Pointer to a valid SSOTokenID identifying the user to whom the log record applies.
Pointer to the logging module (file) to which log records are written.
Pointer to the properties that contain the information to initialize the OpenSSO Enterprise Logging Service.
log_props is expected to have the information formatted as a properties map in key/value pairs. Delete the am_properties_t pointer only when finished with the SDK. See am_properties_t for more information.
This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file).
Logs a message for the specified module at the given level.
When using am_log_vlog(), consider the following:
The message is produced only if the level defined for the specified module is greater than or equal to the level defined for the message. See am_log_is_level_enabled().
am_log_vlog() passes the standard va_list as an argument for the format string. See am_log_log() for another method.
#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, va_list args);
This function takes the following parameters:
The identifier of the OpenSSO Enterprise logging module to which the message is relevant.
The level of the message. Each message has an associated level that defines the amount of detail that will be logged. Possible values are defined in the am_log_level_t enumeration. The default value is AM_LOG_INFO.
typedef enum am_log_level { AM_LOG_ALWAYS = -1, /* always logged */ AM_LOG_NONE, /* never logged, typically used to turn off a module */ AM_LOG_ERROR, /* used for error messages */ AM_LOG_WARNING, /* used for warning messages */ AM_LOG_INFO, /* used for informational messages */ AM_LOG_DEBUG, /* used for debug messages */ AM_LOG_MAX_DEBUG, /* used for more detailed debug messages */ AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */ AM_LOG_AUTH_LOCAL = 256 } am_log_level_t;
Pointer to a printf-style character string.
The set of addition arguments needed by format are either enumerated directly or passed using the standard va_list mechanism as appropriate to the call.
A void pointer interpreted as an argument list. va_list is the type of the void pointer passed to a function that accepts a pointer to a list of arguments.
The set of additional arguments needed by format are either enumerated directly or passed using the standard va_list mechanism as appropriate to the call. See am_log_log().
This function returns one of the values of the boolean_t enumeration (defined in the standard <types.h> header file):
The code used is dependent on the server operating system. See <am_types.h> for more details.
If the message can be logged.
If the message will not be logged.