/*

 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.

 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.

 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.

 *

 * This software is available to you under a choice of one of two

 * licenses.  You may choose to be licensed under the terms of the GNU

 * General Public License (GPL) Version 2, available from the file

 * COPYING in the main directory of this source tree, or the

 * OpenIB.org BSD license below:

 *

 *     Redistribution and use in source and binary forms, with or

 *     without modification, are permitted provided that the following

 *     conditions are met:

 *

 *      - Redistributions of source code must retain the above

 *        copyright notice, this list of conditions and the following

 *        disclaimer.

 *

 *      - Redistributions in binary form must reproduce the above

 *        copyright notice, this list of conditions and the following

 *        disclaimer in the documentation and/or other materials

 *        provided with the distribution.

 *

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS

 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN

 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

 * SOFTWARE.

 *

 */

/*

 * Abstract:

 *	Declaration of logging mechanisms.

 */

#ifndef _CL_LOG_H_

#define _CL_LOG_H_

#include <complib/cl_types.h>

#ifdef __cplusplus

#  define BEGIN_C_DECLS extern "C" {

#  define END_C_DECLS   }

#else				/* !__cplusplus */

#  define BEGIN_C_DECLS

#  define END_C_DECLS

#endif				/* __cplusplus */

BEGIN_C_DECLS

/****h* Component Library/Log Provider

* NAME

*	Log Provider

*

* DESCRIPTION

*	The log provider allows users to log information in a system log instead of

*	the console or debugger target.

**********/

/****d* Component Library: Log Provider/cl_log_type_t

* NAME

*	cl_log_type_t

*

* DESCRIPTION

*	The cl_log_type_t enumerated type is used to differentiate between

*	different types of log entries.

*

* SYNOPSIS

*/

typedef enum _cl_log_type {

	CL_LOG_INFO,

	CL_LOG_WARN,

	CL_LOG_ERROR

} cl_log_type_t;

/*

* VALUES

*	CL_LOG_INFO

*		Indicates a log entry is purely informational.

*

*	CL_LOG_WARN

*		Indicates a log entry is a warning but non-fatal.

*

*	CL_LOG_ERROR

*		Indicates a log entry is a fatal error.

*

* SEE ALSO

*	Log Provider, cl_log_event

*********/

/****f* Component Library: Log Provider/cl_log_event

* NAME

*	cl_log_event

*

* DESCRIPTION

*	The cl_log_event function adds a new entry to the system log.

*

* SYNOPSIS

*/

void

cl_log_event(IN const char *const name,

	     IN const cl_log_type_t type,

	     IN const char *const message,

	     IN const void *const p_data OPTIONAL, IN const uint32_t data_len);

/*

* PARAMETERS

*	name

*		[in] Pointer to an ANSI string containing the name of the source for

*		the log entry.

*

*	type

*		[in] Defines the type of log entry to add to the system log.

*		See the definition of cl_log_type_t for acceptable values.

*

*	message

*		[in] Pointer to an ANSI string containing the text for the log entry.

*		The message should not be terminated with a new line, as the log

*		provider appends a new line to all log entries.

*

*	p_data

*		[in] Optional pointer to data providing context for the log entry.

*		At most 256 bytes of data can be successfully logged.

*

*	data_len

*		[in] Length of the buffer pointed to by the p_data parameter.  Ignored

*		if p_data is NULL.

*

* RETURN VALUE

*	This function does not return a value.

*

* NOTES

*	If the data length exceeds the maximum supported, the event is logged

*	without its accompanying data.

*

* SEE ALSO

*	Log Provider, cl_log_type_t

*********/

END_C_DECLS

#endif				/* _CL_LOG_H_ */