4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* -*- Mode: C -*- */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * The contents of this file are subject to the terms
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * of the Common Development and Distribution License
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * (the License). You may not use this file except in
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * compliance with the License.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * You can obtain a copy of the License at
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * https://opensso.dev.java.net/public/CDDLv1.0.html or
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * See the License for the specific language governing
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * permission and limitations under the License.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * When distributing Covered Code, include this CDDL
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Header Notice in each file and include the License file
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * If applicable, add the following below the CDDL Header,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * with the fields enclosed by brackets [] replaced by
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * your own identifying information:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * "Portions Copyrighted [year] [name of copyright owner]"
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * $Id: am_log.h,v 1.4 2008/08/19 19:11:36 veiming Exp $
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Types and functions for using OpenSSO Access
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Management SDK log objects.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster AM_LOG_NONE, /* never logged, typically used to turn off a module */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster AM_LOG_WARNING, /* used for warning messages */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster AM_LOG_INFO, /* used for informational messages */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster AM_LOG_MAX_DEBUG, /* used for more detailed debug messages */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster AM_LOG_AUTH_REMOTE = 128, /* logged deny and/or allow */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster /* Log Level as defined by JDK 1.4 */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster /* Log Levels defined by OpenSSO */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Log Record */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster#define AM_LOG_ALL_MODULES ((am_log_module_id_t) 0)
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster#define AM_LOG_REMOTE_MODULE ((am_log_module_id_t) AM_LOG_ALL_MODULES+1)
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Default log fields which can be used for adding log info */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Initializes the log service.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * properties name of the properties file.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_SUCCESS
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if the logging file could be initialized
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_FAILURE
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if any other error is detected
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_init(const am_properties_t properties);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Sets the name of the file to use for logging. If the specified name
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * is NULL or empty, then logging messages will be sent to the stderr
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * name name of the file in which to record logging messages
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_SUCCESS
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if the logging file could be set
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_NO_MEMORY
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if unable to allocate memory for internal data structures
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_FAILURE
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if any other error is detected
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_set_log_file(const char *name);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Adds a new module to the list of known logging modules. If a
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * module of the same name already exists, then the module id of that
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * module is returned.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * name the name to associate with the new module
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * id_ptr where to store the id of the logging module
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_SUCCESS
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if no error is detected
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_INVALID_ARGUMENT
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if name or id_ptr is NULL
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_NSPR_ERROR
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if unable to initialize to the logging package
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_NO_MEMORY
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if unable to allocate memory for the new logging module
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * AM_FAILURE
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * if any other error is detected
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Fosteram_log_add_module(const char *name, am_log_module_id_t *id_ptr);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Sets the logging level for the specified module.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * moduleID the id of the module to be modified
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * level the new logging level for the module
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * the previous logging level of the module or LOG_NONE if the specified
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * module is invalid.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Fosteram_log_set_module_level(am_log_module_id_t moduleID,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Sets the logging level for the modules listed in specified string.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * The format of the string is:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * <ModuleName>[:<Level>][,<ModuleName>[:<Level>]]*
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Optional spaces may occur before and after any commas.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * module_level_string
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * list of modules to set.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * The same set of errors as am_log_add_module.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Fosteram_log_set_levels_from_string(const char *module_level_string);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Determines whether a logging message at the specified level and
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * associated with the specified module would be emitted.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * module the id of the module to be examined
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * level the logging level to be checked
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * !0 if the message would be emitted
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * 0 otherwise
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT boolean_t am_log_is_level_enabled(am_log_module_id_t moduleID,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * The next two routines produce logging messages. The message is
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * emitted only if the current level of the specified module is
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * greater than or equal to the specified level.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Parameters:
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * module the id of the module to be associated with the message
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * level the logging level of the message
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * format a printf-style format string
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * the set of addition arguments needed by the format string either
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * enumerated directly or passed using the standard va_list mechanism
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * as appropriate to the call.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT boolean_t am_log_log(am_log_module_id_t moduleID,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster const char *format, ...);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT boolean_t am_log_vlog(am_log_module_id_t moduleID,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_set_remote_info(const char *rem_log_url,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Instantiate a log record and initialize it with the given
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * log level and message
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_create(am_log_record_t *record_ptr,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster const char *message);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Destroys the log record returned by am_log_record_create */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_destroy(am_log_record_t record);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Update log record with user's sso token information */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_populate(am_log_record_t record,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Update log record with additional information */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_add_loginfo(am_log_record_t record,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster const char *key,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster const char *value);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Update log record with additional information.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * Set all log info values as properties map
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * The log_info is expected to have the required log info fields as key value
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * pairs and user is expected to delete the am_properties_t pointer only when
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster * he is done with amsdk.
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_set_loginfo_props(am_log_record_t record,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Convenience functions */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_set_log_level(am_log_record_t record,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_record_set_log_message(am_log_record_t record,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster const char *message);
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Log the log record in given log_name */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_log_record(am_log_record_t record,
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster/* Flush all the log records in the log buffer */
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan FosterAM_EXPORT am_status_t am_log_flush_remote_log();
4fe4e4f798a84a46e567f64ceadd3648eb0582d4Allan Foster#endif /* not AM_LOG_H */