[IBBUS] added support to logging to System Event Log.
[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 #include <complib/cl_types.h>\r
47 \r
48 \r
49 /****h* Component Library/Log Provider\r
50 * NAME\r
51 *       Log Provider\r
52 *\r
53 * DESCRIPTION\r
54 *       The log provider allows users to log information in a system log instead of\r
55 *       the console or debugger target.\r
56 **********/\r
57 \r
58 \r
59 /****d* Component Library: Log Provider/cl_log_type_t\r
60 * NAME\r
61 *       cl_log_type_t\r
62 *\r
63 * DESCRIPTION\r
64 *       The cl_log_type_t enumerated type is used to differentiate between\r
65 *       different types of log entries.\r
66 *\r
67 * SYNOPSIS\r
68 */\r
69 typedef enum _cl_log_type\r
70 {\r
71         CL_LOG_INFO,\r
72         CL_LOG_WARN,\r
73         CL_LOG_ERROR\r
74 \r
75 } cl_log_type_t;\r
76 /*\r
77 * VALUES\r
78 *       CL_LOG_INFO\r
79 *               Indicates a log entry is purely informational.\r
80 *\r
81 *       CL_LOG_WARN\r
82 *               Indicates a log entry is a warning but non-fatal.\r
83 *\r
84 *       CL_LOG_ERROR\r
85 *               Indicates a log entry is a fatal error.\r
86 *\r
87 * SEE ALSO\r
88 *       Log Provider, cl_log_event\r
89 *********/\r
90 \r
91 \r
92 #ifdef __cplusplus\r
93 extern "C"\r
94 {\r
95 #endif\r
96 \r
97 \r
98 /****f* Component Library: Log Provider/cl_log_event\r
99 * NAME\r
100 *       cl_log_event\r
101 *\r
102 * DESCRIPTION\r
103 *       The cl_log_event function adds a new entry to the system log.\r
104 *\r
105 * SYNOPSIS\r
106 */\r
107 CL_EXPORT void CL_API\r
108 cl_log_event(\r
109         IN      const char* const       name,\r
110         IN      const cl_log_type_t     type,\r
111         IN      const char* const       message,\r
112         IN      const void* const       p_data OPTIONAL,\r
113         IN      const uint32_t          data_len );\r
114 /*\r
115 * PARAMETERS\r
116 *       name\r
117 *               [in] Pointer to an ANSI string containing the name of the source for\r
118 *               the log entry.\r
119 *\r
120 *       type\r
121 *               [in] Defines the type of log entry to add to the system log.\r
122 *               See the definition of cl_log_type_t for acceptable values.\r
123 *\r
124 *       message\r
125 *               [in] Pointer to an ANSI string containing the text for the log entry.\r
126 *               The message should not be terminated with a new line, as the log\r
127 *               provider appends a new line to all log entries.\r
128 *\r
129 *       p_data\r
130 *               [in] Optional pointer to data providing context for the log entry.\r
131 *               At most 256 bytes of data can be successfully logged.\r
132 *\r
133 *       data_len\r
134 *               [in] Length of the buffer pointed to by the p_data parameter.  Ignored\r
135 *               if p_data is NULL.\r
136 *\r
137 * RETURN VALUE\r
138 *       This function does not return a value.\r
139 *\r
140 * NOTES\r
141 *       If the data length exceeds the maximum supported, the event is logged\r
142 *       without its accompanying data.\r
143 *\r
144 * SEE ALSO\r
145 *       Log Provider, cl_log_type_t\r
146 *********/\r
147 \r
148 \r
149 /****f* Component Library: Debug Output/cl_msg_out\r
150 * NAME\r
151 *       cl_event_log_write\r
152 *\r
153 * DESCRIPTION\r
154 *       The cl_event_log_write function sends a message to System Event Logger.\r
155 *\r
156 * SYNOPSIS\r
157 */\r
158 CL_EXPORT void\r
159 cl_event_log_write(\r
160         PVOID   p_io_object,\r
161         ULONG   p_error_code,\r
162         ULONG   p_unique_error_code,\r
163         ULONG   p_final_status,\r
164         PWCHAR  p_insertion_string,\r
165         ULONG   p_n_data_items,\r
166                 ...\r
167                 );\r
168 /*\r
169 * PARAMETERS\r
170 *       p_io_object\r
171 *               [in] The IO object ( driver object or device object ).\r
172 *       \r
173 *       p_error_code\r
174 *               [in] The error code.\r
175 *\r
176 *       p_unique_error_code\r
177 *               [in] A specific error code.\r
178 *\r
179 *       p_final_status\r
180 *               [in] The final status.\r
181 *\r
182 *       p_insertion_string\r
183 *               [in] String to print.\r
184 *\r
185 *       p_n_data_items\r
186 *               [in] Number of data items\r
187 *\r
188 *       ...\r
189 *               [in] data items values\r
190 *\r
191 * RETURN VALUE\r
192 *       This function does not return a value.\r
193 *\r
194 * NOTES\r
195 *       cl_event_log_write is available in both debug and release builds.\r
196 *\r
197 *       The function uses IoAllocateErrorLogEntry and IoWriteErrorLogEntry\r
198 *       functions to send data to System Event Log.\r
199 *\r
200 * SEE ALSO\r
201 *       \r
202 *********/\r
203 \r
204 #ifdef __cplusplus\r
205 }\r
206 #endif\r
207 \r
208 #ifdef CL_KERNEL\r
209 #include <ntddk.h>\r
210 #define NTSTRSAFE_LIB\r
211 #include <ntstrsafe.h>\r
212 \r
213 #define CL_LOG_BUF_LEN          512\r
214 extern WCHAR g_cl_wlog[ CL_LOG_BUF_LEN ]; \r
215 extern UCHAR g_cl_slog[ CL_LOG_BUF_LEN ]; \r
216 \r
217 static void __build_str( const char *   format, ... )\r
218 {\r
219         NTSTATUS status;\r
220         va_list p_arg;\r
221         va_start(p_arg, format);\r
222         status = RtlStringCbVPrintfA((char *)g_cl_slog, sizeof(g_cl_slog), format , p_arg);\r
223         if (status)\r
224                 goto end;\r
225         status = RtlStringCchPrintfW(g_cl_wlog, sizeof(g_cl_wlog)/sizeof(g_cl_wlog[0]), L"%S", g_cl_slog);\r
226         if (status)\r
227                 goto end;\r
228 end:\r
229         va_end(p_arg);\r
230 }\r
231 \r
232 #define CL_PRINT_TO_EVENT_LOG(_obj_,_event_id_,_msg_)  \\r
233         if (_obj_) \\r
234         { \\r
235                 NTSTATUS event_id = _event_id_; \\r
236                 __build_str _msg_; \\r
237                 cl_event_log_write( _obj_, (ULONG)event_id, 0, 0, g_cl_wlog, 0, 0 ); \\r
238         }\r
239 #else\r
240 \r
241 #define CL_PRINT_TO_EVENT_LOG(_obj_,_event_id_,_msg_)\r
242 \r
243 #endif\r
244 \r
245 #endif  /* _CL_LOG_H_ */\r