pupnp (libupnp) snapshot from SourceForge: git clone git://pupnp.git.sourceforge...
[igd2-for-linux:pandonghui1211s-igd2-for-linux.git] / pupnp_branch-1.6.x / upnp / inc / upnpdebug.h
1 /*******************************************************************************
2  *
3  * Copyright (c) 2000-2003 Intel Corporation 
4  * Copyright (c) 2006 RĂ©mi Turboult <r3mi@users.sourceforge.net>
5  * All rights reserved. 
6  *
7  * Redistribution and use in source and binary forms, with or without 
8  * modification, are permitted provided that the following conditions are met: 
9  *
10  * * Redistributions of source code must retain the above copyright notice, 
11  * this list of conditions and the following disclaimer. 
12  * * Redistributions in binary form must reproduce the above copyright notice, 
13  * this list of conditions and the following disclaimer in the documentation 
14  * and/or other materials provided with the distribution. 
15  * * Neither name of Intel Corporation nor the names of its contributors 
16  * may be used to endorse or promote products derived from this software 
17  * without specific prior written permission.
18  * 
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
27  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  *
31  ******************************************************************************/
32
33 #ifndef UPNP_DEBUG_H
34 #define UPNP_DEBUG_H 
35
36 #include "upnp.h"
37 #include "upnpconfig.h"
38
39 #include <stdio.h>
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45
46 /** @name Other debugging features
47           The UPnP SDK contains other features to aid in debugging.
48  */
49
50 /*! @{ */
51
52 /** @name Upnp_LogLevel
53  *  The user has the option to select 4 different types of debugging levels,
54  *  see {\tt UpnpSetLogLevel}. 
55  *  The critical level will show only those messages 
56  *  which can halt the normal processing of the library, like memory 
57  *  allocation errors. The remaining three levels are just for debugging 
58  *  purposes.  Packet level will display all the incoming and outgoing 
59  *  packets that are flowing between the control point and the device. 
60  *  Info Level displays the other important operational information 
61  *  regarding the working of the library. If the user selects All, 
62  *  then the library displays all the debugging information that it has.
63  *  \begin{itemize}
64  *    \item {\tt UPNP_CRITICAL [0]}
65  *    \item {\tt UPNP_PACKET [1]}
66  *    \item {\tt UPNP_INFO [2]}
67  *    \item {\tt UPNP_ALL [3]}
68  *  \end{itemize}
69  */
70
71 typedef enum Upnp_Module {
72         SSDP,
73         SOAP,
74         GENA,
75         TPOOL,
76         MSERV,
77         DOM,
78         API,
79         HTTP
80 } Dbg_Module;
81
82 /*! @{ */
83 typedef enum Upnp_LogLevel_e {
84         UPNP_CRITICAL,
85         UPNP_PACKET,
86         UPNP_INFO,
87         UPNP_ALL
88 } Upnp_LogLevel;
89 /*! @} */
90
91
92 /**
93  * Default log level : see {\tt Upnp_LogLevel}
94  */
95 #define UPNP_DEFAULT_LOG_LEVEL  UPNP_ALL
96
97
98
99 /***************************************************************************
100  * Function : UpnpInitLog
101  *
102  * Parameters:  void
103  *
104  * Description:
105  *      This functions initializes the log files
106  *
107  * Returns: int
108  *      -1 : If fails
109  *      UPNP_E_SUCCESS : if success
110  ***************************************************************************/
111 #ifdef DEBUG
112 int UpnpInitLog();
113 #else
114 static UPNP_INLINE int UpnpInitLog() { return UPNP_E_SUCCESS; }
115 #endif
116
117
118 /***************************************************************************
119  * Function : UpnpSetLogLevel
120  *                              
121  * Parameters: Upnp_LogLevel log_level
122  *
123  * Description:                                                 
124  *      This functions set the log level (see {\tt Upnp_LogLevel}
125  * Returns: void
126  ***************************************************************************/
127 #ifdef DEBUG
128 void UpnpSetLogLevel(Upnp_LogLevel log_level);
129 #else
130 static UPNP_INLINE void UpnpSetLogLevel(Upnp_LogLevel log_level) {}
131 #endif
132
133
134 /***************************************************************************
135  * Function : UpnpCloseLog                                              
136  *                                                              
137  * Parameters:  void                                    
138  *                                                              
139  * Description:                                                 
140  *      This functions closes the log files
141  * Returns: void
142  ***************************************************************************/
143 #ifdef DEBUG
144 void UpnpCloseLog();
145 #else
146 static UPNP_INLINE void UpnpCloseLog() {}
147 #endif
148
149
150 /***************************************************************************
151  * Function : UpnpSetLogFileNames               
152  *                                                      
153  * Parameters:                                          
154  *      IN const char* ErrFileName: name of the error file
155  *      IN const char *InfoFileName: name of the information file
156  *      IN int size: Size of the buffer
157  *      IN int starLength: This parameter provides the width of the banner
158  *                                                              
159  * Description:                                                 
160  *      This functions takes the buffer and writes the buffer in the file as 
161  *      per the requested banner        
162  * Returns: void
163  ***************************************************************************/
164 #ifdef DEBUG
165 void UpnpSetLogFileNames(
166         const char *ErrFileName,
167         const char *InfoFileName);
168 #else
169 static UPNP_INLINE void UpnpSetLogFileNames(
170         const char *ErrFileName,
171         const char *InfoFileName) {}
172 #endif
173
174
175 /***************************************************************************
176  * Function : UpnpGetDebugFile          
177  *                                              
178  * Parameters:                                  
179  *      IN Upnp_LogLevel DLevel: The level of the debug logging. It will decide 
180  *              whether debug statement will go to standard output, 
181  *              or any of the log files.
182  *      IN Dbg_Module Module: debug will go in the name of this module
183  *                                                              
184  * Description:
185  *      This function checks if the module is turned on for debug 
186  *      and returns the file descriptor corresponding to the debug level
187  * Returns: FILE *
188  *      NULL : if the module is turn off for debug 
189  *      else returns the right file descriptor
190  ***************************************************************************/
191 #ifdef DEBUG
192 FILE *UpnpGetDebugFile(Upnp_LogLevel level, Dbg_Module module);
193 #else
194 static UPNP_INLINE FILE *UpnpGetDebugFile(Upnp_LogLevel level, Dbg_Module module)
195 {
196         return NULL;
197 }
198 #endif
199
200
201 /***************************************************************************
202  * Function : DebugAtThisLevel                                  
203  *                                                                      
204  * Parameters:                  
205  *      IN Upnp_LogLevel DLevel: The level of the debug logging. It will decide 
206  *              whether debug statement will go to standard output, 
207  *              or any of the log files.
208  *      IN Dbg_Module Module: debug will go in the name of this module
209  *                                      
210  * Description:                                 
211  *      This functions returns true if debug output should be done in this
212  *      module.
213  *
214  * Returns: int
215  ***************************************************************************/
216 #ifdef DEBUG
217 int DebugAtThisLevel(
218         IN Upnp_LogLevel DLevel,
219         IN Dbg_Module Module);
220 #else
221 static UPNP_INLINE int DebugAtThisLevel(
222         IN Upnp_LogLevel DLevel,
223         IN Dbg_Module Module) { return 0; }
224 #endif
225
226
227 /***************************************************************************
228  * Function : UpnpPrintf                                
229  *                                                                      
230  * Parameters:                                                          
231  *      IN Upnp_LogLevel DLevel: The level of the debug logging. It will decide 
232  *              whether debug statement will go to standard output, 
233  *              or any of the log files.
234  *      IN Dbg_Module Module: debug will go in the name of this module
235  *      IN char *DbgFileName: Name of the file from where debug statement is
236  *                                                      coming
237  *      IN int DbgLineNo : Line number of the file from where debug statement 
238  *                              is coming
239  *      IN char * FmtStr, ...: Variable number of arguments that will go 
240  *                              in the debug statement
241  *                                      
242  * Description:                                                 
243  *      This functions prints the debug statement either on the startdard 
244  *      output or log file along with the information from where this 
245  *      debug statement is coming
246  * Returns: void
247  ***************************************************************************/ 
248 #ifdef DEBUG
249 void UpnpPrintf(
250         Upnp_LogLevel DLevel,
251         Dbg_Module Module,
252         const char* DbgFileName,
253         int DbgLineNo,
254         const char* FmtStr,
255         ...)
256 #if (__GNUC__ >= 3)
257         /* This enables printf like format checking by the compiler */
258         __attribute__((format (__printf__, 5, 6)))
259 #endif
260 ;
261 #else /* DEBUG */
262 static UPNP_INLINE void UpnpPrintf(
263         Upnp_LogLevel DLevel,
264         Dbg_Module Module,
265         const char* DbgFileName,
266         int DbgLineNo,
267         const char* FmtStr,
268         ...) {}
269 #endif /* DEBUG */
270
271
272 /***************************************************************************
273  * Function : UpnpDisplayBanner                         
274  *                                                      
275  * Parameters:                                                  
276  *      IN FILE *fd: file descriptor where the banner will be written
277  *      IN char **lines: The buffer that will be written
278  *      IN int size: Size of the buffer
279  *      IN int starLength: This parameter provides the width of the banner
280  *                                                                      
281  * Description:                                                 
282  *      This functions takes the buffer and writes the buffer in the file as 
283  *      per the requested banner                        
284  * Returns: void
285  ***************************************************************************/
286 #ifdef DEBUG
287 void UpnpDisplayBanner(
288         FILE *fd,
289         const char **lines,
290         size_t size,
291         int starlength);
292 #else
293 static UPNP_INLINE void UpnpDisplayBanner(
294         FILE *fd,
295         const char **lines,
296         size_t size,
297         int starlength) {}
298 #endif
299
300
301 /***************************************************************************
302  * Function : UpnpDisplayFileAndLine                            
303  *                                                              
304  * Parameters:                                                  
305  *      IN FILE *fd: File descriptor where line number and file name will be 
306  *                      written 
307  *      IN char *DbgFileName: Name of the file  
308  *      IN int DbgLineNo : Line number of the file
309  *                                                              
310  * Description:
311  *      This function writes the file name and file number from where
312  *              debug statement is coming to the log file
313  * Returns: void
314  ***************************************************************************/
315 #ifdef DEBUG
316 void UpnpDisplayFileAndLine(
317         FILE *fd,
318         const char *DbgFileName,
319         int DbgLineNo);
320 #else
321 static UPNP_INLINE void UpnpDisplayFileAndLine(
322         FILE *fd,
323         const char *DbgFileName,
324         int DbgLineNo) {}
325 #endif
326
327 /*! @} */
328
329 #ifdef __cplusplus
330 }
331 #endif
332
333 #endif /* UPNP_DEBUG_H */
334