389c6c6aa3808b24515674c24bcd95d850905aeb
[mirror/winof/.git] / inc / complib / cl_log.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      Declaration of logging mechanisms.\r
37  *\r
38  * Environment:\r
39  *      All\r
40  */\r
41 \r
42 \r
43 #ifndef _CL_LOG_H_\r
44 #define _CL_LOG_H_\r
45 \r
46 \r
47 #include <complib/cl_types.h>\r
48 \r
49 \r
50 /****h* Component Library/Log Provider\r
51 * NAME\r
52 *       Log Provider\r
53 *\r
54 * DESCRIPTION\r
55 *       The log provider allows users to log information in a system log instead of\r
56 *       the console or debugger target.\r
57 **********/\r
58 \r
59 \r
60 /****d* Component Library: Log Provider/cl_log_type_t\r
61 * NAME\r
62 *       cl_log_type_t\r
63 *\r
64 * DESCRIPTION\r
65 *       The cl_log_type_t enumerated type is used to differentiate between\r
66 *       different types of log entries.\r
67 *\r
68 * SYNOPSIS\r
69 */\r
70 typedef enum _cl_log_type\r
71 {\r
72         CL_LOG_INFO,\r
73         CL_LOG_WARN,\r
74         CL_LOG_ERROR\r
75 \r
76 } cl_log_type_t;\r
77 /*\r
78 * VALUES\r
79 *       CL_LOG_INFO\r
80 *               Indicates a log entry is purely informational.\r
81 *\r
82 *       CL_LOG_WARN\r
83 *               Indicates a log entry is a warning but non-fatal.\r
84 *\r
85 *       CL_LOG_ERROR\r
86 *               Indicates a log entry is a fatal error.\r
87 *\r
88 * SEE ALSO\r
89 *       Log Provider, cl_log_event\r
90 *********/\r
91 \r
92 \r
93 #ifdef __cplusplus\r
94 extern "C"\r
95 {\r
96 #endif\r
97 \r
98 \r
99 /****f* Component Library: Log Provider/cl_log_event\r
100 * NAME\r
101 *       cl_log_event\r
102 *\r
103 * DESCRIPTION\r
104 *       The cl_log_event function adds a new entry to the system log.\r
105 *\r
106 * SYNOPSIS\r
107 */\r
108 CL_EXPORT void CL_API\r
109 cl_log_event(\r
110         IN      const char* const       name,\r
111         IN      const cl_log_type_t     type,\r
112         IN      const char* const       message,\r
113         IN      const void* const       p_data OPTIONAL,\r
114         IN      const uint32_t          data_len );\r
115 /*\r
116 * PARAMETERS\r
117 *       name\r
118 *               [in] Pointer to an ANSI string containing the name of the source for\r
119 *               the log entry.\r
120 *\r
121 *       type\r
122 *               [in] Defines the type of log entry to add to the system log.\r
123 *               See the definition of cl_log_type_t for acceptable values.\r
124 *\r
125 *       message\r
126 *               [in] Pointer to an ANSI string containing the text for the log entry.\r
127 *               The message should not be terminated with a new line, as the log\r
128 *               provider appends a new line to all log entries.\r
129 *\r
130 *       p_data\r
131 *               [in] Optional pointer to data providing context for the log entry.\r
132 *               At most 256 bytes of data can be successfully logged.\r
133 *\r
134 *       data_len\r
135 *               [in] Length of the buffer pointed to by the p_data parameter.  Ignored\r
136 *               if p_data is NULL.\r
137 *\r
138 * RETURN VALUE\r
139 *       This function does not return a value.\r
140 *\r
141 * NOTES\r
142 *       If the data length exceeds the maximum supported, the event is logged\r
143 *       without its accompanying data.\r
144 *\r
145 * SEE ALSO\r
146 *       Log Provider, cl_log_type_t\r
147 *********/\r
148 \r
149 \r
150 #ifdef __cplusplus\r
151 }\r
152 #endif\r
153 \r
154 \r
155 #endif  /* _CL_LOG_H_ */\r