RTI Distributed Logger API Version 7.7.0
rti_dl_c.h
1/*
2 * (c) Copyright, Real-Time Innovations, 2011-2016.
3 * All rights reserved.
4 * No duplications, whole or partial, manual or electronic, may be made
5 * without express written permission. Any such copies, or
6 * revisions thereof, must display this notice unaltered.
7 * This code contains trade secrets of Real-Time Innovations, Inc.
8 */
9
10#ifndef rti_dl_c_h
11#define rti_dl_c_h
12
13/*ce \file
14 * \brief RTI Distributed Logger (DL) structs and functions
15 */
16#include "rti_dl/rti_dl_dll_c.h"
17#include "log/log_dll.h"
18#include "osapi/osapi_type.h"
19#include "ndds/ndds_c.h"
20#include "ndds/ndds_config_c.h"
21
22#include "dds_c/dds_c_log_impl.h"
23#include "dds_c/dds_c_infrastructure.h"
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29#define RTI_DL_DEFAULT_QUEUE_SIZE 128
30#define RTI_DL_DEFAULT_DOMAIN_ID 0
31
32#define COMMAND_REQUEST_CONTENT_FILTERED_TOPIC_EXPRESSION \
33 "targetHostAndAppId.rtps_host_id = %0 and targetHostAndAppId.rtps_app_id = " \
34 "%1"
35#define COMMAND_REQUEST_CONTENT_FILTERED_TOPIC_NAME \
36 "CommandRequestContentFilteredTopic"
37
38/*
39 * DDS_Time_t initializer is hardcoded to avoid compilation issues in
40 * Integrity platforms.
41 */
42#define RTI_DL_DistLogger_MessageParams_INITIALIZER \
43 { \
44 0, NULL, NULL, DDS_TIME_INVALID_VALUE \
45 }
46
47/* ------------------------------------------------------------ */
48/*ce
49 * \defgroup RTI_DL_DistLogger_Module RTI Distributed Logger API
50 * @brief This module contains common definitions such as RTI Distributed
51 * Logger singleton, message sending functions, and general configuration.
52 *
53 * This module provides an API to publish log messages to a DDS Topic. Generally
54 * this API is used by an application logging infrastructure to integrate it
55 * into an application, although it is also possible to use the API directly.
56 * In general, the steps to customize and use RTI Distributed Logger are the
57 * following:
58 * -# Customize your RTI Distributed Logger using the
59 * \ref RTI_DL_Options_Module. \ref RTI_DL_Options must be set \b before
60 * creating the \ref RTI_DL_DistLogger.
61 * -# Assign the newly created options to RTI Distributed Logger using \ref
62 * RTI_DL_DistLogger_setOptions.
63 * -# Create your \ref RTI_DL_DistLogger_Module using \ref
64 * RTI_DL_DistLogger_getInstance. Make sure the instance was not created before
65 * or the option setup will have no effect.
66 * -# Finally, send your own log messages using \ref RTI_DL_DistLogger_Module
67 * logging functions: \ref RTI_DL_DistLogger_error, \ref
68 * RTI_DL_DistLogger_fatal, ...
69 * Internal RTI Logger will be sent automatically once RTI Distributed
70 * Logger is created (no additional configuration required).
71*/
72
73
74/*ce
75 * \defgroup RTI_DL_Options_Module RTI Distributed Logger Options API
76 * \ingroup RTI_DL_DistLogger_Module
77 * \brief Customize RTI Distributed Logger using this API.
78*/
79
80
81/*ce
82 * \ingroup RTI_DL_Options_Module
83 \struct RTI_DL_Options
84 \brief This struct contains all RTI Distributed Logger's configurable
85 options
86
87 This struct must be created and configured \b before the first call to
88 \ref RTI_DL_DistLogger_getInstance. To associate the options
89 with the Distributed Logger, use the function
90 \ref RTI_DL_DistLogger_setOptions. Use the functions in \ref
91 RTI_DL_Options_Module to modify the different options.
92*/
93
94typedef struct RTI_DL_Options RTI_DL_Options;
95
96
97
98/*---------------------------------------------------------------
99 Dist Logger DDSEntities
100 ----------------------------------------------------------------
101*/
102
103/*i \defgroup RTI_DL_DDSEntities_Module RTI Distributed Logger DDS Entities API
104 * \ingroup RTI_DL_DistLogger_Module
105 * \brief Functions and type definitions for internal DDS entities used by the
106 * RTI Distributed Logger.
107*/
108/*i \ingroup RTI_DL_DDSEntities_Module
109 * \struct RTI_DL_DDSEntities
110 * \brief This class provides a wrapper of DDS entities.
111*/
112typedef struct RTI_DL_DDSEntities RTI_DL_DDSEntities;
113
114
115
116
117/*ce
118 * \ingroup RTI_DL_DistLogger_Module
119 * \struct RTI_DL_DistLogger
120 * \brief Struct defining RTI Distributed Logger singleton.
121 *
122 * This struct is a <b>singleton</b>, so only one copy will be created.
123 * Use the \ref RTI_DL_Options_Module to customize the singleton \b BEFORE
124 * creating it.
125 */
126typedef struct RTI_DL_DistLogger RTI_DL_DistLogger;
127
128
129
130/*ce
131 * \ingroup RTI_DL_DistLogger_Module
132 * \brief Provides access to the \ref RTI_DL_DistLogger singleton.
133 *
134 * This method provides access to the singleton instance of RTI Distributed
135 * Logger, \ref RTI_DL_DistLogger. If the instance does not exist, it will be
136 * created. To customize it, use the \ref RTI_DL_Options_Module API \b BEFORE
137 * creating the singleton the first time. Note that no change in options is
138 * allowed after the singleton is created.
139 * \return The singleton instance of \ref RTI_DL_DistLogger.
140 * \note This function is only thread-safe on Linux and Windows platforms.
141 */
142extern RTIDLCDllExport RTI_DL_DistLogger * RTI_DL_DistLogger_getInstance(void);
143
144
145
146/*i
147 * \ingroup RTI_DL_DistLogger_Module
148 * \brief Provides access to the \ref RTI_DL_DistLogger singleton, specifying
149 * which DomainParticipantFactory should be used in case Distributed Logger
150 * needs to create its own DomainParticipant during singleton initialization.
151 *
152 * This method provides access to the singleton instance of RTI Distributed
153 * Logger, \ref RTI_DL_DistLogger. If the instance does not exist, it will be
154 * created. To customize it, use the \ref RTI_DL_Options_Module API \b BEFORE
155 * creating the singleton the first time. Note that no change in options is
156 * allowed after the singleton is created.
157 *
158 * \param [in] domainParticipantFactory Pointer to a valid
159 * DDS_DomainParticipantFactory from which Distributed
160 * Logger must create its DomainParticipant in case
161 * that none is provided through the \ref RTI_DL_Options_Module
162 * API
163 *
164 * \return The singleton instance of \ref RTI_DL_DistLogger.
165 * \note This function is only thread-safe on Linux and Windows platforms.
166 */
167extern RTIDLCDllExport RTI_DL_DistLogger * RTI_DL_DistLogger_getInstanceI(
168 DDS_DomainParticipantFactory *domainParticipantFactory);
169
170
171/*ce
172 * \ingroup RTI_DL_DistLogger_Module
173 * \brief Sets the filter level for the singleton.
174 *
175 * Filtering controls what type of log messages are sent.
176 * This enables filtering on the \em sending side (in the application using
177 * Distributed Logger). You can also enable filtering on the \em receiving side
178 * (such as in a tool that receives log messages, like RTI Admin Console or
179 * RTI Monitor).
180 *
181 * Supported Filter Levels: See the table below.
182 * The default value is RTI_DL_INFO_LEVEL.
183 *
184 * Or see the IDL file provided with Distributed Logger
185 * (file: \ref_url_dl_idl). In the IDL file, there are language-specific bindings.
186 * Prepend the appropriate binding to the filter level shown in the IDL.
187 * For example, one of the filter levels in the IDL is INFO_LEVEL.
188 * To refer to this filter level in C, use RTI_DL_INFO_LEVEL.
189 *
190 * Log messages up to and including the specified filter level will pass through
191 * the filter and be sent on the network. For example, the WARNING level allows
192 * log messages up to and including the WARNING level (FATAL, SEVERE, ERROR, and
193 * WARNING) to be sent; any other log messages with numerically higher filter
194 * levels (INFO, DEBUG, and TRACE) will be filtered out and not sent.
195 *
196 * \param [in,out] self Pointer to the \ref RTI_DL_DistLogger
197 * \param [in] newLevel The new log level.
198 * \return Error code. DDS_RETCODE_OK if everything went as planned.
199 *
200 * The following table shows how RTI Connext DDS log levels (RTI Logger) map to
201 * RTI Distributed Logger log filter levels.
202 *
203 * Not all Distributed Logger levels appear in this table because
204 * there is not a one-to-one mapping between RTI Connext DDS and RTI Distributed
205 * Logger levels (there are more levels in RTI Distributed Logger).
206 * You can obtain the filter level using a constant defined in the Distributed
207 * Logger IDL file or a getter function in the Distributed Logger API.
208 *
209 * <CENTER><TABLE>
210 * <CAPTION><EM>Filter Levels</EM></CAPTION>
211 * <TR>
212 * <TH> Connext DDS API constant </TH>
213 * <TH> Distributed Logger IDL constant </TH>
214 * <TH> Distributed Logger API getter </TH>
215 * </TR>
216 * <TR>
217 * <TD>NDDS_CONFIG_LOG_FATAL_ERROR</TD>
218 * <TD>RTI_DL_FATAL_LEVEL</TD>
219 * <TD>\ref RTI_DL_DistLogger_get_fatal_log_level</TD>
220 * </TR>
221 * <TR>
222 * <TD>NDDS_CONFIG_LOG_LEVEL_ERROR</TD>
223 * <TD>RTI_DL_ERROR_LEVEL</TD>
224 * <TD>\ref RTI_DL_DistLogger_get_error_log_level</TD>
225 * </TR>
226 * <TR>
227 * <TD>NDDS_CONFIG_LOG_LEVEL_WARNING</TD>
228 * <TD>RTI_DL_WARNING_LEVEL</TD>
229 * <TD>\ref RTI_DL_DistLogger_get_warning_log_level</TD>
230 * </TR>
231 * <TR>
232 * <TD>NDDS_CONFIG_LOG_LEVEL_STATUS_LOCAL</TD>
233 * <TD>RTI_DL_NOTICE_LEVEL</TD>
234 * <TD>\ref RTI_DL_DistLogger_get_notice_log_level</TD>
235 * </TR>
236 * <TR>
237 * <TD>NDDS_CONFIG_LOG_LEVEL_STATUS_REMOTE</TD>
238 * <TD>RTI_DL_INFO_LEVEL</TD>
239 * <TD>\ref RTI_DL_DistLogger_get_info_log_level</TD>
240 * </TR>
241 * <TR>
242 * <TD>NDDS_CONFIG_LOG_LEVEL_DEBUG</TD>
243 * <TD>RTI_DL_DEBUG_LEVEL</TD>
244 * <TD>\ref RTI_DL_DistLogger_get_debug_log_level</TD>
245 * </TR>
246 * </TABLE></CENTER>
247 *
248 */
249extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_DistLogger_setFilterLevel(
250 RTI_DL_DistLogger *self, DDS_Long newLevel);
251
252
253/*ce
254 * \ingroup RTI_DL_DistLogger_Module
255 * \brief Assigns configurable options to RTI Distributed Logger before its
256 * creation.
257 *
258 * Assigns the values in the \ref RTI_DL_Options struct to the
259 * \ref RTI_DL_DistLogger singleton \b before its creation. If the singleton was
260 * already created, this function has no effect.
261 * \param [in] options New options to be assigned to the
262 * \ref RTI_DL_DistLogger singleton.
263 * \pre self must be NULL.
264 * \return RTI_TRUE if everything went as planned. RTI_FALSE if RTI
265 * Distributed Logger already existed.
266 */
267
268extern RTIDLCDllExport RTIBool RTI_DL_DistLogger_setOptions(const RTI_DL_Options *options);
269
270
271/*ce \ingroup RTI_DL_DistLogger_Module
272 * \brief Sets PrintFormat of RTI Logger to the provided value.
273 *
274 * This method is mostly a pass-through to the appropriate call in the RTI Connext
275 * DDS library, but it also has the benefit of keeping the state of RTI
276 * Logger and RTI Distributed Logger in sync.
277 * \param [in,out] self Pointer to the \ref RTI_DL_DistLogger
278 * \param [in] logPrintFormat The new PrintFormat.
279 * \return RTI_TRUE if everything went as planned.
280 */
281extern RTIDLCDllExport RTIBool RTI_DL_DistLogger_setRTILoggerPrintFormat(
282 RTI_DL_DistLogger *self, NDDS_Config_LogPrintFormat logPrintFormat);
283
284
285/*ce \ingroup RTI_DL_DistLogger_Module
286 * \brief Updates the LogCategory and the LogVerbosity in RTI Logger to the
287 * provided value.
288 *
289 * This method is mostly a pass-through to the appropriate call in the RTI Connext
290 * DDS library, but it also has the benefit of keeping the state of RTI
291 * Logger and RTI Distributed Logger in sync.
292 * \param [in,out] self Pointer to the \ref RTI_DL_DistLogger
293 * \param [in] category The category for which to set the verbosity.
294 * \param [in] verbosity The new verbosity level for the category.
295 * \return <code>true</code> if the call was successful,
296 * or <code>false</code> otherwise.
297 */
298extern RTIDLCDllExport RTIBool RTI_DL_DistLogger_setRTILoggerVerbosityByCategory(
299 RTI_DL_DistLogger *self, NDDS_Config_LogCategory category,
300 NDDS_Config_LogVerbosity verbosity);
301
302
303/*ce \ingroup RTI_DL_DistLogger_Module
304 * \brief Input parameters for \ref RTI_DL_DistLogger_logMessageWithParams
305 */
306struct RTI_DL_DistLogger_MessageParams {
307 /*e
308 * The level of the log message.
309 */
310 int log_level;
311
312 /*e
313 * The message to log. It must be non-NULL.
314 */
315 const char *message;
316
317 /*e
318 * The category of the log message.
319 */
320 const char *category;
321
322 /*e
323 * The timestamp with which the message will be logged.
324 */
325 struct DDS_Time_t timestamp;
326};
327
328
329/*ce \ingroup RTI_DL_DistLogger_Module
330 * \brief Logs a message at the specified level and with the specified
331 * category.
332 *
333 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
334 * \param [in] logLevel The level of the log message.
335 * \param [in] message The message to log.
336 * \param [in] category The category of the log message.
337 */
338extern RTIDLCDllExport void RTI_DL_DistLogger_logMessageWithLevelCategory(
339 RTI_DL_DistLogger *self, int logLevel, const char *message,
340 const char *category);
341
342
343
344/*ce \ingroup RTI_DL_DistLogger_Module
345 * \brief Performs the same function as \ref RTI_DL_DistLogger_logMessageWithLevelCategory
346 * except that it also allows specification of the message timestamp.
347 *
348 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
349 * \param [in] params Parameters.
350 */
351extern RTIDLCDllExport void RTI_DL_DistLogger_logMessageWithParams(
352 RTI_DL_DistLogger *self,
353 const struct RTI_DL_DistLogger_MessageParams *params);
354
355
356/*ce \ingroup RTI_DL_DistLogger_Module
357 * \brief Logs a fatal message
358 *
359 * The message received is logged using the default category and the
360 * RTI_DL_FATAL_LEVEL log level.
361 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
362 * \param [in] message The message to log.
363 */
364extern RTIDLCDllExport void RTI_DL_DistLogger_fatal(RTI_DL_DistLogger *self,
365 const char *message);
366
367
368/*ce \ingroup RTI_DL_DistLogger_Module
369 * \brief Logs a severe message
370 *
371 * The message received is logged using the default category and the
372 * RTI_DL_SEVERE_LEVEL log level.
373 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
374 * \param [in] message The message to log.
375 */
376extern RTIDLCDllExport void RTI_DL_DistLogger_severe(RTI_DL_DistLogger *self,
377 const char *message);
378
379
380/*ce \ingroup RTI_DL_DistLogger_Module
381 * \brief Logs a error message
382 *
383 * The message received is logged using the default category and the
384 * RTI_DL_ERROR_LEVEL log level.
385 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
386 * \param [in] message The message to log.
387 */
388extern RTIDLCDllExport void RTI_DL_DistLogger_error(RTI_DL_DistLogger *self,
389 const char *message);
390
391
392/*ce \ingroup RTI_DL_DistLogger_Module
393 * \brief Logs a warning message
394 *
395 * The message received is logged using the default category and the
396 * RTI_DL_WARNING_LEVEL log level.
397 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
398 * \param [in] message The message to log.
399 */
400extern RTIDLCDllExport void RTI_DL_DistLogger_warning(RTI_DL_DistLogger *self,
401 const char *message);
402
403
404/*ce \ingroup RTI_DL_DistLogger_Module
405 * \brief Logs a notice message
406 *
407 * The message received is logged using the default category and the
408 * RTI_DL_NOTICE_LEVEL log level.
409 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
410 * \param [in] message The message to log.
411 */
412extern RTIDLCDllExport void RTI_DL_DistLogger_notice(RTI_DL_DistLogger *self,
413 const char *message);
414
415
416/*ce \ingroup RTI_DL_DistLogger_Module
417 * \brief Logs a info message
418 *
419 * The message received is logged using the default category and the
420 * RTI_DL_INFO_LEVEL log level.
421 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
422 * \param [in] message The message to log.
423 */
424extern RTIDLCDllExport void RTI_DL_DistLogger_info(RTI_DL_DistLogger *self,
425 const char *message);
426
427
428/*ce \ingroup RTI_DL_DistLogger_Module
429 * \brief Logs a debug message
430 *
431 * The message received is logged using the default category and the
432 * RTI_DL_DEBUG_LEVEL log level.
433 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
434 * \param [in] message The message to log.
435 */
436extern RTIDLCDllExport void RTI_DL_DistLogger_debug(RTI_DL_DistLogger *self,
437 const char *message);
438
439
440/*ce \ingroup RTI_DL_DistLogger_Module
441 * \brief Logs a trace message
442 *
443 * The message received is logged using the default category and the
444 * RTI_DL_TRACE_LEVEL log level.
445 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
446 * \param [in] message The message to log.
447 */
448extern RTIDLCDllExport void RTI_DL_DistLogger_trace(RTI_DL_DistLogger *self,
449 const char *message);
450
451
452/*ce \ingroup RTI_DL_DistLogger_Module
453 * \brief Logs a message
454 *
455 * The message received is logged using the default category and the
456 * given log level.
457 * \param [in] self Pointer to the \ref RTI_DL_DistLogger
458 * \param [in] logLevel The level of the log message.
459 * \param [in] message The message to log.
460 */
461extern RTIDLCDllExport void RTI_DL_DistLogger_log(RTI_DL_DistLogger *self,
462 int logLevel, const char *message);
463
464
465
466/*ce \ingroup RTI_DL_DistLogger_Module
467 * \brief Finalizes and deletes the RTI Distributed Logger singleton.
468 *
469 * Unset the connections with DDS, free memory, and set the singleton to NULL
470 * \return DDS_RETCODE_OK if everything went as planned. Otherwise, an
471 * error code is returned.
472 */
473extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_DistLogger_finalizeInstance(void);
474
475
476/*ce \ingroup RTI_DL_DistLogger_Module
477 * \brief Return Fatal log level.
478 *
479 * \return Fatal log level.
480 */
481extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_fatal_log_level(void);
482
483
484/*ce \ingroup RTI_DL_DistLogger_Module
485 * \brief Return Error log level.
486 *
487 * \return Error log level.
488 */
489extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_error_log_level(void);
490
491
492/*ce \ingroup RTI_DL_DistLogger_Module
493 * \brief Return Warning log level.
494 *
495 * \return Warning log level.
496 */
497extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_warning_log_level(void);
498
499
500/*ce \ingroup RTI_DL_DistLogger_Module
501 * \brief Return Notice log level.
502 *
503 * \return Notice log level.
504 */
505extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_notice_log_level(void);
506
507
508/*ce \ingroup RTI_DL_DistLogger_Module
509 * \brief Return Info log level.
510 *
511 * \return Info log level.
512 */
513extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_info_log_level(void);
514
515
516/*ce \ingroup RTI_DL_DistLogger_Module
517 * \brief Return Debug log level.
518 *
519 * \return Debug log level.
520 */
521extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_debug_log_level(void);
522
523
524/*------------------------------------------------*/
525/*ce \defgroup RTI_DL_Utility_Module RTI Distributed Logger Utility Module
526* \ingroup RTI_DL_DistLogger_Module
527* \brief Commodity functions to work with RTI Distributed Logger .
528*/
529/*ce
530 * \ingroup RTI_DL_Utility_Module
531 * \brief Blocks the calling thread for the specified duration.
532 *
533 * Note that the achievable resolution of sleep is OS-dependent.
534 * That is, do not assume that you can sleep for 1 ms just
535 * because you can specify a 1-ms sleep duration via the API.
536 * The sleep resolution on most operating systems is usually 10 ms or greater.
537 *
538 * \param [in] ms Sleep duration in milliseconds.
539 */
540extern RTIDLCDllExport void RTI_DL_Utility_sleep(int ms);
541
542
543
544/*------------------------------------------------*/
545/*i \defgroup RTI_DL_LogMessageWriteThread RTI DL LogMessageWriteThread API
546 * \ingroup RTI_DL_DistLogger_Module
547 * This struct and functions are responsible for pulling log messages from its input queue,
548 * formatting them to the type used with DDS, and publishing them to the DDS
549 * Topic.
550*/
551/*i \ingroup RTI_DL_LogMessageWriteThread
552 * \struct RTI_DL_LogMessageWriteThread
553 * \brief This struct holds the log message and the queue needed to push them to DDS.
554*/
555typedef struct RTI_DL_LogMessageWriteThread LogMessageWriteThread;
556
557
558/*---------------------------------------------------------------
559 Dist Logger Options (Options)
560 ----------------------------------------------------------------
561*/
562
563
564/*ce \ingroup RTI_DL_Options_Module
565 * \brief Initializes a \ref RTI_DL_Options struct with the default
566 * values needed to create the Distributed Logger.
567*/
568extern RTIDLCDllExport void RTI_DL_Options_initialize(RTI_DL_Options * self);
569
570
571/*ce \ingroup RTI_DL_Options_Module
572 * \brief Allocates memory for a \ref RTI_DL_Options struct and sets the default
573 * values needed to create the Distributed Logger.
574 * \return Pointer to a working \ref RTI_DL_Options struct
575 * \post Memory must be release using \ref RTI_DL_Options_delete
576 * \see RTI_DL_Options_delete()
577*/
578extern RTIDLCDllExport RTI_DL_Options * RTI_DL_Options_createDefault(void);
579
580
581/*e
582 * \ingroup RTI_DL_Options_Module
583 * \brief Create a copy of a RTI Distributed Logger options instance.
584 *
585 * This method creates a deep copy of a RTI Distributed Logger options object.
586 *
587 * \pre The self options instance is not null and has been initialized with the
588 * default values.
589 *
590 * \param [out] self Already created \ref RTI_DL_Options struct where we want
591 * to copy the values in.
592 * \param [in] other \ref RTI_DL_Options containing the values to be copied in
593 * \c self.
594 * \return If the copy process was successful then returns <code>true</code>.
595 * Otherwise it returns <code>false</code>.
596 */
597extern RTIDLCDllExport RTIBool RTI_DL_Options_copy(RTI_DL_Options * self,
598 const RTI_DL_Options * other);
599
600
601/*e
602 * \ingroup RTI_DL_Options_Module
603 * \brief Checks for equality between two \ref RTI_DL_Options objects.
604 * \param [in] self an \ref RTI_DL_Options object.
605 * \param [in] other an \ref RTI_DL_Options object.
606 * \return <code>true</code> if the two objects are equal.
607 * Returns <code>false</code> otherwise.
608 */
609extern RTIDLCDllExport RTIBool RTI_DL_Options_equals(
610 const RTI_DL_Options * self, const RTI_DL_Options * other);
611
612
613/*ce \ingroup RTI_DL_Options_Module
614 * \brief Gets the current DomainParticipant that will be used to create the
615 * RTI Distributed Logger's internal entities.
616 *
617 * If a customized DomainParticipant has been set, this function returns a
618 * pointer to it. If this field is not null, this is the
619 * DomainParticipant. Otherwise, it returns the default value, NULL.
620 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
621 * \return Pointer to the DDS_DomainParticipant contained in the struct.
622 * \see RTI_DL_Options_getDomainParticipant
623 */
624extern RTIDLCDllExport DDS_DomainParticipant *
625 RTI_DL_Options_getDomainParticipant(RTI_DL_Options * self);
626
627
628/*ce \ingroup RTI_DL_Options_Module
629 * \brief Sets the DomainParticipant to be used to create RTI
630 * Distributed Logger internal entities.
631 *
632 * There are several use cases in which you may want to use your own
633 * DomainParticipant to create RTI Distributed Logger internal DDS
634 * entities. By calling this function, you will have control of the
635 * DomainParticipant used by RTI Distributed Logger. Once assigned,
636 * \c \b domainParticipant will be used to create the DDS entities (Topics,
637 * Publishers, Subscribers, DataWriters, & DataReaders) needed by RTI
638 * Distributed Logger.
639 *
640 * When the DomainParticipant is set to a non-NULL value,
641 * it is the user's responsibility to handle the memory associated
642 * with it.
643 *
644 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct
645 * \param [in] domainParticipant Pointer to a valid DDS_DomainParticipant
646 * \post Memory must be released by the user \b after finalizing RTI
647 * Distributed Logger using \ref RTI_DL_DistLogger_finalizeInstance.
648 * \return DDS_RETCODE_OK if the operation was a success.
649 */
650extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setDomainParticipant(
651 RTI_DL_Options * self, DDS_DomainParticipant * domainParticipant);
652
653
654/*ce \ingroup RTI_DL_Options_Module
655 * \brief Indicates whether Distributed Logger should also log all
656 * messages produced by infrastructure code automatically.
657 *
658 * If true, messages produced by either the middleware or the tools will
659 * be forwarded to Distributed Logger.
660 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
661 * \return Boolean to the current LogInfrastructureMessages value.
662 */
663extern RTIDLCDllExport RTIBool RTI_DL_Options_getLogInfrastructureMessages(
664 RTI_DL_Options * self);
665
666
667/*ce \ingroup RTI_DL_Options_Module
668 * \brief Enables or disables automatic logging of infrastructure messages
669 *
670 * If true, messages produced by either the middleware or the tools will
671 * be forwarded to Distributed Logger. In this mode Distributed Logger uses
672 * NDDS_Config_Logger_set_output_device() API to receive messages from the
673 * middleware. Hence any device previously registered with
674 * NDDS_Config_Logger_set_output_device() API will be unregistered. Similarly
675 * Distributed Logger will stop logging infrastructure messages if the
676 * set_output_device() API is used to register a new device after the creation
677 * of the Distributed Logger instance.
678 *
679 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct
680 * \param [in] log Boolean indicating whether to enable this feature.
681 * \return DDS_RETCODE_OK if the operation was a success.
682 */
683extern RTIDLCDllExport DDS_ReturnCode_t
684 RTI_DL_Options_setLogInfrastructureMessages(RTI_DL_Options * self,
685 RTIBool log);
686
687
688/*ce \ingroup RTI_DL_Options_Module
689 * \brief Indicates whether remote administration is enabled or not
690 *
691 * If true, remote administration Topics will be created and
692 * used. If false, they will not be created. The default value
693 * is true.
694 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
695 * \return true if the Remote Administration is enabled. Otherwise false.
696 */
697extern RTIDLCDllExport RTIBool RTI_DL_Options_isRemoteAdministrationEnabled(
698 RTI_DL_Options * self);
699
700
701/*ce \ingroup RTI_DL_Options_Module
702 * \brief Enables or disables remote administration
703 *
704 * Sets remote administration of the Topics to the value passed as
705 * a parameter.
706 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct
707 * \param [in] enabled Boolean indicating new remote administration value.
708 * \return DDS_RETCODE_OK if the operation was a success.
709 */
710extern RTIDLCDllExport DDS_ReturnCode_t
711 RTI_DL_Options_setRemoteAdministrationEnabled(RTI_DL_Options * self,
712 RTIBool enabled);
713
714
715/*ce \ingroup RTI_DL_Options_Module
716 * \brief Gets the log filter level.
717 *
718 * Supported Filter Levels: See the IDL file provided with RTI Distributed
719 * Logger (\ref_url_dl_idl)
720 *
721 * The default value is RTI_DL_INFO_LEVEL.
722 *
723 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
724 * \return integer containing the log filter level value of the options.
725 * \see RTI_DL_DistLogger_setFilterLevel
726 */
727extern RTIDLCDllExport int RTI_DL_Options_getFilterLevel(RTI_DL_Options * self);
728
729
730/*ce \ingroup RTI_DL_Options_Module
731 * \brief Sets the log filter level.
732 *
733 * Filtering controls what type of log messages are sent.
734 * This enables filtering on the \em sending side (in the application using
735 * RTI Distributed Logger). You can also enable filtering on the \em receiving
736 * side (such as in a tool that receives log messages, like RTI Admin Console or
737 * RTI Monitor).
738 *
739 * Supported Filter Levels: See the IDL file provided with RTI Distributed
740 * Logger (\ref_url_dl_idl).
741 * The default value is RTI_DL_INFO_LEVEL.
742
743 *
744 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct
745 * \param [in] filterLevel Integer containing the log filter level value of the
746 * options.
747 * \return DDS_RETCODE_OK if the operation was a success
748 * \see RTI_DL_DistLogger_setFilter for more details.
749 */
750extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setFilterLevel(
751 RTI_DL_Options * self, int filterLevel);
752
753
754/*ce \ingroup RTI_DL_Options_Module
755 * \brief Gets the current Domain ID
756 *
757 * Returns the Domain ID to be used by RTI Distributed Logger. This value is
758 * only used if \ref RTI_DL_Options_setDomainParticipant has NOT been called.
759 * Otherwise, the Domain ID used is the one of the DomainParticipant assigned
760 *
761 * The default value is 0.
762 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
763 * \return Integer containing the DDS Domain ID where RTI Distributed
764 * Logger instance will be created.
765 */
766extern RTIDLCDllExport int RTI_DL_Options_getDomainId(RTI_DL_Options * self);
767
768
769/*ce \ingroup RTI_DL_Options_Module
770 * \brief Sets the current Domain ID
771 *
772 * Updated the Domain ID to be used by RTI Distributed Logger. This value is
773 * only used if \ref RTI_DL_Options_setDomainParticipant has NOT been called.
774 * Otherwise, the Domain ID used is the one of the DomainParticipant assigned.
775 *
776 * The default value is 0.
777 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct.
778 * \param [in] domainId Integer representing a DDS Domain ID. Max value 250.
779 * \return DDS_RETCODE_OK if the operation was a success.
780 */
781extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setDomainId(
782 RTI_DL_Options * self, int domainId);
783
784
785/*ce \ingroup RTI_DL_Options_Module
786 * \brief Gets the Qos Library that will be used to create to RTI
787 * Distributed Logger
788 *
789 * The QoS library name to use when creating DDS entities. It is up to the
790 * application to ensure that this library is available at runtime for RTI
791 * Distributed Logger to use. The default value is "".
792 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
793 * \return Pointer to a string containing the current Qos Library. Do not
794 * modify the content of this pointer directly nor delete it.
795 */
796extern RTIDLCDllExport char * RTI_DL_Options_getQosLibrary(
797 RTI_DL_Options * self);
798
799
800/*ce \ingroup RTI_DL_Options_Module
801 * \brief Sets the Qos Library that will be used to create to RTI
802 * Distributed Logger
803 *
804 * The QoS library name to use when creating DDS entities. It is up to the
805 * application to ensure that this library is available at run time for the
806 * Distributed Logger to use.
807 *
808 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct.
809 * \param [in] qosLibrary Pointer to a char containing the new Qos Library. A
810 * copy of the string is made.
811 * \return DDS_RETCODE_OK if the operation was a success.
812 */
813extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setQosLibrary(
814 RTI_DL_Options * self, const char *qosLibrary);
815
816
817/*ce \ingroup RTI_DL_Options_Module
818 * \brief Gets the Qos Profile that will be used to create to RTI
819 * Distributed Logger
820 *
821 * The QoS profile name to use when creating DDS entities. It is up to the
822 * application to ensure that this profile is available at run time for the
823 * Distributed Logger to use. The default value is "".
824 *
825 * \param [in] self Pointer to a working \ref RTI_DL_Options struct.
826 * \return Pointer to a char containing the current Qos Profile. Do not modify
827 * the content of this pointer directly nor delete it.
828 */
829extern RTIDLCDllExport char * RTI_DL_Options_getQosProfile(
830 RTI_DL_Options * self);
831
832
833/*ce \ingroup RTI_DL_Options_Module
834 * \brief Sets the Qos Profile that will be used to create to RTI
835 * Distributed Logger
836 *
837 * The QoS profile name to use when creating DDS entities. It is up to the
838 * application to ensure that this profile is available at run time for the
839 * Distributed Logger to use.
840 *
841 * \param[in,out] self Pointer to a working \ref RTI_DL_Options struct.
842 * \param [in] qosProfile Pointer to a char containing the new Qos profile. A
843 * copy of the string is made.
844 * \return DDS_RETCODE_OK if the operation was a success.
845 */
846extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setQosProfile(
847 RTI_DL_Options * self, const char *qosProfile);
848
849
850/*ce \ingroup RTI_DL_Options_Module
851 * \brief Gets the maximum queue size that will be assigned to RTI
852 * Distributed Logger
853 *
854 * This field controls the size of the queue used to temporarily store log
855 * messages from the application until they can be written out to
856 * DDS. The default value is RTI_DL_DEFAULT_QUEUE_SIZE.
857 * \param [in] self Pointer to a working \ref RTI_DL_Options struct
858 * \return Integer containing the current maximum queue size.
859 */
860extern RTIDLCDllExport int RTI_DL_Options_getQueueSize(RTI_DL_Options * self);
861
862
863/*ce \ingroup RTI_DL_Options_Module
864 * \brief Sets the maximum queue size that will be assigned to RTI
865 * Distributed Logger
866 *
867 * This field controls the size of the queue used to temporarily store log
868 * messages from the application until they can be written out to
869 * DDS.
870 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct.
871 * \param [in] queueSize Integer containing the new maximum queue size.
872 * \return DDS_RETCODE_OK if the operation was a success.
873 */
874extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setQueueSize(
875 RTI_DL_Options * self, int queueSize);
876
877
878/*ce \ingroup RTI_DL_Options_Module
879 * \brief Gets the thread settings of the publishing thread that will be created
880 * by RTI Distributed Logger
881 *
882 * This fields controls the priority of the thread that sends the
883 * messages through DDS. The default values are defined in dds_c_infrastructure.h.
884 * \param [in] self Pointer to a working \ref RTI_DL_Options struct.
885 * \return The thread settings defined in the options.
886 */
887extern RTIDLCDllExport struct DDS_ThreadSettings_t *
888 RTI_DL_Options_getThreadSettings(RTI_DL_Options * self);
889
890
891/*ce \ingroup RTI_DL_Options_Module
892 * \brief Sets the settings of the publishing thread that will be created
893 * by RTI Distributed Logger
894 *
895 * This field controls the settings of the thread that sends the
896 * messages through DDS. These settings only affect the publishing thread
897 * created by RTI Distributed Logger.
898 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct.
899 * \param [in] threadSettings The thread settings to apply to the options.
900 * Must be a valid RTI_OSAPI_THREAD_PRIORITY value.
901 * \return DDS_RETCODE_OK if the operation was a success.
902 */
903extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setThreadSettings(
904 RTI_DL_Options * self,
905 const struct DDS_ThreadSettings_t * threadSettings);
906
907
908/*ce \ingroup RTI_DL_Options_Module
909 * \brief Gets the application kind that will be associated with RTI
910 * Distributed Logger
911 *
912 * This string is sent along on the state Topic and can help identify
913 * different applications within a system. You can use this field however
914 * you think it will help you most. The default value is "".
915 * \param [in] self Pointer to a working \ref RTI_DL_Options struct.
916 * \return Pointer to a char containing the current application kind
917 */
918extern RTIDLCDllExport char * RTI_DL_Options_getApplicationKind(
919 RTI_DL_Options * self);
920
921
922/*ce \ingroup RTI_DL_Options_Module
923 * \brief Sets the application kind that will be associated with RTI
924 * Distributed Logger
925 *
926 * This string is sent along on the state Topic and can help identify
927 * different applications within a system. You can use this field however
928 * you think it will help you most. The default value is "".
929 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct.
930 * \param [in] applicationKind Pointer to a string containing the new
931 * application kind. The maximum length of the string is 255.
932 * \return DDS_RETCODE_OK if the operation was a success.
933 */
934extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setApplicationKind(
935 RTI_DL_Options * self, const char *applicationKind);
936
937
938
939/*ce \ingroup RTI_DL_Options_Module
940 * \brief Gets the current value of echoToStdout option
941 *
942 * If true, RTI Distributed Logger prints the log messages received to the
943 * stdout. The default value is TRUE.
944 * \param [in] self Pointer to a working \ref RTI_DL_Options.
945 * \return Boolean to the current echoToStdout value
946 */
947extern RTIDLCDllExport RTIBool RTI_DL_Options_getEchoToStdout(
948 RTI_DL_Options * self);
949
950
951/*ce \ingroup RTI_DL_Options_Module
952 * \brief Sets the value of echoToStdout flag
953 *
954 * If true, RTI Distributed Logger prints the log messages received to the
955 * stdout. The default value is TRUE.
956 * \param [in,out] self Pointer to a working \ref RTI_DL_Options.
957 * \param [in] echoToStdout New value of set self.echoToStdout.
958 * \return DDS_RETCODE_OK if the operation was a success.
959 */
960extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setEchoToStdout(
961 RTI_DL_Options * self, RTIBool echoToStdout);
962
963
964/*ce \ingroup RTI_DL_Options_Module
965 * \brief Finalizes an \ref RTI_DL_Options struct. Checks whether the pointer
966 exists or not. Does not release memory.
967 * \param [in] self Pointer to a working \ref RTI_DL_Options struct. Checks
968 whether the parameter is NULL or not.
969 * \post \c self->domainParticipant will not be changed.
970 * \see RTI_DL_Options_delete
971*/
972extern RTIDLCDllExport void RTI_DL_Options_finalize(
973 RTI_DL_Options *self);
974
975
976/*ce \ingroup RTI_DL_Options_Module
977 * \brief Releases memory for a \ref RTI_DL_Options. Checks whether the pointer
978 exists or not.
979 * \param [in] self Pointer to a working \ref RTI_DL_Options struct. Checks
980 whether the parameter is NULL or not.
981 * \return NULL if everything goes as planned.
982 * \post \c self->domainParticipant will not be deleted.
983*/
984extern RTIDLCDllExport RTI_DL_Options* RTI_DL_Options_delete(
985 RTI_DL_Options *self);
986
987
988/*i \ingroup RTI_DL_Options_Module
989 * \brief Get the options used to configure the behavior of the Distributed
990 * Logger.
991 *
992 * \return A pointer to the \ref RTI_DL_Options struct containing the options
993 * used to configure the behavior of the Distributed Logger.
994 */
995extern RTIDLCDllExport
996const RTI_DL_Options * RTI_DL_DistLogger_getOptions(void);
997
998
999/*i
1000 * \ingroup RTI_DL_DistLogger_Module
1001 * \brief Disables the DL singleton
1002 *
1003 * Internal use only.
1004 * Disable the DL singleton and prepares it to be deleted.
1005 * It's called when finalizeInstance is called.
1006 */
1007extern RTIDLCDllExport
1008void RTI_DL_DistLogger_disable(void);
1009
1010
1011#ifdef __cplusplus
1012}
1013#endif
1014
1015#endif /* rti_dl_c_h */