RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
osapi_log.h
1 /*
2  * FILE: osapi_log.h - Logging API
3  *
4  * (c) Copyright, Real-Time Innovations, 2008-2015.
5  *
6  * All rights reserved.
7  *
8  * No duplications, whole or partial, manual or electronic, may be made
9  * without express written permission. Any such copies, or
10  * revisions thereof, must display this notice unaltered.
11  * This code contains trade secrets of Real-Time Innovations, Inc.
12  *
13  * modification history
14  * --------------------
15  * 04nov2015,tk MICRO-1505 Reduce memory footprint
16  * 02dec2014,tk MICRO-9763/PR#12922 Added documentation for log-entry use
17  * 16sep2014,tk MICRO-887/PR#10752 Removed reference to removed function
18  * 22sep2011,tk Updated
19  * 23sep2008,yy Created
20  *
21  */
22 /*ci
23  * \file
24  * \brief OSAPI Log API
25  * \addtogroup OSAPILogClass OSAPI Logging
26  */
27 #ifndef osapi_log_h
28 #define osapi_log_h
29 
30 #ifndef osapi_dll_h
31 #include "osapi/osapi_dll.h"
32 #endif /* */
33 #ifndef osapi_thread_h
34 #include "osapi/osapi_thread.h"
35 #endif /* */
36 #ifndef osapi_heap_h
37 #include "osapi/osapi_heap.h"
38 #endif /* */
39 #ifndef osapi_system_h
40 #include "osapi/osapi_system.h"
41 #endif /* */
42 
43 #ifdef __cplusplus
44 extern "C"
45 {
46 #endif
47 
48 /******************************************************************************
49  * OSAPI Error codes
50  ******************************************************************************/
51 
52 #ifndef RTI_MODULE_NAME
53 #define RTI_MODULE_NAME "undefined"
54 #endif
55 
56 #define OSAPI_LOG_MSG_PN_X2_STD_PARAM RTI_MODULE_NAME,\
57  __FILE__,__FUNCTION__, __LINE__
58 
59 #if OSAPI_ENABLE_LOG
60 #define OSAPI_LOG_ENTRY_CREATE(kind_,error_code_,p_,is_finale_)\
61  OSAPI_Log_entry_create(kind_,error_code_,p_,is_finale_);
62 
63 #define OSAPI_LOG_ENTRY_ADD(kind_,error_code_,p_)\
64  OSAPI_Log_entry_add(kind_,error_code_,p_);
65 
66 #define OSAPI_LOG_ENTRY_ADD_INT(name_,value_,is_final_)\
67  OSAPI_Log_entry_add_int(name_,value_,is_final_);
68 
69 #define OSAPI_LOG_ENTRY_ADD_STRING(name_,value_,is_final_)\
70  OSAPI_Log_entry_add_string(name_,value_,is_final_);
71 
72 #define OSAPI_LOG_ENTRY_ADD_POINTER(name_,value_,is_final_)\
73  OSAPI_Log_entry_add_pointer(name_,value_,is_final_);\
74 
75 #define OSAPI_LOG_ENTRY_ADD_1STRING_1INT(kind_,error_code_,p_,s_name_,s_value_,i_name_,i_value_)\
76  OSAPI_Log_entry_add_1string_1int(kind_,error_code_,p_,s_name_,s_value_,i_name_,i_value_);
77 
78 #define OSAPI_LOG_ENTRY_ADD_1POINTER(kind_,error_code_,p_,name_,value_)\
79  OSAPI_Log_entry_add_1pointer(kind_,error_code_,p_,name_,value_);
80 
81 #define OSAPI_LOG_ENTRY_ADD_1STRING(kind_,error_code_,p_,name_,value_)\
82  OSAPI_Log_entry_add_1string(kind_,error_code_,p_,name_,value_);
83 
84 #define OSAPI_LOG_ENTRY_ADD_2STRING(kind_,error_code_,p_,name1_,value1_,name2_,value2_)\
85  OSAPI_Log_entry_add_2string(kind_,error_code_,p_,name1_,value1_,name2_,value2_);
86 
87 #define OSAPI_LOG_ENTRY_ADD_1INT(kind_,error_code_,p_,name1_,value1_)\
88  OSAPI_Log_entry_add_1int(kind_,error_code_,p_,name1_,value1_);
89 
90 #define OSAPI_LOG_ENTRY_ADD_2INT(kind_,error_code_,p_,name1_,value1_,name2_,value2_)\
91  OSAPI_Log_entry_add_2int(kind_,error_code_,p_,name1_,value1_,name2_,value2_);
92 
93 #define OSAPI_LOG_ENTRY_ADD_3INT(kind_,error_code_,p_,name1_,value1_,name2_,value2_,name3_,value3_)\
94  OSAPI_Log_entry_add_3int(kind_,error_code_,p_,name1_,value1_,name2_,value2_,name3_,value3_);
95 #else
96 #define OSAPI_LOG_ENTRY_CREATE(kind_,error_code_,p_,is_finale_)
97 #define OSAPI_LOG_ENTRY_ADD_INT(name_,value_,is_final_)
98 #define OSAPI_LOG_ENTRY_ADD_STRING(name_,value_,is_final_)
99 #define OSAPI_LOG_ENTRY_ADD_POINTER(name_,value_,is_final_)
100 #define OSAPI_LOG_ENTRY_ADD_1STRING_1INT(kind_,error_code_,p_,s_name_,s_value_,i_name_,i_value_)
101 #define OSAPI_LOG_ENTRY_ADD_1POINTER(kind_,error_code_,p_,name_,value_)
102 #define OSAPI_LOG_ENTRY_ADD_1STRING(kind_,error_code_,p_,name_,value_)
103 #define OSAPI_LOG_ENTRY_ADD_2STRING(kind_,error_code_,p_,name1_,value1_,name2_,value2_)
104 #define OSAPI_LOG_ENTRY_ADD_1INT(kind_,error_code_,p_,name1_,value1_)
105 #define OSAPI_LOG_ENTRY_ADD_2INT(kind_,error_code_,p_,name1_,value1_,name2_,value2_)
106 #define OSAPI_LOG_ENTRY_ADD_3INT(kind_,error_code_,p_,name1_,value1_,name2_,value2_,name3_,value3_)
107 #define OSAPI_LOG_ENTRY_ADD(kind_,error_code_,p_)
108 #endif
109 
110 /*ce
111  * \defgroup OSAPILogCodesClass OSAPI
112  * \ingroup LoggingModule
113  *
114  * \details
115  * The logging API provides a number of functions for logging different
116  * types of events. There are 3 types of events:
117  *
118  * info - This type is for informational purposes
119  *
120  * warning - This type does not necessarily cause any functional behavior,
121  * but could indicate an unexpected situation has been handled
122  * or performance could be affected.
123  *
124  * error - This indicated an error condition that has functional impact
125  * and could not be dealt with.
126  *
127  * \brief OS API. ModuleID = 0
128  */
129 
130 /******************************************************************************
131  * OSAPI Log Modules
132  ******************************************************************************/
133 /*ce \def OSAPI_LOG_BASE
134  * \brief Log Id base-number
135  */
136 #define OSAPI_LOG_BASE (0)
137 
138 /*ce \def REDA_LOG_BASE
139  * \brief REDA Module
140  */
141 #define REDA_LOG_BASE (1 << 16)
142 
143 /*ce \def DB_LOG_BASE
144  * \brief DB Module
145  */
146 #define DB_LOG_BASE (2 << 16)
147 
148 /*ce \def RT_LOG_BASE
149  * \brief RT Module
150  */
151 #define RT_LOG_BASE (3 << 16)
152 
153 /*ce \def NETIO_LOG_BASE
154  * \brief NETIO Module
155  */
156 #define NETIO_LOG_BASE (4 << 16)
157 
158 /*ce \def UDP_LOG_BASE
159  * \brief UDP Module, same as NETIO
160  */
161 #define UDP_LOG_BASE NETIO_LOG_BASE
162 
163 /*ce \def CDR_LOG_BASE
164  * \brief CDR Module
165  */
166 #define CDR_LOG_BASE (5 << 16)
167 
168 /*ce \def RTPS_LOG_BASE
169  * \brief RTPS Module
170  */
171 #define RTPS_LOG_BASE (6 << 16)
172 
173 /*ce \def DDSC_LOG_BASE
174  * \brief DDS_C Module
175  */
176 #define DDSC_LOG_BASE (7 << 16)
177 
178 /*ce \def RHSM_LOG_BASE
179  * \brief RHSM Module
180  */
181 #define RHSM_LOG_BASE (8 << 16)
182 
183 /*ce \def WHSM_LOG_BASE
184  * \brief WHSM Module
185  */
186 #define WHSM_LOG_BASE (9 << 16)
187 
188 /*ce \def DPSE_LOG_BASE
189  * \brief DPSE Module
190  */
191 #define DPSE_LOG_BASE (10 << 16)
192 
193 /*ce \def DPDE_LOG_BASE
194  * \brief DPDE Module
195  */
196 #define DPDE_LOG_BASE (11 << 16)
197 
198 /*ce
199  * \brief Retrieving the next error code failed
200  * \ingroup OSAPILogCodesClass
201  */
202 #define OSAPI_LOG_GET_NEXT_OBJECT_ID_EC (OSAPI_LOG_BASE + 1)
203 #define OSAPI_LOG_GET_NEXT_OBJECT_ID(level_) \
204 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_GET_NEXT_OBJECT_ID_EC ,\
205  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
206 
207 /* System messages */
208 
209 /*ce
210  * \brief An error occured while setting the system properties
211  * \ingroup OSAPILogCodesClass
212  */
213 #define OSAPI_LOG_SYSTEM_SET_PROPERTY_EC (OSAPI_LOG_BASE + 2)
214 #define OSAPI_LOG_SYSTEM_SET_PROPERTY(level_) \
215 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_SYSTEM_SET_PROPERTY_EC,\
216  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
217 
218 /*ce
219  * \brief An error occured when starting the system timer
220  * \ingroup OSAPILogCodesClass
221  */
222 #define OSAPI_LOG_SYSTEM_TIMER_START_EC (OSAPI_LOG_BASE + 4)
223 #define OSAPI_LOG_SYSTEM_TIMER_START(level_) \
224 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_SYSTEM_TIMER_START_EC,\
225  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
226 
227 /*ce
228  * \brief An error occured when stopping the system timer
229  * \ingroup OSAPILogCodesClass
230  */
231 #define OSAPI_LOG_SYSTEM_TIMER_STOP_EC (OSAPI_LOG_BASE + 5)
232 #define OSAPI_LOG_SYSTEM_TIMER_STOP(level_) \
233 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_SYSTEM_TIMER_STOP_EC,\
234  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
235 
236 /* THREAD message */
237 /*ce
238  * \brief An error when allocating the a thread object
239  * \ingroup OSAPILogCodesClass
240  */
241 #define OSAPI_LOG_THREAD_NEW_EC (OSAPI_LOG_BASE + 6)
242 #define OSAPI_LOG_THREAD_NEW(level_) \
243 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_THREAD_NEW_EC,\
244  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
245 
246 /*ce
247  * \brief An error when creating the a thread object
248  * \ingroup OSAPILogCodesClass
249  */
250 #define OSAPI_LOG_THREAD_CREATE_EC (OSAPI_LOG_BASE + 7)
251 #define OSAPI_LOG_THREAD_CREATE(level_) \
252 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_THREAD_CREATE_EC,\
253  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
254 
255 /*ce
256  * \brief An error when creating thread sync semaphore
257  * \ingroup OSAPILogCodesClass
258  */
259 #define OSAPI_LOG_THREAD_SEM_EC (OSAPI_LOG_BASE + 8)
260 #define OSAPI_LOG_THREAD_SEM(level_,cs_,ss_) \
261 OSAPI_LOG_ENTRY_CREATE((level_),OSAPI_LOG_THREAD_SEM_EC,\
262  OSAPI_LOG_MSG_PN_X2_STD_PARAM,RTI_FALSE)\
263  OSAPI_LOG_ENTRY_ADD_POINTER("cs",(cs_),RTI_FALSE)\
264  OSAPI_LOG_ENTRY_ADD_POINTER("ss",(ss_),RTI_TRUE)
265 
266 /*ce
267  * \brief Failed to signal that a thread has been created
268  * \ingroup OSAPILogCodesClass
269  */
270 #define OSAPI_LOG_THREAD_EXEC_CREATE_EC (OSAPI_LOG_BASE + 9)
271 #define OSAPI_LOG_THREAD_EXEC_CREATE(level_) \
272 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_THREAD_EXEC_CREATE_EC,\
273  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
274 
275 /*ce
276  * \brief Failed to signal the start a created thread
277  * \ingroup OSAPILogCodesClass
278  */
279 #define OSAPI_LOG_THREAD_EXEC_START_EC (OSAPI_LOG_BASE + 10)
280 #define OSAPI_LOG_THREAD_EXEC_START(level_,ss_) \
281 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_THREAD_EXEC_START_EC,\
282  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"ss",(ss_))
283 
284 /*ce
285  * \brief Failed to start a thread
286  * \ingroup OSAPILogCodesClass
287  */
288 #define OSAPI_LOG_THREAD_START_EC (OSAPI_LOG_BASE + 11)
289 #define OSAPI_LOG_THREAD_START(level_,ss_) \
290 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_THREAD_START_EC,\
291  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"ss",(ss_))
292 
293 /*ce
294  * \brief Failed to destroy a thread
295  * \ingroup OSAPILogCodesClass
296  */
297 #define OSAPI_LOG_THREAD_DESTROY_EC (OSAPI_LOG_BASE + 12)
298 #define OSAPI_LOG_THREAD_DESTROY(level_,ss_) \
299 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_THREAD_DESTROY_EC,\
300  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"ss",(ss_))
301 
302 /*ce
303  * \brief Failed to start an unstarted thread being destroyed
304  * \ingroup OSAPILogCodesClass
305  */
306 #define OSAPI_LOG_THREAD_DESTROY_NO_START_EC (OSAPI_LOG_BASE + 13)
307 #define OSAPI_LOG_THREAD_DESTROY_NO_START(level_,ss_) \
308 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_THREAD_DESTROY_NO_START_EC,\
309  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"ss",(ss_))
310 
311 /*ce
312  * \brief Failed wakeup of a thread being destroyed
313  * \ingroup OSAPILogCodesClass
314  */
315 #define OSAPI_LOG_THREAD_DESTROY_NO_WAKEUP_EC (OSAPI_LOG_BASE + 14)
316 #define OSAPI_LOG_THREAD_DESTROY_NO_WAKEUP(level_,ss_) \
317 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_THREAD_DESTROY_NO_WAKEUP_EC,\
318  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"ss",(ss_))
319 
320 /*ce
321  * \brief Failed initializing a thread
322  * \ingroup OSAPILogCodesClass
323  */
324 #define OSAPI_LOG_THREAD_INIT_EC (OSAPI_LOG_BASE + 15)
325 #define OSAPI_LOG_THREAD_INIT(level_,sysrc_) \
326 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_THREAD_INIT_EC,\
327  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
328 
329 
330 /*ce
331  * \brief Failed to set scheduling policy of a thread
332  * \ingroup OSAPILogCodesClass
333  */
334 #define OSAPI_LOG_THREAD_SCHEDPARAM_EC (OSAPI_LOG_BASE + 16)
335 #define OSAPI_LOG_THREAD_SCHEDPARAM(level_,sysrc_,prio_) \
336 OSAPI_LOG_ENTRY_ADD_2INT((level_),OSAPI_LOG_THREAD_SCHEDPARAM_EC ,\
337  OSAPI_LOG_MSG_PN_X2_STD_PARAM,\
338  "sysrc",(sysrc_),"prio",(prio_))
339 
340 /*ce
341  * \brief Failed to get the scheduling policy of a thread
342  * \ingroup OSAPILogCodesClass
343  */
344 #define OSAPI_LOG_THREAD_GET_POLICY_EC (OSAPI_LOG_BASE + 17)
345 #define OSAPI_LOG_THREAD_GET_POLICY(level_,sysrc_) \
346 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_THREAD_GET_POLICY_EC,\
347  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
348 
349 /*ce
350  * \brief Mismatch of scheduling policy of a created thread and the application
351  * thread
352  * \ingroup OSAPILogCodesClass
353  */
354 #define OSAPI_LOG_THREAD_POLICY_DIFFER_EC (OSAPI_LOG_BASE + 18)
355 #define OSAPI_LOG_THREAD_POLICY_DIFFER(level_,get_policy_,set_policy_) \
356 OSAPI_LOG_ENTRY_ADD_2INT((level_),OSAPI_LOG_THREAD_POLICY_DIFFER_EC,\
357  OSAPI_LOG_MSG_PN_X2_STD_PARAM,\
358  "get_policy",(get_policy_),"set_policy",(set_policy_))
359 
360 /*ce
361  * \brief Failed to map to native thread priority values
362  * \ingroup OSAPILogCodesClass
363  */
364 #define OSAPI_LOG_THREAD_PRIORITY_MAP_EC (OSAPI_LOG_BASE + 19)
365 #define OSAPI_LOG_THREAD_PRIORITY_MAP(level_,min_,max_) \
366 OSAPI_LOG_ENTRY_ADD_2INT((level_),OSAPI_LOG_THREAD_PRIORITY_MAP_EC,\
367  OSAPI_LOG_MSG_PN_X2_STD_PARAM,\
368  "min",(min_),"max",(max_))
369 
370 /* TIMER messages */
371 
372 /*ce
373  * \brief Failed to delete the Timer object
374  * \ingroup OSAPILogCodesClass
375  */
376 #define OSAPI_LOG_TIMER_DELETE_EC (OSAPI_LOG_BASE + 20)
377 #define OSAPI_LOG_TIMER_DELETE(level_) \
378 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_TIMER_DELETE_EC,\
379  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
380 
381 #define OSAPI_LOG_TIMER_TICK_EC (OSAPI_LOG_BASE + 21)
382 
383 /*ce
384  * \brief Failed taking or giving the Timer mutex
385  * \ingroup OSAPILogCodesClass
386  */
387 #define OSAPI_LOG_TIMER_TICK_MUTEX_EC (OSAPI_LOG_BASE + 22)
388 #define OSAPI_LOG_TIMER_TICK_MUTEX(level_,mutex_,take_) \
389 OSAPI_LOG_ENTRY_CREATE((level_),OSAPI_LOG_TIMER_TICK_MUTEX_EC,\
390  OSAPI_LOG_MSG_PN_X2_STD_PARAM,RTI_FALSE)\
391 OSAPI_LOG_ENTRY_ADD_POINTER("mutex",(mutex_),RTI_FALSE)\
392 OSAPI_LOG_ENTRY_ADD_INT("take",(take_),RTI_TRUE)
393 
394 #define OSAPI_LOG_TIMER_CREATE_TIMEOUT_EC (OSAPI_LOG_BASE + 23)
395 
396 #define OSAPI_LOG_TIMER_UPDATE_TIMEOUT_EC (OSAPI_LOG_BASE + 24)
397 
398 #define OSAPI_LOG_TIMER_DELETE_TIMEOUT_EC (OSAPI_LOG_BASE + 25)
399 
400 
401 /*ce
402  * \brief Failed to return user data for a timeout due to mismatched epochs
403  * \ingroup OSAPILogCodesClass
404  */
405 #define OSAPI_LOG_TIMER_GET_USER_DATA_EPOCH_EC (OSAPI_LOG_BASE + 27)
406 #define OSAPI_LOG_TIMER_GET_USER_DATA_EPOCH(level_,h_,e_,e1_,e2_) \
407 OSAPI_LOG_ENTRY_CREATE( (level_),OSAPI_LOG_TIMER_GET_USER_DATA_EPOCH_EC,\
408  OSAPI_LOG_MSG_PN_X2_STD_PARAM,RTI_FALSE)\
409  OSAPI_LOG_ENTRY_ADD_POINTER("h",(h_),RTI_FALSE)\
410  OSAPI_LOG_ENTRY_ADD_POINTER("e",(e_),RTI_FALSE)\
411  OSAPI_LOG_ENTRY_ADD_INT("e1",(e1_),RTI_FALSE)\
412  OSAPI_LOG_ENTRY_ADD_INT("e2",(e2_),RTI_TRUE)
413 /*ce
414  * \brief Failed to allocate memory for a new Timer
415  * \ingroup OSAPILogCodesClass
416  */
417 #define OSAPI_LOG_TIMER_NEW_EC (OSAPI_LOG_BASE + 28)
418 #define OSAPI_LOG_TIMER_NEW(level_) \
419 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_TIMER_NEW_EC,\
420  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
421 
422 /*ce
423  * \brief Failed to allocate memory for a new Timer entry
424  * \ingroup OSAPILogCodesClass
425  */
426 #define OSAPI_LOG_TIMER_NEW_ENTRY_EC (OSAPI_LOG_BASE + 29)
427 #define OSAPI_LOG_TIMER_NEW_ENTRY(level_) \
428 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_TIMER_NEW_ENTRY_EC,\
429  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
430 
431 /*ce
432  * \brief Failed to allocate memory for a new Timer wheel
433  * \ingroup OSAPILogCodesClass
434  */
435 #define OSAPI_LOG_TIMER_NEW_WHEEL_EC (OSAPI_LOG_BASE + 30)
436 #define OSAPI_LOG_TIMER_NEW_WHEEL(level_,slots_) \
437 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_TIMER_NEW_WHEEL_EC,\
438  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"slots",(slots_))
439 
440 /*ce
441  * \brief Failed to create a new Timer mutex
442  * \ingroup OSAPILogCodesClass
443  */
444 #define OSAPI_LOG_TIMER_NEW_MUTEX_EC (OSAPI_LOG_BASE + 31)
445 #define OSAPI_LOG_TIMER_NEW_MUTEX(level_) \
446 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_TIMER_NEW_MUTEX_EC,\
447  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
448 
449 /*ce
450  * \brief Failed to start a new Timer being created
451  * \ingroup OSAPILogCodesClass
452  */
453 #define OSAPI_LOG_TIMER_NEW_START_TIMER_EC (OSAPI_LOG_BASE + 32)
454 #define OSAPI_LOG_TIMER_NEW_START_TIMER(level_,timer_,ticr_) \
455 OSAPI_LOG_ENTRY_CREATE((level_),OSAPI_LOG_TIMER_NEW_START_TIMER_EC,\
456  OSAPI_LOG_MSG_PN_X2_STD_PARAM,RTI_FALSE)\
457  OSAPI_LOG_ENTRY_ADD_POINTER("timer",(timer_),RTI_FALSE)\
458  OSAPI_LOG_ENTRY_ADD_POINTER("ticr",(ticr_),RTI_TRUE)
459 
460 /*ce
461  * \brief Failed to stop a Timer being deleted
462  * \ingroup OSAPILogCodesClass
463  */
464 #define OSAPI_LOG_TIMER_DELETE_STOP_TIMER_EC (OSAPI_LOG_BASE + 33)
465 #define OSAPI_LOG_TIMER_DELETE_STOP_TIMER(level_,timer_) \
466 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_TIMER_DELETE_STOP_TIMER_EC,\
467  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"timer",(timer_))
468 
469 /*ce
470  * \brief Failed to delete the Timer mutex
471  * \ingroup OSAPILogCodesClass
472  */
473 #define OSAPI_LOG_TIMER_DELETE_MUTEX_EC (OSAPI_LOG_BASE + 34)
474 #define OSAPI_LOG_TIMER_DELETE_MUTEX(level_,timer_) \
475 OSAPI_LOG_ENTRY_ADD_1POINTER((level_),OSAPI_LOG_TIMER_DELETE_MUTEX_EC,\
476  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"timer",(timer_))
477 
478 /*ce
479  * \brief Failed to take or give a Timer mutex
480  * \ingroup OSAPILogCodesClass
481  */
482 #define OSAPI_LOG_TIMER_MUTEX_EC (OSAPI_LOG_BASE + 35)
483 #define OSAPI_LOG_TIMER_MUTEX(level_,mutex_,take_) \
484  OSAPI_LOG_ENTRY_CREATE((level_),OSAPI_LOG_TIMER_MUTEX_EC,OSAPI_LOG_MSG_PN_X2_STD_PARAM,RTI_FALSE)\
485  OSAPI_LOG_ENTRY_ADD_POINTER("mutex",(mutex_),RTI_FALSE)\
486  OSAPI_LOG_ENTRY_ADD_INT("take",(take_),RTI_TRUE)
487 
488 /* Semaphore messages */
489 
490 /*ce
491  * \brief Failed to delete a semaphore
492  * \ingroup OSAPILogCodesClass
493  */
494 #define OSAPI_LOG_SEMAPHORE_DELETE_EC (OSAPI_LOG_BASE + 36)
495 #define OSAPI_LOG_SEMAPHORE_DELETE(level_,sysrc_) \
496 OSAPI_LOG_ENTRY_ADD_1INT( (level_),OSAPI_LOG_SEMAPHORE_DELETE_EC,\
497  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
498 
499 /*ce
500  * \brief Failed to create a semaphore
501  * \ingroup OSAPILogCodesClass
502  */
503 #define OSAPI_LOG_SEMAPHORE_NEW_EC (OSAPI_LOG_BASE + 37)
504 #define OSAPI_LOG_SEMAPHORE_NEW(level_) \
505 OSAPI_LOG_ENTRY_ADD( (level_),OSAPI_LOG_SEMAPHORE_NEW_EC,\
506  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
507 
508 /*ce
509  * \brief Failed to initialize a new semaphore
510  * \ingroup OSAPILogCodesClass
511  */
512 #define OSAPI_LOG_SEMAPHORE_NEW_INIT_EC (OSAPI_LOG_BASE + 38)
513 #define OSAPI_LOG_SEMAPHORE_NEW_INIT(level_,sysrc_) \
514 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_SEMAPHORE_NEW_INIT_EC,\
515  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
516 
517 /*ce
518  * \brief Failed to give a semaphore
519  * \ingroup OSAPILogCodesClass
520  */
521 #define OSAPI_LOG_SEMAPHORE_GIVE_EC (OSAPI_LOG_BASE + 39)
522 #define OSAPI_LOG_SEMAPHORE_GIVE(level_,sysrc_) \
523 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_SEMAPHORE_GIVE_EC,\
524  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
525 
526 /*ce
527  * \brief Failed to take a semaphore
528  * \ingroup OSAPILogCodesClass
529  */
530 #define OSAPI_LOG_SEMAPHORE_TAKE_EC (OSAPI_LOG_BASE + 40)
531 #define OSAPI_LOG_SEMAPHORE_TAKE(level_,sysrc_) \
532 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_SEMAPHORE_TAKE_EC,\
533  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
534 
535 /* Mutex messages */
536 
537 /*ce
538  * \brief Failed to delete a mutex
539  * \ingroup OSAPILogCodesClass
540  */
541 #define OSAPI_LOG_MUTEX_DELETE_EC (OSAPI_LOG_BASE + 41)
542 #define OSAPI_LOG_MUTEX_DELETE(level_,sysrc_) \
543 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_MUTEX_DELETE_EC,\
544  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
545 
546 /*ce
547  * \brief Failed to create a mutex
548  * \ingroup OSAPILogCodesClass
549  */
550 #define OSAPI_LOG_MUTEX_NEW_EC (OSAPI_LOG_BASE + 42)
551 #define OSAPI_LOG_MUTEX_NEW(level_) \
552 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_MUTEX_NEW_EC,\
553  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
554 
555 /*ce
556  * \brief Failed to take a mutex
557  * \ingroup OSAPILogCodesClass
558  */
559 #define OSAPI_LOG_MUTEX_TAKE_EC (OSAPI_LOG_BASE + 43)
560 #define OSAPI_LOG_MUTEX_TAKE(level_,sysrc_) \
561 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_MUTEX_TAKE_EC,\
562  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
563 
564 /*ce
565  * \brief Failed to give a mutex
566  * \ingroup OSAPILogCodesClass
567  */
568 #define OSAPI_LOG_MUTEX_GIVE_EC (OSAPI_LOG_BASE + 44)
569 #define OSAPI_LOG_MUTEX_GIVE(level_,sysrc_) \
570 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_MUTEX_GIVE_EC,\
571  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
572 
573 /*ce
574  * \brief Failed to initialize a mutex
575  * \ingroup OSAPILogCodesClass
576  */
577 #define OSAPI_LOG_MUTEX_INIT_EC (OSAPI_LOG_BASE + 45)
578 #define OSAPI_LOG_MUTEX_INIT(level_,sysrc_) \
579 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_MUTEX_INIT_EC,\
580  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
581 
582 /* HEAP */
583 
584 /*ce
585  * \brief Failed to allocate a buffer from the heap
586  * \ingroup OSAPILogCodesClass
587  */
588 #define OSAPI_LOG_HEAP_INTERNAL_ALLOCATE_EC (OSAPI_LOG_BASE + 46)
589 #define OSAPI_LOG_HEAP_INTERNAL_ALLOCATE(level_,s_,a_) \
590 OSAPI_LOG_ENTRY_ADD_2INT((level_),OSAPI_LOG_HEAP_INTERNAL_ALLOCATE_EC,\
591  OSAPI_LOG_MSG_PN_X2_STD_PARAM,\
592  "s",(s_),"a",(a_))
593 
594 #define OSAPI_LOG_HEAP_FREE_EC (OSAPI_LOG_BASE + 47)
595 
596 /*ce
597  * \brief Failed to get current system time
598  * \ingroup OSAPILogCodesClass
599  */
600 #define OSAPI_LOG_SYSTEM_GET_TIME_EC (OSAPI_LOG_BASE + 48)
601 #define OSAPI_LOG_SYSTEM_GET_TIME(level_,sysrc_) \
602 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_SYSTEM_GET_TIME_EC,\
603  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"sysrc",(sysrc_))
604 
605 /*ce
606  * \brief Return the last recorded error-code for the calling thread
607  *
608  * \details
609  * This log-messages retrieves the last recorded error-code for the
610  * calling thread. It is used a function calls another function that
611  * fails.
612  *
613  * \ingroup OSAPILogCodesClass
614  */
615 #define OSAPI_LOG_LAST_RECORDED_ERROR_EC (OSAPI_LOG_BASE + 49)
616 #define OSAPI_LOG_LAST_RECORDED_ERROR(level_) \
617 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_LAST_RECORDED_ERROR_EC,\
618  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"rc",OSAPI_Log_get_last_error_code())
619 
620 /*ce
621  * \brief Failed to set the thread name in the OS
622  *
623  * \details
624  * When OSAPI starts a thread it also calls the OS to set the thread name. If this
625  * fails this warning message indicates why.
626  *
627  * \ingroup OSAPILogCodesClass
628  */
629 #define OSAPI_LOG_SET_THREAD_NAME_EC (OSAPI_LOG_BASE + 50)
630 #define OSAPI_LOG_SET_THREAD_NAME(level_,rc_) \
631 OSAPI_LOG_ENTRY_ADD_1INT((level_),OSAPI_LOG_SET_THREAD_NAME_EC,\
632  OSAPI_LOG_MSG_PN_X2_STD_PARAM,"rc",(rc_))
633 
634 /*ce
635  * \brief Failed to add a semaphore to the thread semaphore pool.
636  *
637  * \details
638  * This maximum number of semaphores are defined with
639  * OSAPI_SYSTEM_MAX_THREAD_SEMAPHORE osapi_config.h and can be overridden
640  * by compiling with -DOSAPI_SYSTEM_MAX_THREAD_SEMAPHORE=<N>. One semaphore
641  * is needed per reeive thread created.
642  *
643  * \ingroup OSAPILogCodesClass
644  */
645 #define OSAPI_LOG_THREAD_SEMPOOL_EXCEEDED_EC (OSAPI_LOG_BASE + 51)
646 #define OSAPI_LOG_THREAD_SEMPOOL_EXCEEDED(level_) \
647 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_THREAD_SEMPOOL_EXCEEDED_EC,\
648  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
649 
650 /*ce
651  * \brief Failed to delete a semaphore from the thread semaphore pool
652  *
653  * \details
654  * This is error indicates an imbalanced number of add/delete calls to the
655  * thread semaphore pool.
656  *
657  * \ingroup OSAPILogCodesClass
658  */
659 #define OSAPI_LOG_THREAD_SEMPOOL_INVALID_SEM_EC (OSAPI_LOG_BASE + 52)
660 #define OSAPI_LOG_THREAD_SEMPOOL_INVALID_SEM(level_) \
661 OSAPI_LOG_ENTRY_ADD((level_),OSAPI_LOG_THREAD_SEMPOOL_INVALID_SEM_EC,\
662  OSAPI_LOG_MSG_PN_X2_STD_PARAM)
663 
664 /******************************************************************************/
665 
666 #if OSAPI_ENABLE_LOG
667 /******************************************************************************
668  * Log types
669  ******************************************************************************/
670 /*ci
671  * \ingroup OSAPILogClass
672  * \brief Log message as an error
673  */
674 typedef enum
675 {
676  OSAPI_LOGKIND_ERROR = 0,
677  OSAPI_LOGKIND_WARNING,
678  OSAPI_LOGKIND_INFO,
679  OSAPI_LOGKIND_PRECONDITION
680 } OSAPI_LogKind_T;
681 
682 typedef RTI_UINT32 OSAPI_LogEntryHeader_T;
683 typedef RTI_UINT32 OSAPI_LogEntryPayloadElement_T;
684 
685 /* 31 30 29 28-27 26-16 15 14-0
686  * +---+---+---+------+--------+--------+
687  * | X | E | T | TYPE | MODULE | F | EC |
688  * +---+---+---+------+--------+--------+
689  */
690 #define OSAPI_LOG_HEADER_GET_X(hdr_) ((hdr_)>>31)
691 #define OSAPI_LOG_HEADER_GET_E(hdr_) ((hdr_)>>30 & 0x1)
692 #define OSAPI_LOG_HEADER_GET_T(hdr_) ((hdr_)>>29 & 0x1)
693 #define OSAPI_LOG_HEADER_GET_TYPE(hdr_) (((hdr_) >>27) & 0x3)
694 #define OSAPI_LOG_HEADER_GET_MODULE(hdr_) (((hdr_) >>16) & 0x7ff)
695 #define OSAPI_LOG_HEADER_GET_EC(hdr_) ((hdr_) & 0x7fff)
696 #define OSAPI_LOG_HEADER_GET_F(hdr_) ((hdr_)>>15 & 0x1)
697 
698 #define OSAPI_LOG_HEADER_SET_X(hdr_) ((hdr_) |= 0x80000000)
699 #define OSAPI_LOG_HEADER_CLR_X(hdr_) ((hdr_) &= ~0x80000000)
700 #define OSAPI_LOG_HEADER_SET_E(hdr_) ((hdr_) |= 0x40000000)
701 #define OSAPI_LOG_HEADER_SET_T(hdr_) ((hdr_) |= 0x20000000)
702 #define OSAPI_LOG_HEADER_CLR_T(hdr_) ((hdr_) &= ~0x20000000)
703 #define OSAPI_LOG_HEADER_SET_TYPE(hdr_,type_) ((hdr_) |= ((type_) << 27))
704 #define OSAPI_LOG_HEADER_SET_MODULE(hdr_,m_) ((hdr_) |= ((m_) << 16))
705 #define OSAPI_LOG_HEADER_SET_EC(hdr_,ec) ((hdr_) |= (ec_))
706 #define OSAPI_LOG_HEADER_SET_F(hdr_) ((hdr_) |= 0x8000)
707 #define OSAPI_LOG_HEADER_CLR_F(hdr_) ((hdr_) &= ~0x8000)
708 
709 #define OSAPI_LOG_STATUS_MN (0x80000000)
710 #define OSAPI_LOG_STATUS_SF (0x40000000)
711 #define OSAPI_LOG_STATUS_FN (0x20000000)
712 #define OSAPI_LOG_STATUS_LN (0x10000000)
713 #define OSAPI_LOG_STATUS_F (0x08000000)
714 
715 #define OSAPI_LOG_STATUS_ALL \
716  (OSAPI_LOG_STATUS_MN | \
717  OSAPI_LOG_STATUS_SF | \
718  OSAPI_LOG_STATUS_FN | \
719  OSAPI_LOG_STATUS_LN)
720 
721 #define OSAPI_LOG_STATUS_NO_DATA \
722  (OSAPI_LOG_STATUS_MN | \
723  OSAPI_LOG_STATUS_SF | \
724  OSAPI_LOG_STATUS_FN | \
725  OSAPI_LOG_STATUS_LN)
726 
727 typedef enum
728 {
729  OSAPI_LOGTYPE_INTEGER,
730  OSAPI_LOGTYPE_STRING,
731  OSAPI_LOGTYPE_POINTER
732 } OSAPI_LogType_T;
733 
734 typedef struct OSAPI_LogDataEntry
735 {
736  OSAPI_LogType_T type;
737  char *name;
738  union
739  {
740  RTI_INT32 int_value;
741  char *string_value;
742  void *ptr_value;
743  } value;
744 } OSAPI_LogDataEntry_T;
745 
746 #define OSAPI_LOGDATA_SET_F(hdr_) ((hdr_) |= 0x80000000)
747 #define OSAPI_LOGDATA_GET_F(hdr_) ((hdr_)>>31 & 0x1)
748 #define OSAPI_LOGDATA_SET_TYPE(hdr_,type_) ((hdr_) |= ((type_)<<27))
749 #define OSAPI_LOGDATA_GET_TYPE(hdr_) (((hdr_)>>27) & 0xf)
750 
751 #if OSAPI_ENABLE_TRACE
752 typedef enum
753 {
754  OSAPI_TRACETYPE_HEADER,
755  OSAPI_TRACETYPE_INT32,
756  OSAPI_TRACETYPE_STRING,
757  OSAPI_TRACETYPE_GUID,
758  OSAPI_TRACETYPE_V4_AS_INT32,
759  OSAPI_TRACETYPE_V12_AS_INT32
760 } OSAPI_TraceType_T;
761 #endif
762 
763 /*ci
764  * \brief A log-entry in the log-buffer
765  *
766  * \details
767  * Each log-entry in the log-buffer has a fixed sized buffer followed
768  * by a variable length part that depends on the log-information stored.
769  * The following notation is commonly used in the code:
770  *
771  * data_ptr = (char*)&log_entry[1]
772  *
773  * The data-pointer now points to the beginning of the variable length
774  * data part that follows the fixed size header.
775  *
776  * \verbatim
777  * +-----------------+ Log-buffer
778  * | OSAPI_LogEntry |
779  * | |
780  * +- - - - - - - - -+ <- data_ptr
781  * | |
782  * | log-data |
783  * | |
784  * +-----------------+ Log-buffer
785  * | OSAPI_LogEntry |
786  * | |
787  * +- - - - - - - - -+
788  * | |
789  * | log-data |
790  * | |
791  * +-----------------+
792  *
793  * \endverbatim
794  */
795 typedef struct OSAPI_LogEntry
796 {
797  /*ci
798  * \brief time this message was logged
799  */
800  OSAPI_NtpTime timestamp;
801 
802  /*ci
803  * \brief The error code
804  */
805  RTI_UINT32 error_code;
806 
807 } OSAPI_LogEntry_T;
808 
809 /*ce
810  * \ingroup OSAPILogClass
811  * \brief Logging verbosity
812  */
813 typedef enum
814 {
815  /*ce \brief Logs are not written
816  */
817  OSAPI_LOG_VERBOSITY_SILENT = 0,
818 
819  /*ce \brief Only error logs are written
820  */
821  OSAPI_LOG_VERBOSITY_ERROR = 1,
822 
823  /*ce \brief Error and warning logs are written
824  */
825  OSAPI_LOG_VERBOSITY_WARNING = 2,
826 
827  /*ce \brief All logs are written
828  */
829  OSAPI_LOG_VERBOSITY_DEBUG = 3
830 } OSAPI_LogVerbosity_T;
831 
832 /*ce
833  * \ingroup OSAPILogClass
834  * \brief Optional user-defined function to output a log/trace buffer
835  *
836  * The handler is set by OSAPI_Log_set_property().
837  *
838  * \param[in] buffer Pointer to buffer with log to write
839  * \param[in] length Length of the buffer to write
840  */
841 typedef void
842 (*OSAPI_Log_write_buffer_T)(const char *buffer,RTI_INT32 length);
843 
844 /*ce
845  * \ingroup OSAPILogClass
846  * \brief Configuration of logging functionality
847  */
848 struct OSAPI_LogProperty
849 {
850  /*ce
851  *
852  * \brief The maximum number of bytes allocated to the log buffer.
853  *
854  * \details
855  * Log entries are of variable length. When this limit has been reached,
856  * no more log entries can be stored unless the buffer is cleared.
857  */
858  RTI_SIZE_T max_buffer_size;
859 
860  /*ce \brief Bitmap to control the fidelity of what is stored in the log
861  * entry
862  */
863  RTI_UINT32 log_detail;
864 
865  /*ce \brief Function pointer to output a log/trace buffer
866  */
867  OSAPI_Log_write_buffer_T write_buffer;
868 };
869 
870 
871 #define OSAPI_LOG_DETAIL_MODULENAME (0x80000000UL)
872 #define OSAPI_LOG_DETAIL_SOURCEFILE (0x40000000UL)
873 #define OSAPI_LOG_DETAIL_LINENUMBER (0x20000000UL)
874 #define OSAPI_LOG_DETAIL_FUNCTIONAME (0x10000000UL)
875 #define OSAPI_LOG_DETAIL_FORMAT (0x08000000UL)
876 #define OSAPI_LOG_DETAIL_DATA_ONLY (0x04000000UL)
877 
878 #define OSAPI_LOG_DETAIL_ALL \
879  (OSAPI_LOG_DETAIL_MODULENAME | \
880  OSAPI_LOG_DETAIL_SOURCEFILE | \
881  OSAPI_LOG_DETAIL_LINENUMBER | \
882  OSAPI_LOG_DETAIL_FUNCTIONAME | \
883  OSAPI_LOG_DETAIL_FORMAT | \
884  OSAPI_LOG_DETAIL_DATA_ONLY)
885 
886 #define OSAPI_LOG_DETAIL_NO_DATA \
887  (OSAPI_LOG_DETAIL_MODULENAME | \
888  OSAPI_LOG_DETAIL_SOURCEFILE | \
889  OSAPI_LOG_DETAIL_LINENUMBER | \
890  OSAPI_LOG_DETAIL_FUNCTIONAME )
891 
892 #if OSAPI_ENABLE_PRECONDITION
893 #define OSAPI_LOG_BUFFER_SIZE (16384)
894 #else
895 #define OSAPI_LOG_BUFFER_SIZE (128)
896 #endif
897 
898 #define OSAPI_LogProperty_INIITALIZER \
899 {\
900  OSAPI_LOG_BUFFER_SIZE,\
901  OSAPI_LOG_DETAIL_ALL,\
902  NULL\
903 }
904 
905 #if OSAPI_ENABLE_TRACE
906 typedef void
907 (*OSAPI_TraceHandler_T)(RTI_UINT32 trace_mask,
908  void *param,
909  RTI_INT32 context,
910  const char *const module,
911  const char *const file,
912  const char *const function,
913  RTI_INT32 line_no,
914  OSAPI_TraceType_T type,
915  const void *title,
916  RTI_INT32 int_value,
917  const void *ptr_value,
918  const char *str_value,
919  RTI_BOOL is_final);
920 
921 OSAPIDllVariable extern OSAPI_TraceHandler_T OSAPI_gv_TraceFunction;
922 OSAPIDllVariable extern void* OSAPI_gv_TraceFunctionParam;
923 OSAPIDllVariable extern RTI_UINT32 OSAPI_gv_TraceMask;
924 #endif
925 
926 /*ce
927  * \ingroup OSAPILogClass
928  * \brief Optional user-defined function for processing new log messages
929  *
930  * \details Definition of a function that can be installed with the logger and
931  * that will be called for each new log event.
932  *
933  * The handler is set by OSAPI_Log_set_log_handler().
934  *
935  * When called, provides parameters containing the raw log entry and additional
936  * optional information.
937  *
938  *
939  * \param[in] param User-defined payload
940  * \param[in] msg Log entry
941  * \param[in] kind Kind of log message
942  * \param[in] ec Unique error code of log message
943  * \param[in] module Module of log message
944  * \param[in] file Name of source file. Optional.
945  * \param[in] func Name of function. Optional.
946  * \param[in] line Line number. Optional.
947  * \param[in] argc Variable length argument count
948  * \param[in] ap Variable length argument list
949  */
950 typedef void
951 (*OSAPI_LogHandler_T)(void *param,OSAPI_LogEntry_T *entry);
952 
953 typedef void
954 (*OSAPI_LogDisplay_T)(void *param,OSAPI_LogEntry_T *msg);
955 
956 OSAPIDllVariable extern OSAPI_LogHandler_T OSAPI_gv_LogFunction;
957 OSAPIDllVariable extern void* OSAPI_gv_LogFunctionParam;
958 
959 OSAPIDllVariable extern OSAPI_LogDisplay_T OSAPI_gv_LogDisplayFunction;
960 OSAPIDllVariable extern void* OSAPI_gv_LogDisplayFunctionParam;
961 
962 /*ce
963  * \ingroup OSAPILogClass
964  * \brief Install a log handler
965  *
966  * \details
967  * The log functionality allows the user to specify a log handler. The log
968  * handler is a function which is called for every logged event. It is up
969  * to the user to decide what to do with the log message. The handler is
970  * a global function pointer.
971  *
972  * \param [in] handler Pointer to log handler function
973  * \param [in] param Parameter passed to the log handler function. This
974  * parameter is transparent to the log functionality.
975  *
976  * \return RTI_TRUE on success, RTI_FALSE on failure
977  *
978  */
979 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
980 OSAPI_Log_set_log_handler(OSAPI_LogHandler_T handler,void *param);
981 
982 /*ce
983  * \ingroup OSAPILogClass
984  * \brief Return the current log handler
985  *
986  * \details
987  * Return the current log handler.
988  *
989  * \param [in] handler Pointer to store log handler function
990  * \param [in] param Pointer to store the current log handler parameter.
991  *
992  * \return RTI_TRUE on success, RTI_FALSE on failure
993  *
994  */
995 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
996 OSAPI_Log_get_log_handler(OSAPI_LogHandler_T *handler,void **param);
997 
998 #if OSAPI_ENABLE_TRACE
999 /*ce
1000  * \ingroup OSAPILogClass
1001  * \brief Install a trace handler
1002  *
1003  * \details
1004  * Install a custom trace handler. Traces are not stored in the log-buffer
1005  * and is generally used to analyze behavior interactively. the default
1006  * trace handler outputs the trace data to a console.
1007  *
1008  * \param [in] handler Pointer to trace handler function
1009  * \param [in] param Parameter passed to the trace handler function. This
1010  * parameter is transparent to the trace functionality.
1011  *
1012  * \return RTI_TRUE on success, RTI_FALSE on failure
1013  *
1014  */
1015 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
1016 OSAPI_Log_set_trace_handler(OSAPI_TraceHandler_T handler,void *param);
1017 
1018 /*ce
1019  * \brief Return the trace handler
1020  * \ingroup OSAPILogClass
1021  *
1022  * \details
1023  * Return the current trace handler and trace parameter. This information
1024  * can be used to daisy-chain calls to multiple trace-handlers.
1025  *
1026  * \param [in] handler Pointer to store trace handler function
1027  * \param [in] param Pointer to store the trace handler parameter.
1028  *
1029  * \return RTI_TRUE on success, RTI_FALSE on failure
1030  *
1031  */
1032 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
1033 OSAPI_Log_get_trace_handler(OSAPI_TraceHandler_T *handler,void **param);
1034 #endif
1035 
1036 /*ce
1037  * \ingroup OSAPILogClass
1038  * \brief Install a display handler
1039  *
1040  * \details
1041  * The display handler is responsible for outputting log messages to a console.
1042  *
1043  * \param [in] handler Pointer to display function
1044  * \param [in] param Parameter passed to the display handler function. This
1045  * parameter is transparent to the log functionality.
1046  *
1047  * \return RTI_TRUE on success, RTI_FALSE on failure
1048  *
1049  */
1050 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
1051 OSAPI_Log_set_display_handler(OSAPI_LogDisplay_T handler,void *param);
1052 
1053 /*ce
1054  * \brief Return the current display function
1055  * \ingroup OSAPILogClass
1056  *
1057  * \details
1058  * Return the current log handler.
1059  *
1060  * \param [in] handler Pointer to store display handler function
1061  * \param [in] param Pointer to store the current display handler parameters.
1062  *
1063  * \return RTI_TRUE on success, RTI_FALSE on failure
1064  *
1065  */
1066 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
1067 OSAPI_Log_get_display_handler(OSAPI_LogDisplay_T *handler,void **param);
1068 
1069 /*ci
1070  * \brief Initialize the log functionality
1071  * \ingroup OSAPILogClass
1072  *
1073  * \details
1074  * Dynamically allocates bytes for the log ring buffer. Also prints out endianness.
1075  * If store_debug_logs is false, debug-level logs are printed to the console.
1076  * 0Otherwise, the logs are stored in the log buffer.
1077  * The log functionality must be initialized before any log messages can be
1078  * stored. It should only be called once. Since debug logs can easily exhaust
1079  * the log buffer, it can optionally be enabled. However, even if debug
1080  * logging is disabled, the log handler function still has the option
1081  * to store it.
1082  *
1083  * \return RTI_TRUE on success, RTI_FALSE on failure
1084  */
1085 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
1086 OSAPI_Log_initialize(void);
1087 
1088 /*ci
1089  * \ingroup OSAPILogClass
1090  * \brief Finalize the log buffer
1091  *
1092  * \details
1093  * This function release all memory allocated to the log buffer and release
1094  * all resources associated with it.
1095  *
1096  * \return RTI_TRUE on success, RTI_FALSE on failure
1097  *
1098  * \sa \ref OSAPI_Log_initialize
1099  */
1100 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
1101 OSAPI_Log_finalize(void);
1102 
1103 /*ce
1104  * \ingroup OSAPILogClass
1105  * \brief Set the log verbosity
1106  *
1107  * \details
1108  * Change the log verbosity. The new setting takes immediate effect.
1109  *
1110  * \param [in] verbosity New log verbosity
1111  *
1112  */
1113 OSAPIDllExport void
1114 OSAPI_Log_set_verbosity(OSAPI_LogVerbosity_T verbosity);
1115 
1116 #if OSAPI_ENABLE_TRACE
1117 /*ce
1118  * \ingroup OSAPILogClass
1119  * \brief Set the trace mask
1120  *
1121  * \param [in] mask New trace mask
1122  */
1123 OSAPIDllExport void
1124 OSAPI_Trace_set_trace_mask(RTI_UINT32 mask);
1125 #endif
1126 
1127 /*ce
1128  * \ingroup OSAPILogClass
1129  * \brief Clear the log buffer
1130  *
1131  * \details
1132  * Clear the log buffer, all the current entries are lost
1133  *
1134  * \return RTI_TRUE on success, RTI_FALSE on failure
1135  */
1136 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
1137 OSAPI_Log_clear(void);
1138 
1139 /*ce
1140  * \brief Returns the error code for a function that failed
1141  * \ingroup OSAPILogClass
1142  *
1143  * \details
1144  * Many functions returns RTI_FALSE or NULL on failure. In order to provide
1145  * additional information about reason for the failure fucntions may set
1146  * an additional error code. This function returns the last error-code
1147  * recorded for the calling thread.
1148  *
1149  * \return Last error-code recorded for this thread
1150  *
1151  */
1152 OSAPIDllExport RTI_INT32
1153 OSAPI_Log_get_last_error_code(void);
1154 
1155 /*ce
1156  * \brief Get the current log properties
1157  * \ingroup OSAPILogClass
1158  *
1159  * \details
1160  * Return the current log properties
1161  *
1162  * \param[out] property - Current log properties
1163  *
1164  * \sa OSAPI_Log_set_property
1165  */
1166 OSAPIDllExport void
1167 OSAPI_Log_get_property(struct OSAPI_LogProperty *property);
1168 
1169 /*ce
1170  * \brief Set the log properties
1171  * \ingroup OSAPILogClass
1172  *
1173  * \details
1174  * Set the current log properties. It is not possible to set new
1175  * properties after OSAPI_Log_initialize() has been called/
1176  *
1177  * \param[in] property New log properties
1178  *
1179  * \return RTI_TRUE if new properties can be set, RTI_FALSE otherwise
1180  * \sa OSAPI_Log_get_property
1181  */
1182 OSAPIDllExport RTI_BOOL
1183 OSAPI_Log_set_property(struct OSAPI_LogProperty *property);
1184 
1185 /*ci
1186  * \brief Get the current log verbosity
1187  * \ingroup OSAPILogClass
1188  *
1189  * \return Current verbosity
1190  */
1191 OSAPIDllExport OSAPI_LogVerbosity_T
1192 OSAPI_Log_get_verbosity(void);
1193 
1194 /*ci
1195  * \brief Create a new log-entry
1196  *
1197  * \ingroup OSAPILogClass
1198  *
1199  * \param[in] kind The type of log entry
1200  * \param[in] error_code The error-code
1201  * \param[in] module The name of the module logging the error
1202  * \param[in] file The file logging the error
1203  * \param[in] line The line number in file the error is logged
1204  * \param[in] is_final If RTI_TRUE more data follows, if RTI_FALSE then
1205  * the log meesage is considered complete.
1206  */
1207 OSAPIDllExport void
1208 OSAPI_Log_entry_create(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1209  const char *const module, const char *const file,
1210  const char *const func, RTI_INT32 line,RTI_BOOL is_final);
1211 
1212 /*ci
1213  * \brief Add an integer to a log-entry
1214  *
1215  * \ingroup OSAPILogClass
1216  *
1217  * \param[in] name The name of the integer being logged
1218  * \param[in] value The value of the integer being logged
1219  * \param[in] is_final RTI_TRUE if this is the last value added to the log entry
1220  * RTI_FALSE if more values are being added to the log entry
1221  */
1222 OSAPIDllExport void
1223 OSAPI_Log_entry_add_int(const char *name,RTI_INT32 value,RTI_BOOL is_final);
1224 
1225 /*ci
1226  * \brief Add a string to a log-entry
1227  *
1228  * \ingroup OSAPILogClass
1229  *
1230  * \param[in] name The name of the string being logged
1231  * \param[in] value The value of the string being logged
1232  * \param[in] is_final RTI_TRUE if this is the last value added to the log entry
1233  * RTI_FALSE if more values are being added to the log entry
1234  */
1235 OSAPIDllExport void
1236 OSAPI_Log_entry_add_string(const char *name,const char *value,RTI_BOOL is_final);
1237 
1238 
1239 /*ci
1240  * \brief Add a pointer to a log-entry
1241  *
1242  * \ingroup OSAPILogClass
1243  *
1244  * \param[in] name The name of the pointer being logged
1245  * \param[in] value The value of the pointer being logged
1246  * \param[in] is_final RTI_TRUE if this is the last value added to the log entry
1247  * RTI_FALSE if more values are being added to the log entry
1248  */
1249 OSAPIDllExport void
1250 OSAPI_Log_entry_add_pointer(const char *name,const void *value,RTI_BOOL is_final);
1251 
1252 OSAPIDllExport RTI_BOOL
1253 OSAPI_Log_entry_get_data(OSAPI_LogEntry_T *log_entry,char **data_ptr,
1254  OSAPI_LogType_T *type,const char **name,
1255  const void **value,RTI_BOOL *is_final);
1256 
1257 /*ci
1258  * \brief Create a new log-entry for an error-code with no additional data
1259  *
1260  * \ingroup OSAPILogClass
1261  *
1262  * \param[in] kind The type of log entry
1263  * \param[in] error_code The error-code
1264  * \param[in] module The name of the module logging the error
1265  * \param[in] file The file logging the error
1266  * \param[in] line The line number in file the error is logged
1267  *
1268  * \sa OSAPI_Log_entry_create
1269  */
1270 OSAPIDllExport void
1271 OSAPI_Log_entry_add(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1272  const char *const module, const char *const file,
1273  const char *const func, RTI_INT32 line);
1274 
1275 /*ci
1276  * \brief Create a new log-entry with a single integer
1277  *
1278  * \ingroup OSAPILogClass
1279  *
1280  * \param[in] kind The type of log entry
1281  * \param[in] error_code The error-code
1282  * \param[in] module The name of the module logging the error
1283  * \param[in] file The file logging the error
1284  * \param[in] line The line number in file the error is logged
1285  * \param[in] name The name of the integer being logged
1286  * \param[in] value The value of the integer being logged
1287  *
1288  */
1289 OSAPIDllExport void
1290 OSAPI_Log_entry_add_1int(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1291  const char *const module, const char *const file,
1292  const char *const func, RTI_INT32 line,const char *name,
1293  RTI_INT32 value);
1294 
1295 
1296 /*ci
1297  * \brief Create a new log-entry with a 2 integers
1298  *
1299  * \ingroup OSAPILogClass
1300  *
1301  * \param[in] kind The type of log entry
1302  * \param[in] error_code The error-code
1303  * \param[in] module The name of the module logging the error
1304  * \param[in] file The file logging the error
1305  * \param[in] line The line number in file the error is logged
1306  * \param[in] name1 The name of the 1st integer being logged
1307  * \param[in] value1 The value of the 1st integer being logged
1308  * \param[in] name2 The name of the 2nd integer being logged
1309  * \param[in] value2 The value of the 2nd integer being logged
1310  *
1311  */
1312 OSAPIDllExport void
1313 OSAPI_Log_entry_add_2int(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1314  const char *const module, const char *const file,
1315  const char *const func, RTI_INT32 line,
1316  const char *name1,RTI_INT32 value1,
1317  const char *name2,RTI_INT32 value2);
1318 
1319 /*ci
1320  * \brief Create a new log-entry with a 3 integers
1321  *
1322  * \ingroup OSAPILogClass
1323  *
1324  * \param[in] kind The type of log entry
1325  * \param[in] error_code The error-code
1326  * \param[in] module The name of the module logging the error
1327  * \param[in] file The file logging the error
1328  * \param[in] line The line number in file the error is logged
1329  * \param[in] name1 The name of the 1st integer being logged
1330  * \param[in] value1 The value of the 1st integer being logged
1331  * \param[in] name2 The name of the 2nd integer being logged
1332  * \param[in] value2 The value of the 2nd integer being logged
1333  * \param[in] name3 The name of the 3rd integer being logged
1334  * \param[in] value3 The value of the 3rd integer being logged
1335  *
1336  */
1337 OSAPIDllExport void
1338 OSAPI_Log_entry_add_3int(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1339  const char *const module, const char *const file,
1340  const char *const func, RTI_INT32 line,
1341  const char *name1,RTI_INT32 value1,
1342  const char *name2,RTI_INT32 value2,
1343  const char *name3,RTI_INT32 value3);
1344 
1345 /*ci
1346  * \brief Create a new log-entry with a single string
1347  *
1348  * \ingroup OSAPILogClass
1349  *
1350  * \param[in] kind The type of log entry
1351  * \param[in] error_code The error-code
1352  * \param[in] module The name of the module logging the error
1353  * \param[in] file The file logging the error
1354  * \param[in] line The line number in file the error is logged
1355  * \param[in] name The name of the string being logged
1356  * \param[in] value The value of the string being logged
1357  *
1358  */
1359 OSAPIDllExport void
1360 OSAPI_Log_entry_add_1string(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1361  const char *const module, const char *const file,
1362  const char *const func, RTI_INT32 line,
1363  const char *name,const char* value);
1364 
1365 /*ci
1366  * \brief Create a new log-entry with a 2 strings
1367  *
1368  * \ingroup OSAPILogClass
1369  *
1370  * \param[in] kind The type of log entry
1371  * \param[in] error_code The error-code
1372  * \param[in] module The name of the module logging the error
1373  * \param[in] file The file logging the error
1374  * \param[in] line The line number in file the error is logged
1375  * \param[in] name1 The name of the 1st string being logged
1376  * \param[in] value1 The value of the 1st string being logged
1377  * \param[in] name2 The name of the 2nd string being logged
1378  * \param[in] value2 The value of the 2nd string being logged
1379  *
1380  */
1381 OSAPIDllExport void
1382 OSAPI_Log_entry_add_2string(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1383  const char *const module, const char *const file,
1384  const char *const func, RTI_INT32 line,
1385  const char *name1,const char* value1,
1386  const char *name2,const char* value2);
1387 
1388 /*ci
1389  * \brief Create a new log-entry with a single pointer
1390  *
1391  * \ingroup OSAPILogClass
1392  *
1393  * \param[in] kind The type of log entry
1394  * \param[in] error_code The error-code
1395  * \param[in] module The name of the module logging the error
1396  * \param[in] file The file logging the error
1397  * \param[in] line The line number in file the error is logged
1398  * \param[in] name The name of the pointer being logged
1399  * \param[in] value The value of the pointer being logged
1400  *
1401  */
1402 OSAPIDllExport void
1403 OSAPI_Log_entry_add_1pointer(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1404  const char *const module, const char *const file,
1405  const char *const func, RTI_INT32 line,
1406  const char *name, const void* value);
1407 
1408 /*ci
1409  * \brief Create a new log-entry with a single string and a integer
1410  *
1411  * \ingroup OSAPILogClass
1412  *
1413  * \param[in] kind The type of log entry
1414  * \param[in] error_code The error-code
1415  * \param[in] module The name of the module logging the error
1416  * \param[in] file The file logging the error
1417  * \param[in] line The line number in file the error is logged
1418  * \param[in] s_name The name of the string being logged
1419  * \param[in] s_value The value of the string being logged
1420  * \param[in] i_name The name of the integer being logged
1421  * \param[in] i_value The value of the string being logged
1422  */
1423 OSAPIDllExport void
1424 OSAPI_Log_entry_add_1string_1int(OSAPI_LogKind_T kind, RTI_INT32 error_code,
1425  const char *const module, const char *const file,
1426  const char *const func, RTI_INT32 line,
1427  const char *s_name,const char* s_value,
1428  const char *i_name,RTI_INT32 i_value);
1429 #endif /* OSAPI_ENABLE_LOG */
1430 
1431 /*ci
1432  * \brief Convert an integer to a string in decimal format
1433  * *
1434  * \param[inout] buffer Buffer to store result in
1435  * \param[in] max_length Maximum length of the buffer
1436  * \param[in] d The digit to convert
1437  *
1438  * \return The number of characters placed in the buffer excluding the
1439  * NULL termination. If there is insufficient space max_length
1440  * is returned.
1441  */
1442 OSAPIDllExport RTI_INT32
1443 OSAPI_Log_itoa(char *buffer,RTI_INT32 max_length,RTI_INT32 d);
1444 
1445 #ifdef __cplusplus
1446 } /* extern "C" */
1447 #endif
1448 
1449 #include "osapi/osapi_log_impl.h"
1450 
1451 #endif /* osapi_log_h */
RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc