rti_dl_c.h

/*
 * (c) Copyright, Real-Time Innovations, 2011-2016.
 * All rights reserved.
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */
 
#ifndef rti_dl_c_h
#define rti_dl_c_h
 
/*ce \file
 * \brief RTI Distributed Logger (DL) structs and functions
 */
#include "rti_dl/rti_dl_dll_c.h"
#include "log/log_dll.h"
#include "osapi/osapi_type.h"
#include "ndds/ndds_c.h"
#include "ndds/ndds_config_c.h"
 
#include "dds_c/dds_c_log_impl.h"
#include "dds_c/dds_c_infrastructure.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define RTI_DL_DEFAULT_QUEUE_SIZE  128
#define RTI_DL_DEFAULT_DOMAIN_ID 0
 
#define COMMAND_REQUEST_CONTENT_FILTERED_TOPIC_EXPRESSION \
  "targetHostAndAppId.rtps_host_id = %0 and targetHostAndAppId.rtps_app_id = " \
  "%1"
#define COMMAND_REQUEST_CONTENT_FILTERED_TOPIC_NAME \
  "CommandRequestContentFilteredTopic"
 
/*
 * DDS_Time_t initializer is hardcoded to avoid compilation issues in
 * Integrity platforms.
 */
#define RTI_DL_DistLogger_MessageParams_INITIALIZER \
  { \
    0, NULL, NULL, DDS_TIME_INVALID_VALUE \
  }
 
/* ------------------------------------------------------------ */
/*ce
 * \defgroup RTI_DL_DistLogger_Module RTI Distributed Logger API
 * @brief This module contains common definitions such as RTI Distributed
 *  Logger singleton, message sending functions, and general configuration.
 *
 * This module provides an API to publish log messages to a DDS Topic. Generally
 * this API is used by an application logging infrastructure to integrate it
 * into an application, although it is also possible to use the API directly.
 * In general, the steps to customize and use RTI Distributed Logger are the
 * following:
 * -# Customize your RTI Distributed Logger using the
 * \ref RTI_DL_Options_Module. \ref RTI_DL_Options must be set \b before
 * creating the \ref RTI_DL_DistLogger.
 * -# Assign the newly created options to RTI Distributed Logger using \ref
 * RTI_DL_DistLogger_setOptions.
 * -# Create your \ref RTI_DL_DistLogger_Module using \ref
 *  RTI_DL_DistLogger_getInstance. Make sure the instance was not created before
 *  or the option setup will have  no effect.
 * -# Finally, send your own log messages using \ref RTI_DL_DistLogger_Module
 * logging functions: \ref RTI_DL_DistLogger_error, \ref
 * RTI_DL_DistLogger_fatal, ...
 * Internal RTI Logger will be sent automatically once RTI Distributed
 *  Logger is created (no additional configuration required).
*/
 
 
/*ce
 * \defgroup RTI_DL_Options_Module RTI Distributed Logger Options API
 * \ingroup RTI_DL_DistLogger_Module
 * \brief Customize RTI Distributed Logger using this API.
*/
 
 
/*ce
 * \ingroup RTI_DL_Options_Module
    \struct RTI_DL_Options
    \brief This struct contains all RTI Distributed Logger's configurable
    options
 
    This struct must be created and configured \b before the first call to
    \ref RTI_DL_DistLogger_getInstance. To associate the options
    with the Distributed Logger, use the function
    \ref RTI_DL_DistLogger_setOptions. Use the functions in \ref
    RTI_DL_Options_Module to modify the different options.
*/
 
typedef struct RTI_DL_Options RTI_DL_Options;
 
 
 
/*---------------------------------------------------------------
           Dist Logger DDSEntities
 ----------------------------------------------------------------
*/
 
/*i \defgroup RTI_DL_DDSEntities_Module RTI Distributed Logger DDS Entities API
 * \ingroup RTI_DL_DistLogger_Module
 * \brief Functions and type definitions for internal DDS entities used by the
 * RTI Distributed Logger.
*/
/*i \ingroup RTI_DL_DDSEntities_Module
 *  \struct RTI_DL_DDSEntities
 *  \brief This class provides a wrapper of DDS entities.
*/
typedef struct RTI_DL_DDSEntities RTI_DL_DDSEntities;
 
 
 
 
/*ce
 * \ingroup RTI_DL_DistLogger_Module
 *  \struct RTI_DL_DistLogger
 *  \brief Struct defining RTI Distributed Logger singleton.
 *
 *  This struct is a <b>singleton</b>, so only one copy will be created.
 *  Use the \ref RTI_DL_Options_Module to customize the singleton \b BEFORE
 *  creating it.
 */
typedef struct RTI_DL_DistLogger RTI_DL_DistLogger;
 
 
 
/*ce
 * \ingroup RTI_DL_DistLogger_Module
 *  \brief Provides access to the \ref RTI_DL_DistLogger singleton.
 *
 * This method provides access to the singleton instance of RTI Distributed
 * Logger, \ref RTI_DL_DistLogger. If the instance does not exist, it will be
 * created. To customize it, use the \ref RTI_DL_Options_Module API \b BEFORE
 * creating the singleton the first time. Note that no change in options is
 * allowed after the singleton is created.
 * \return The singleton instance of \ref RTI_DL_DistLogger.
 * \note This function is only thread-safe on Linux and Windows platforms.
 */
extern RTIDLCDllExport RTI_DL_DistLogger * RTI_DL_DistLogger_getInstance(void);
 
 
 
/*i
 * \ingroup RTI_DL_DistLogger_Module
 *  \brief Provides access to the \ref RTI_DL_DistLogger singleton, specifying
 *  which DomainParticipantFactory should be used in case Distributed Logger
 *  needs to create its own DomainParticipant during singleton initialization.
 *
 * This method provides access to the singleton instance of RTI Distributed
 * Logger, \ref RTI_DL_DistLogger. If the instance does not exist, it will be
 * created. To customize it, use the \ref RTI_DL_Options_Module API \b BEFORE
 * creating the singleton the first time. Note that no change in options is
 * allowed after the singleton is created.
 *
 * \param [in] domainParticipantFactory Pointer to a valid
 *                       DDS_DomainParticipantFactory from which Distributed
 *                       Logger must create its DomainParticipant in case
 *                       that none is provided through the \ref RTI_DL_Options_Module
 *                       API
 *
 * \return The singleton instance of \ref RTI_DL_DistLogger.
 * \note This function is only thread-safe on Linux and Windows platforms.
 */
extern RTIDLCDllExport RTI_DL_DistLogger * RTI_DL_DistLogger_getInstanceI(
        DDS_DomainParticipantFactory *domainParticipantFactory);
 
 
/*ce
 * \ingroup RTI_DL_DistLogger_Module
 *  \brief Sets the filter level for the singleton.
 *
 * Filtering controls what type of log messages are sent.
 * This enables filtering on the \em sending side (in the application using
 * Distributed Logger). You can also enable filtering on the \em receiving side
 * (such as in a tool that receives log messages, like RTI Admin Console or
 * RTI Monitor).
 *
 * Supported Filter Levels: See the table below.
 * The default value is RTI_DL_INFO_LEVEL.
 *
 * Or see the IDL file provided with Distributed Logger
 * (file: \ref_url_dl_idl). In the IDL file, there are language-specific bindings.
 * Prepend the appropriate binding to the filter level shown in the IDL.
 * For example, one of the filter levels in the IDL is INFO_LEVEL.
 * To refer to this filter level in C, use RTI_DL_INFO_LEVEL.
 *
 * Log messages up to and including the specified filter level will pass through
 * the filter and be sent on the network. For example, the WARNING level allows
 * log messages up to and including the WARNING level (FATAL, SEVERE, ERROR, and
 * WARNING) to be sent; any other log messages with numerically higher filter
 * levels (INFO, DEBUG, and TRACE) will be filtered out and not sent.
 *
 * \param [in,out] self        Pointer to the \ref RTI_DL_DistLogger
 * \param [in]     newLevel    The new log level.
 * \return  Error code. DDS_RETCODE_OK if everything went as planned.
 *
 * The following table shows how RTI Connext DDS log levels (RTI Logger) map to
 * RTI Distributed Logger log filter levels.
 *
 * Not all Distributed Logger levels appear in this table because
 * there is not a one-to-one mapping between RTI Connext DDS and RTI Distributed
 * Logger levels (there are more levels in RTI Distributed Logger).
 * You can obtain the filter level using a constant defined in the Distributed
 * Logger IDL file or a getter function in the Distributed Logger API.
 *
 * <CENTER><TABLE>
 * <CAPTION><EM>Filter Levels</EM></CAPTION>
 * <TR>
 * <TH> Connext DDS API constant </TH>
 * <TH> Distributed Logger IDL constant </TH>
 * <TH> Distributed Logger API getter </TH>
 * </TR>
 * <TR>
 *    <TD>NDDS_CONFIG_LOG_FATAL_ERROR</TD>
 *    <TD>RTI_DL_FATAL_LEVEL</TD>
 *    <TD>\ref RTI_DL_DistLogger_get_fatal_log_level</TD>
 * </TR>
 * <TR>
 *    <TD>NDDS_CONFIG_LOG_LEVEL_ERROR</TD>
 *    <TD>RTI_DL_ERROR_LEVEL</TD>
 *    <TD>\ref RTI_DL_DistLogger_get_error_log_level</TD>
 * </TR>
 * <TR>
 *    <TD>NDDS_CONFIG_LOG_LEVEL_WARNING</TD>
 *    <TD>RTI_DL_WARNING_LEVEL</TD>
 *    <TD>\ref RTI_DL_DistLogger_get_warning_log_level</TD>
 * </TR>
 * <TR>
 *    <TD>NDDS_CONFIG_LOG_LEVEL_STATUS_LOCAL</TD>
 *    <TD>RTI_DL_NOTICE_LEVEL</TD>
 *    <TD>\ref RTI_DL_DistLogger_get_notice_log_level</TD>
 * </TR>
 * <TR>
 *    <TD>NDDS_CONFIG_LOG_LEVEL_STATUS_REMOTE</TD>
 *    <TD>RTI_DL_INFO_LEVEL</TD>
 *    <TD>\ref RTI_DL_DistLogger_get_info_log_level</TD>
 * </TR>
 * <TR>
 *    <TD>NDDS_CONFIG_LOG_LEVEL_DEBUG</TD>
 *    <TD>RTI_DL_DEBUG_LEVEL</TD>
 *    <TD>\ref RTI_DL_DistLogger_get_debug_log_level</TD>
 * </TR>
 * </TABLE></CENTER>
 *
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_DistLogger_setFilterLevel(
        RTI_DL_DistLogger *self, DDS_Long newLevel);
 
 
/*ce
 * \ingroup RTI_DL_DistLogger_Module
 *  \brief Assigns configurable options to RTI Distributed Logger before its
 *  creation.
 *
 *  Assigns the values in the \ref RTI_DL_Options struct to the
 *  \ref RTI_DL_DistLogger singleton \b before its creation. If the singleton was
 *  already created, this function has no effect.
 *  \param [in]     options  New options to be assigned to the
 *                  \ref RTI_DL_DistLogger singleton.
 *  \pre    self must be NULL.
 *  \return     RTI_TRUE if everything went as planned. RTI_FALSE if RTI
 *  Distributed Logger already existed.
 */
 
extern RTIDLCDllExport RTIBool RTI_DL_DistLogger_setOptions(const RTI_DL_Options *options);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Sets PrintFormat of RTI Logger to the provided value.
 *
 *  This method is mostly a pass-through to the appropriate call in the RTI Connext 
 *  DDS library, but it also has the benefit of keeping the state of RTI
 *  Logger and RTI Distributed Logger in sync.
 *  \param [in,out] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in]     logPrintFormat     The new PrintFormat.
 *  \return     RTI_TRUE if everything went as planned.
 */
extern RTIDLCDllExport RTIBool RTI_DL_DistLogger_setRTILoggerPrintFormat(
        RTI_DL_DistLogger *self, NDDS_Config_LogPrintFormat logPrintFormat);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Updates the LogCategory and the LogVerbosity in RTI Logger to the
 *  provided value.
 *
 *  This method is mostly a pass-through to the appropriate call in the RTI Connext 
 *  DDS library, but it also has the benefit of keeping the state of RTI
 *  Logger and RTI Distributed Logger in sync.
 *  \param [in,out] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in]     category    The category for which to set the verbosity.
 *  \param [in]     verbosity   The new verbosity level for the category.
 *  \return <code>true</code> if the call was successful,
 *  or <code>false</code> otherwise.
 */
extern RTIDLCDllExport RTIBool RTI_DL_DistLogger_setRTILoggerVerbosityByCategory(
        RTI_DL_DistLogger *self, NDDS_Config_LogCategory category,
        NDDS_Config_LogVerbosity verbosity);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Input parameters for \ref RTI_DL_DistLogger_logMessageWithParams
 */
struct RTI_DL_DistLogger_MessageParams {
    /*e
     *  The level of the log message.
     */
    int log_level;
 
    /*e
     *  The message to log. It must be non-NULL.
     */
    const char *message;
 
    /*e
     *  The category of the log message.
     */
    const char *category;
 
    /*e
     *  The timestamp with which the message will be logged.
     */
    struct DDS_Time_t timestamp;
};
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a message at the specified level and with the specified
 *  category.
 *
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] logLevel    The level of the log message.
 *  \param [in] message     The message to log.
 *  \param [in] category    The category of the log message.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_logMessageWithLevelCategory(
        RTI_DL_DistLogger *self, int logLevel, const char *message,
        const char *category);
 
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Performs the same function as \ref RTI_DL_DistLogger_logMessageWithLevelCategory
 *  except that it also allows specification of the message timestamp.
 *
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] params      Parameters.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_logMessageWithParams(
        RTI_DL_DistLogger *self,
        const struct RTI_DL_DistLogger_MessageParams *params);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a fatal message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_FATAL_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_fatal(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a severe message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_SEVERE_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_severe(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a error message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_ERROR_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_error(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a warning message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_WARNING_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_warning(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a notice message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_NOTICE_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_notice(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a info message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_INFO_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_info(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a debug message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_DEBUG_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_debug(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a trace message
 *
 *  The message received is logged using the default category and the
 *  RTI_DL_TRACE_LEVEL log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_trace(RTI_DL_DistLogger *self,
        const char *message);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Logs a message
 *
 *  The message received is logged using the default category and the
 *  given log level.
 *  \param [in] self        Pointer to the \ref RTI_DL_DistLogger
 *  \param [in] logLevel    The level of the log message.
 *  \param [in] message     The message to log.
 */
extern RTIDLCDllExport void RTI_DL_DistLogger_log(RTI_DL_DistLogger *self,
        int logLevel, const char *message);
 
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Finalizes and deletes the RTI Distributed Logger singleton.
 *
 *  Unset the connections with DDS, free memory, and set the singleton to NULL
 *  \return  DDS_RETCODE_OK if everything went as planned. Otherwise, an
 *           error code is returned.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_DistLogger_finalizeInstance(void);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Return Fatal log level.
 *
 *  \return  Fatal log level.
 */
extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_fatal_log_level(void);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Return Error log level.
 *
 *  \return Error log level.
 */
extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_error_log_level(void);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Return Warning log level.
 *
 *  \return Warning log level.
 */
extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_warning_log_level(void);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Return Notice log level.
 *
 *  \return Notice log level.
 */
extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_notice_log_level(void);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Return Info log level.
 *
 *  \return Info log level.
 */
extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_info_log_level(void);
 
 
/*ce \ingroup RTI_DL_DistLogger_Module
 *  \brief Return Debug log level.
 *
 *  \return Debug log level.
 */
extern RTIDLCDllExport DDS_Long RTI_DL_DistLogger_get_debug_log_level(void);
 
 
/*------------------------------------------------*/
/*ce \defgroup RTI_DL_Utility_Module RTI Distributed Logger Utility Module
* \ingroup RTI_DL_DistLogger_Module
* \brief Commodity functions to work with RTI Distributed Logger .
*/
/*ce
 * \ingroup RTI_DL_Utility_Module
 * \brief Blocks the calling thread for the specified duration.
 *
 * Note that the achievable resolution of sleep is OS-dependent.
 * That is, do not assume that you can sleep for 1 ms just
 * because you can specify a 1-ms sleep duration via the API.
 * The sleep resolution on most operating systems is usually 10 ms or greater.
 *
 * \param [in] ms Sleep duration in milliseconds.
 */
extern RTIDLCDllExport void RTI_DL_Utility_sleep(int ms);
 
 
 
/*------------------------------------------------*/
/*i \defgroup RTI_DL_LogMessageWriteThread RTI DL LogMessageWriteThread API
 * \ingroup RTI_DL_DistLogger_Module
 *  This struct and functions are responsible for pulling log messages from its input queue,
 * formatting them to the type used with DDS, and publishing them to the DDS
 * Topic.
*/
/*i \ingroup RTI_DL_LogMessageWriteThread
 *  \struct RTI_DL_LogMessageWriteThread
 *  \brief This struct holds the log message and the queue needed to push them to DDS.
*/
typedef struct RTI_DL_LogMessageWriteThread LogMessageWriteThread;
 
 
/*---------------------------------------------------------------
           Dist Logger Options (Options)
 ----------------------------------------------------------------
*/
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief  Initializes a \ref RTI_DL_Options struct with the default
 * values needed to create the Distributed Logger.
*/
extern RTIDLCDllExport void RTI_DL_Options_initialize(RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief  Allocates memory for a \ref RTI_DL_Options struct and sets the default
 * values needed to create the Distributed Logger.
 * \return Pointer to a working \ref RTI_DL_Options struct
 * \post Memory must be release using \ref RTI_DL_Options_delete
 * \see  RTI_DL_Options_delete()
*/
extern RTIDLCDllExport RTI_DL_Options * RTI_DL_Options_createDefault(void);
 
 
/*e
 * \ingroup RTI_DL_Options_Module
 * \brief Create a copy of a RTI Distributed Logger options instance.
 *
 * This method creates a deep copy of a RTI Distributed Logger options object.
 *
 * \pre The self options instance is not null and has been initialized with the
 * default values.
 * 
 * \param [out] self Already created \ref RTI_DL_Options struct where we want
 *                      to copy the values in.
 * \param [in] other \ref RTI_DL_Options containing the values to be copied in
 *                   \c self.
 * \return If the copy process was successful then returns <code>true</code>.
 * Otherwise it returns <code>false</code>.
 */
extern RTIDLCDllExport RTIBool RTI_DL_Options_copy(RTI_DL_Options * self,
        const RTI_DL_Options * other);
 
 
/*e
 * \ingroup RTI_DL_Options_Module
 * \brief Checks for equality between two \ref RTI_DL_Options objects.
 * \param [in] self an \ref RTI_DL_Options object.
 * \param [in] other an \ref RTI_DL_Options object.
 * \return <code>true</code> if the two objects are equal.
 * Returns <code>false</code> otherwise.
 */
extern RTIDLCDllExport RTIBool RTI_DL_Options_equals(
        const RTI_DL_Options * self, const RTI_DL_Options * other);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Gets the current DomainParticipant that will be used to create the
 *  RTI Distributed Logger's internal entities.
 *
 *  If a customized DomainParticipant has been set, this function returns a
 *  pointer to it. If this field is not null, this is the
 *  DomainParticipant. Otherwise, it returns the default value, NULL.
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct
 *  \return  Pointer to the DDS_DomainParticipant contained in the struct.
 *  \see RTI_DL_Options_getDomainParticipant
 */
extern RTIDLCDllExport DDS_DomainParticipant *
                RTI_DL_Options_getDomainParticipant(RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Sets the DomainParticipant to be used to create RTI
 *  Distributed Logger internal entities.
 *
 *  There are several use cases in which you may want to use your own
 *  DomainParticipant to create RTI Distributed Logger internal DDS
 *  entities. By calling this function, you will have control of the
 *  DomainParticipant used by RTI Distributed Logger. Once assigned,
 *  \c \b domainParticipant will be used to create the DDS entities (Topics,
 *  Publishers, Subscribers, DataWriters, & DataReaders) needed by RTI
 *  Distributed Logger.
 *
 *  When the DomainParticipant is set to a non-NULL value,
 *  it is the user's responsibility to handle the memory associated
 *  with it.
 *
 *  \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct
 *  \param [in] domainParticipant   Pointer to a valid DDS_DomainParticipant
 *  \post   Memory must be released by the user \b after finalizing RTI
 *  Distributed Logger using \ref RTI_DL_DistLogger_finalizeInstance.
 *  \return DDS_RETCODE_OK if the operation was a success. 
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setDomainParticipant(
        RTI_DL_Options * self, DDS_DomainParticipant * domainParticipant);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Indicates whether Distributed Logger should also log all
 *         messages produced by infrastructure code automatically.
 *
 * If true, messages produced by either the middleware or the tools will
 * be forwarded to Distributed Logger.
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct
 *  \return Boolean to the current LogInfrastructureMessages value.
 */
extern RTIDLCDllExport RTIBool RTI_DL_Options_getLogInfrastructureMessages(
        RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Enables or disables automatic logging of infrastructure messages
 *
 * If true, messages produced by either the middleware or the tools will
 * be forwarded to Distributed Logger. In this mode Distributed Logger uses
 * NDDS_Config_Logger_set_output_device() API to receive messages from the
 * middleware. Hence any device previously registered with
 * NDDS_Config_Logger_set_output_device() API will be unregistered. Similarly
 * Distributed Logger will stop logging infrastructure messages if the
 * set_output_device() API is used to register a new device after the creation
 * of the Distributed Logger instance.
 *
 *  \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct
 *  \param [in] log Boolean indicating whether to enable this feature.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t
        RTI_DL_Options_setLogInfrastructureMessages(RTI_DL_Options * self,
                RTIBool log);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Indicates whether remote administration is enabled or not
 *
 * If true, remote administration Topics will be created and
 * used. If false, they will not be created. The default value
 * is true.
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct
 *  \return true if the Remote Administration is enabled. Otherwise false.
 */
extern RTIDLCDllExport RTIBool RTI_DL_Options_isRemoteAdministrationEnabled(
        RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Enables or disables remote administration
 *
 * Sets remote administration of the Topics to the value passed as
 * a parameter.
 *  \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct
 *  \param [in] enabled Boolean indicating new remote administration value.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t
        RTI_DL_Options_setRemoteAdministrationEnabled(RTI_DL_Options * self,
                RTIBool enabled);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Gets the log filter level.
 *
 * Supported Filter Levels: See the IDL file provided with RTI Distributed
 * Logger (\ref_url_dl_idl)
 *  
 * The default value is RTI_DL_INFO_LEVEL.
 *
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct
 *  \return integer containing the log filter level value of the options.
 *  \see RTI_DL_DistLogger_setFilterLevel
 */
extern RTIDLCDllExport int RTI_DL_Options_getFilterLevel(RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Sets the log filter level.
 *
 * Filtering controls what type of log messages are sent.
 * This enables filtering on the \em sending side (in the application using 
 * RTI Distributed Logger). You can also enable filtering on the \em receiving
 * side (such as in a tool that receives log messages, like RTI Admin Console or
 * RTI Monitor).
 *
 * Supported Filter Levels: See the IDL file provided with RTI Distributed
 * Logger (\ref_url_dl_idl).
 * The default value is RTI_DL_INFO_LEVEL.
 
 *
 * \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct
 * \param [in] filterLevel    Integer containing the log filter level value of the
 *                         options.
 * \return DDS_RETCODE_OK if the operation was a success
 * \see RTI_DL_DistLogger_setFilter for more details.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setFilterLevel(
        RTI_DL_Options * self, int filterLevel);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Gets the current Domain ID
 *
 * Returns the Domain ID to be used by RTI Distributed Logger. This value is
 * only used if \ref RTI_DL_Options_setDomainParticipant has NOT been called.
 * Otherwise, the Domain ID used is the one of the DomainParticipant assigned
 *
 * The default value is 0.
 *  \param [in] self  Pointer to a working \ref RTI_DL_Options struct
 *  \return Integer containing the DDS Domain ID where RTI Distributed
 *  Logger instance will be created.
 */
extern RTIDLCDllExport int RTI_DL_Options_getDomainId(RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Sets the current Domain ID
 *
 * Updated the Domain ID to be used by RTI Distributed Logger. This value is
 * only used if \ref RTI_DL_Options_setDomainParticipant has NOT been called.
 * Otherwise, the Domain ID used is the one of the DomainParticipant assigned.
 *
 * The default value is 0.
 *  \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct.
 *  \param [in] domainId Integer representing a DDS Domain ID. Max value 250.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setDomainId(
        RTI_DL_Options * self, int domainId);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Gets the Qos Library that will be used to create to RTI
 *  Distributed Logger
 *
 * The QoS library name to use when creating DDS entities. It is up to the
 * application to ensure that this library is available at runtime for RTI
 * Distributed Logger to use. The default value is "".
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct
 *  \return Pointer to a string containing the current Qos Library. Do not
 *  modify the content of this pointer directly nor delete it.
 */
extern RTIDLCDllExport char * RTI_DL_Options_getQosLibrary(
        RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Sets the Qos Library that will be used to create to RTI
 *  Distributed Logger
 *
 * The QoS library name to use when creating DDS entities. It is up to the
 * application to ensure that this library is available at run time for the 
 * Distributed Logger to use.
 *
 * \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct.
 * \param [in] qosLibrary Pointer to a char containing the new Qos Library. A
 *  copy of the string is made.
 * \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setQosLibrary(
        RTI_DL_Options * self, const char *qosLibrary);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Gets the Qos Profile that will be used to create to RTI
 *  Distributed Logger
 *
 * The QoS profile name to use when creating DDS entities. It is up to the
 * application to ensure that this profile is available at run time for the 
 * Distributed Logger to use. The default value is "".
 *
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct.
 *  \return Pointer to a char containing the current Qos Profile. Do not modify
 *  the content of this pointer directly nor delete it.
 */
extern RTIDLCDllExport char * RTI_DL_Options_getQosProfile(
        RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Sets the Qos Profile that will be used to create to RTI
 *  Distributed Logger
 *
 * The QoS profile name to use when creating DDS entities. It is up to the
 * application to ensure that this profile is available at run time for the 
 * Distributed Logger to use.
 *
 *  \param[in,out]  self Pointer to a working \ref RTI_DL_Options struct.
 *  \param [in] qosProfile Pointer to a char containing the new Qos profile. A
 *  copy of the string is made.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setQosProfile(
        RTI_DL_Options * self, const char *qosProfile);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Gets the maximum queue size that will be assigned to RTI
 *  Distributed Logger
 *
 * This field controls the size of the queue used to temporarily store log
 * messages from the application until they can be written out to
 * DDS. The default value is RTI_DL_DEFAULT_QUEUE_SIZE.
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct
 *  \return Integer containing the current maximum queue size.
 */
extern RTIDLCDllExport int RTI_DL_Options_getQueueSize(RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 *  \brief Sets the maximum queue size that will be assigned to RTI
 *  Distributed Logger
 *
 * This field controls the size of the queue used to temporarily store log
 * messages from the application until they can be written out to
 * DDS. 
 *  \param [in,out] self  Pointer to a working \ref RTI_DL_Options struct.
 *  \param [in] queueSize Integer containing the new maximum queue size.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setQueueSize(
        RTI_DL_Options * self, int queueSize);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Gets the thread settings of the publishing thread that will be created
 * by RTI Distributed Logger
 *
 * This fields controls the priority of the thread that sends the 
 * messages through DDS. The default values are defined in dds_c_infrastructure.h.
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct.
 * \return The thread settings defined in the options.
 */
extern RTIDLCDllExport struct DDS_ThreadSettings_t *
                        RTI_DL_Options_getThreadSettings(RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Sets the settings of the publishing thread that will be created
 * by RTI Distributed Logger
 *
 * This field controls the settings of the thread that sends the 
 * messages through DDS. These settings only affect the publishing thread
 * created by RTI Distributed Logger.
 * \param [in,out] self Pointer to a working \ref RTI_DL_Options struct.
 * \param [in] threadSettings The thread settings to apply to the options.
 *                  Must be a valid RTI_OSAPI_THREAD_PRIORITY value.
 * \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setThreadSettings(
        RTI_DL_Options * self,
        const struct DDS_ThreadSettings_t * threadSettings);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Gets the application kind that will be associated with RTI
 * Distributed Logger
 *
 * This string is sent along on the state Topic and can help identify
 * different applications within a system. You can use this field however
 * you think it will help you most. The default value is "".
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options struct.
 *  \return Pointer to a char containing the current application kind
 */
extern RTIDLCDllExport char * RTI_DL_Options_getApplicationKind(
        RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Sets the application kind that will be associated with RTI
 * Distributed Logger
 *
 * This string is sent along on the state Topic and can help identify
 * different applications within a system. You can use this field however
 * you think it will help you most. The default value is "".
 *  \param [in,out] self    Pointer to a working \ref RTI_DL_Options struct.
 *  \param [in] applicationKind Pointer to a string containing the new
 *              application kind. The maximum length of the string is 255.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setApplicationKind(
        RTI_DL_Options * self, const char *applicationKind);
 
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Gets the current value of echoToStdout option
 *
 * If true, RTI Distributed Logger prints the log messages received to the
 * stdout. The default value is TRUE.
 *  \param [in] self    Pointer to a working \ref RTI_DL_Options.
 *  \return Boolean to the current echoToStdout value
 */
extern RTIDLCDllExport RTIBool RTI_DL_Options_getEchoToStdout(
        RTI_DL_Options * self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief Sets the value of echoToStdout flag
 *
 * If true, RTI Distributed Logger prints the log messages received to the
 * stdout. The default value is TRUE.
 *  \param [in,out] self    Pointer to a working \ref RTI_DL_Options.
 *  \param [in] echoToStdout New value of set self.echoToStdout.
 *  \return DDS_RETCODE_OK if the operation was a success.
 */
extern RTIDLCDllExport DDS_ReturnCode_t RTI_DL_Options_setEchoToStdout(
        RTI_DL_Options * self, RTIBool echoToStdout);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief  Finalizes an \ref RTI_DL_Options struct. Checks whether the pointer
    exists or not. Does not release memory.
 * \param [in] self Pointer to a working \ref RTI_DL_Options struct. Checks
    whether the parameter is NULL or not.
 * \post \c self->domainParticipant will not be changed.
 *  \see RTI_DL_Options_delete
*/
extern RTIDLCDllExport void RTI_DL_Options_finalize(
        RTI_DL_Options *self);
 
 
/*ce \ingroup RTI_DL_Options_Module
 * \brief  Releases memory for a \ref RTI_DL_Options. Checks whether the pointer
    exists or not.
 * \param [in] self Pointer to a working \ref RTI_DL_Options struct. Checks
    whether the parameter is NULL or not.
 * \return NULL if everything goes as planned.
 * \post \c self->domainParticipant will not be deleted.
*/
extern RTIDLCDllExport RTI_DL_Options* RTI_DL_Options_delete(
        RTI_DL_Options *self);
 
 
/*i \ingroup RTI_DL_Options_Module
 * \brief Get the options used to configure the behavior of the Distributed 
 * Logger.
 *
 * \return A pointer to the \ref RTI_DL_Options struct containing the options 
 * used to configure the behavior of the Distributed Logger.
 */
extern RTIDLCDllExport 
const RTI_DL_Options * RTI_DL_DistLogger_getOptions(void);
 
 
/*i
 * \ingroup RTI_DL_DistLogger_Module
 * \brief Disables the DL singleton
 *
 * Internal use only.
 * Disable the DL singleton and prepares it to be deleted.
 * It's called when finalizeInstance is called.
 */
extern RTIDLCDllExport
void RTI_DL_DistLogger_disable(void);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* rti_dl_c_h */