This chapter provides a reference to public functions in the C SDK for logging on the local system or on Sun JavaTM System Access Manager. Function summaries include a short description, syntax, parameters and returns.
The following functions are contained in the header file am_log.h:
Adds a new module to the list of known logging modules.
#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:
The name to associate with the new module.
Where to store the id of the logging module.
This function returns am_status_t with one of the following values:
If no error is detected.
If name or id_ptr is NULL.
If unable to initialize to the logging package.
If unable to allocate memory for the new logging module.
If any other error is detected.
If a module of the same name already exists, then the module ID of that module is returned.
Flushes all the log records in the log buffer.
#include "am_log.h" AM_EXPORT am_status_t am_log_flush_remote_log();
This function takes no parameters:
This function returns am_status_t with one of the following values:
If Flush to remote log was successful.
If any error occurs, the type of error indicated by the status value.
Initializes logging.
This must be called before using any am_log_* interfaces.
If any SSO, authentication, 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, authentication, or policy.
See the agents documentation on parameters related to logging that can be used to initialize log.
#include "am_log.h" AM_EXPORT am_status_t am_log_init(const am_properties_t log_init_params);
This function takes the following parameters:
Properties to initialize the log module with.
This function returns am_status_t with one of the following values:
If log initialization is successful.
If any error occurs, the type of error indicated by the status value.
Determines whether a logging message at the specified level and associated with the specified module would be emitted.
#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 ID of the module to be examined.
The logging level to be checked.
This function returns boolean_t with one of the following values:
If the message would be emitted.
Otherwise
Log the given message for the given module and at the given level.
#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 ID of the module to be associated with the message.
The logging level of the message.
A printf-style format string.
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.
The message is emitted only if the current level of the specified module is greater than or equal to the specified level.
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.
#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
This function takes the following parameters:
The log record.
The name of the log module to log the log record to
A valid SSO token ID required to access the logging service on Access Manager.
This function returns am_status_t with one of the following values:
If the log operation was successful
If any error occurs, the type of error indicated by the status value.
Updates the 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:
Opaque handle to the log record.
The name of the log module to log the log record to.
A valid SSO token ID required to access the logging service on Access Manager.
This function returns am_status_t with one of the following values:
If the key and value was successfully added to the given log record.
If any error occurs, the type of error indicated by the status value.
Creates a log record and initializes it with the given log level and message.
#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:
Opaque handle to the log record.
The name of the log module to log the log record to
A valid SSO token ID required to access the logging service on Access Manager.
This function returns am_status_t with one of the following values:
If the key and value was successfully added to the given log record.
If any error occurs, the type of error indicated by the status value.
Destroys the log record returned by am_log_record_create.
#include "am_log.h" AM_EXPORT am_status_t am_log_record_destroy(am_log_record_t record);
This function takes the following parameter:
Opaque handle to the log record to destroy.
This function returns am_status_t with one of the following values:
If the log record was successfully destroyed.
If any error occurs, the type of error indicated by the status value.
Updates the log record with user’s SSO token 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:
Opaque handle to the log record.
A valid SSO Token ID.
This function returns am_status_t with one of the following values:
If the operation was successful.
If any error occurs, the type of error indicated by the status value.
Convenience functions.
#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:
Opaque handle to the log record.
Log level to set in the log record.
This function returns am_status_t with one of the following values:
If the log level was successfully set.
If any error occurs, the type of error indicated by the status value.
Convenience function.
#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:
Opaque handle to the log record.
The message to set in the log record.
This function returns am_status_t with one of the following values:
If the message was successfully added to the log record.
If any error occurs, the type of error indicated by the status value.
Updates the log record with additional 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:
Opaque handle to the log record.
Key value pairs to be set in the log record.
This function returns am_status_t with one of the following values:
If log_info was successfully added.
If any error occurs, the type of error indicated by the status value.
Sets all log info values as properties map.
The log_info is expected to have the required log info members as key value pairs and user is expected to delete the am_properties_t pointer only when he is done with amsdk.
Sets the logging level for the modules listed in specified string.
#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:
List of modules to set.
This function returns am_status_t with one of the following values:
If no error is detected
If name or id_ptr is NULL
If unable to initialize to the logging package
If unable to allocate memory for the new logging module
If unable to allocate memory for the new logging module
The format of the string is:
<ModuleName>[:<Level>][,<ModuleName>[:<Level>]]*
Optional spaces may occur before and after any commas.
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:
Name of the file in which to record logging messages.
This function returns am_status_twith one of the following values:
If the logging file could be set
If unable to allocate memory for internal data structures
If any other error is detected
If the specified name is NULL or empty, then logging messages will be sent to the stderr stream.
Sets the logging level for the specified 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 ID of the module to be modified.
The new logging level for the module.
This function returns am_log_level_t with one of the following values:
When the logging level is set properly.
If the specified module is invalid.
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.
#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:
URL of the Access Manager log service.
The logged by SSO Token ID.
The log name on Access Manager.
Properties to initialize the remote log service with.
This function returns am_status_t with one of the following values:
If the function call is successful.
If an error occurs.
Logs a message for the given module at the given level.
#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, ...);
This function takes the following parameters:
The ID of the module to be associated with the message.
The logging level of the message.
A printf-style format string.
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.
The message is emitted only if the current level of the specified module is greater than or equal to the specified level.