rti_dl_cpp.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_cpp_h
#define rti_dl_cpp_h
 
 
/*e \file
 * \brief RTI Distributed Logger classes and methods
 */
 
#include "rti_dl/rti_dl_dll_cpp.h"
#include "rti_dl/rti_dl_c.h"
 
#include "dds_cpp/dds_cpp_domain.h"
 
 
class RTI_DLDistLogger; /* Forward declaration */
 
/*e 
 * \class RTI_DLOptions 
 * \ingroup RTI_DL_DistLogger_Module
 * \brief This class contains RTI Distributed Logger configurable options.
 *
 * Use this API to customize RTI Distributed Logger to adapt it to your needs.
 * Assign the newly created \ref RTI_DLOptions object to RTI Distributed Logger
 * singleton before calling to \ref RTI_DLDistLogger::getInstance.
 */
class RTIDLCPPDllExport RTI_DLOptions{
    friend class RTI_DLDistLogger;
public:
    /*e
     *  \brief Default constructor
     * 
     *  Allocates memory for a RTI_DLOptions class and sets the default values needed to create the DL.
     *  \see    ~RTI_DLOptions()
     */
    RTI_DLOptions();
 
    /*e
     *  \brief Default destructor
     * 
     *  Frees RTI_DLOptions class. Checks whether the pointer exists or not.
     *  If \c domainParticipant was assigned, its memory is not released.
     */
    ~RTI_DLOptions();
 
    /*e
     *  \brief Gets current C DomainParticipant.
     *
     * If a customized DomainParticipant have been set, this function returns a
     *  pointer to the internal C DomainParticipant that will be used to create
     *  DDS entities (Topics, Publishers, Subscribers, DataWriters, and
     *  DataReaders) needed by RTI Distributed Logger.
     *  The default value is NULL.
     *  \return  Pointer to the DDS_DomainParticipant contained in the class.
     *  Otherwise, NULL.
     */
    DDS_DomainParticipant * getCDomainParticipantI();
 
    /*e 
     *  \brief Sets current DomainParticipant.
     *
     *  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] domainParticipant  Pointer to a valid DDS_DomainParticipant
     *  \post   Memory must be released by the user \b after finalizing RTI
     *  Distributed Logger using \ref RTI_DLDistLogger::finalizeInstance.
     */
    DDS_ReturnCode_t setDomainParticipant(DDSDomainParticipant * domainParticipant);
 
    /*e
     *  \brief Sets current DomainParticipant.
     *
     * If true, remote administration Topics will be created and
     * used. If false, they will not be created. The default value
     * is true.
     * \return true if the Remote Administration is enabled. Otherwise false.
     */
    bool isRemoteAdministrationEnabled();
 
    /*e
     *  \brief Enables or disables remote administration
     *
     * Sets remote administration of the Topics to the value passed as
     * parameter.
     *  \param [in] enabled Boolean indicating new remote administration value.
     */
    DDS_ReturnCode_t setRemoteAdministrationEnabled(bool enabled);
 
    /*e 
     * \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.
     * See setFilterLevel() for more information on filter levels.
     *
     * \return integer containing the log filter level of the options.
     * \see RTI_DLDistLogger::setFilterLevel
     */
    int getFilterLevel();
 
    /*e 
     * \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] filterLevel   The log filter level of the options (see above).
     * \return     Error code.   DDS_RETCODE_OK if everything goes as planned.
     * \see RTI_DLDistLogger::setFilterLevel
    */
    DDS_ReturnCode_t setFilterLevel(int filterLevel);
 
    /*e
     *  \brief Gets the current Domain ID
     *
     * Returns the Domain ID to be used by RTI Distributed Logger. This value is
     * only used if \ref setDomainParticipant has NOT been called. Otherwise,
     * the Domain ID used is the one of the DomainParticipant assigned.
     *
     * The default value is 0.
     *  \return Integer containing the DDS Domain ID where RTI Distributed
     *  Logger instance will be created.
     */
    int getDomainId();
 
    /*e 
     *  \brief Sets the current Domain ID
     *
     * Updated the Domain ID to be used by RTI Distributed Logger. This value is
     * only used if \ref setDomainParticipant has NOT been called. Otherwise,
     * the Domain ID used is the one of the DomainParticipant assigned.
     *
     * The default value is 0.
     *  \param [in] domainId Int representing a DDS Domain ID. Max value: 250
     *  \return DDS_RETCODE_OK if the operation was a success.
     */    
    DDS_ReturnCode_t setDomainId(int domainId);
 
    /*e
     *  \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 run time for RTI
     * Distributed Logger to use. The default value is "".
     *  \return String containing the current Qos Library. Do not
     *  modify the content of this pointer directly nor delete it.
     */
    char *getQosLibrary();
 
    /*e
     * \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] qosLibrary String containing the new Qos Library. A copy of
     *  the string is made.
     * \return DDS_RETCODE_OK if the operation was a success.
     */
    DDS_ReturnCode_t setQosLibrary(const char *qosLibrary);
 
    /*e
     *  \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 "".
     *  \return String containing the current Qos Profile. Do not modify
     *  the content of this pointer directly nor delete it.
     */
    char *getQosProfile();
 
    /*e
     *  \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] qosProfile String containing the new Qos Profile. A copy of
     *  the string is made.
     *  \return DDS_RETCODE_OK if the operation was a success.
     */
    DDS_ReturnCode_t setQosProfile(const char *qosProfile);
 
   /*e
     * \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.
    *  \return Integer containing the current maximum queue size.
    */
    int getQueueSize();
   /*e
     *  \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] queueSize Integer containing the new maximum queue size.
     *  \return DDS_RETCODE_OK if the operation was a success.
     */
    DDS_ReturnCode_t setQueueSize(int queueSize);
 
    /*e
     * \brief Get the thread settings of the publishing threadthat will be
     * created by RTI Distributed Logger.
     *
     * This field contains general settings of the publishing thread in 
     * Distributed Logger, like the thread priority, stack size, and other
     * settings.
     * \return threadPriority Integer containing the current thread priority.
     */
    struct DDS_ThreadSettings_t * getThreadSettings();
 
    /*e
     * \brief Sets the settings of the publishing thread that will be created
     * by RTI Distributed Logger
     *
     * This parameter is used to control thread parameters such as priority, stack
     * size, and other settings. These settings will only affect the
     * publishing thread created by RTI Distributed Logger.
     * \param [in] threadSettings A valid DDS_ThreadSettings_t struct with the
     * settings for Distributed Logger's write thread.
     * \return DDS_RETCODE_OK if the operation was a success.
     */
    DDS_ReturnCode_t setThreadSettings(const struct DDS_ThreadSettings_t * threadSettings);
 
    /*e
     * \brief Gets the application kind that will be associated with RTI
     * Distributed Logger
     *
     * This char pointer 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 "".
     *
     *  \return String containing the current application kind.
     */
    char *getApplicationKind();
 
    /*e
     * \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] applicationKind String containing the new application kind.
     *  The maximum length of the string is 255.
     */
    DDS_ReturnCode_t setApplicationKind(const char *applicationKind);
    
    /*e 
     * \brief Gets the current value of echoToStdout
     *
     * If true, Distributed Logger prints the log messages received to the
     * stdout. The default value is TRUE.
     *  \return Boolean to the current echoToStdout value
     */
    bool getEchoToStdout();
 
    /*e
     * \brief Sets the value of echoToStdout
     *
     * If true, Distributed Logger prints the log messages received to the 
     * stdout. The default value is TRUE.
     *  \param [in] echoToStdout New value of set self.echoToStdout.
     */
    DDS_ReturnCode_t setEchoToStdout(bool echoToStdout);
    
    /*e 
     *  \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.
     *  \return Boolean to the current LogInfrastructureMessages value.
     */
    bool getLogInfrastructureMessages();
 
    /*e
     *  \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 NDDSConfigLogger's
     * 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] log Boolean indicating whether to enable this feature.
     *  \return DDS_RETCODE_OK if the operation was a success.
     */
    DDS_ReturnCode_t setLogInfrastructureMessages(bool log);
 
 
private:
    /*i
     * \brief This variable contains the real options.
     *
     * The RTI_DLOptions class is just a wrapper to the C implementation,
     * so this variable, created in the default constructor, is the one
     * containing the information. Check C Documentation for further details.
     */
    struct RTI_DL_Options *_impl;
 
    /*i
     * \brief Wrapping constructor.
     * Specific constructor that uses already created configuration options.
     * Its visibility is private, and it's oriented for internal usage.
     */
    RTI_DLOptions(struct RTI_DL_Options * options);
};
 
 
/*e 
 * \class RTI_DLUtility
 * \ingroup RTI_DL_DistLogger_Module
 * \brief Commodity functions for using RTI Distributed Logger
 */
class RTIDLCPPDllExport RTI_DLUtility {
public:
    /*e
     *  \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] msec Sleep duration in milliseconds.
     */
    static void sleep(int msec);
};
 
/*e
 * \defgroup RTI_DL_DistLogger_Module RTI Distributed Logger API
 * \brief Main API to use RTI Distributed Logger singleton.
 */
/*e
 * \class RTI_DLDistLogger
 * \ingroup RTI_DL_DistLogger_Module
 *
 * \brief This class contains RTI Distributed Logger singleton and the methods
 * to configure and use it.
 
 * This class is a <b>singleton</b>, so only one copy will be created.
 *  Use the \ref RTI_DLOptions class to customize the singleton \b BEFORE
 *  creating it.
 */
 
class RTIDLCPPDllExport RTI_DLDistLogger {
private:
    /*i
     * \brief This variable contains the actual RTI Distributed Logger
     * singleton.
     *
     *  The RTI_DLDistLogger class is just a wrapper to the C implementation,
     * so this variable, created in the default constructor, is the one
     * containing the information. Check C Documentation for further details.
     */
    struct RTI_DL_DistLogger *_impl;
 
    /*i
     * \brief RTI Distributed Logger singleton.
     *
     *  RTI_DLDistLogger is a singleton. This static variable is created
     *  the first time \ref getInstance() is called. It uses the default
     *  options unless \ref setOptions is called BEFORE creating the DL.
     */
    static RTI_DLDistLogger *instance;
 
    /*i
     * \brief Default constructor
     *
     * Creates the singleton. 
     * It's called when getInstance is called and _impl is NULL.
     */
    RTI_DLDistLogger();
 
    /*i
     * \brief Default destructor
     *
     * Destroys the singleton. 
     * It's called when finalizeInstance is called.
     */
    ~RTI_DLDistLogger();
                
public:
    /*e
     *  \brief Provides access to the RTI_DL_DistLogger singleton.
     *
     * This method provides access to the singleton instance of the RTI_DL_DistLogger. If
     * the instance does not exist, it will be created. Note that no change in
     * options is allowed after the singleton is created.
     * \return The singleton instance of the RTI_DL_DistLogger.
     */
    static RTI_DLDistLogger * getInstance();
 
    /*e
     *  \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.
     * 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] newLevel    The new filter level.
     *  \return     Error code. DDS_RETCODE_OK if everything goes as planned.
     *
     * The following table shows how RTI Connext DDS log levels map to RTI
     * Distributed Logger log filter levels.
     *
     * Not all RTI 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 getFatalLogLevel</TD>
     * </TR>
     * <TR>
     *    <TD>NDDS_CONFIG_LOG_LEVEL_ERROR</TD>
     *    <TD>RTI_DL_ERROR_LEVEL</TD>
     *    <TD>\ref getErrorLogLevel</TD>
     * </TR>
     * <TR>
     *    <TD>NDDS_CONFIG_LOG_LEVEL_WARNING</TD>
     *    <TD>RTI_DL_WARNING_LEVEL</TD>
     *    <TD>\ref getWarningLogLevel</TD>
     * </TR>
     * <TR>
     *    <TD>NDDS_CONFIG_LOG_LEVEL_STATUS_LOCAL</TD>
     *    <TD>RTI_DL_NOTICE_LEVEL</TD>
     *    <TD>\ref getNoticeLogLevel</TD>
     * </TR>
     * <TR>
     *    <TD>NDDS_CONFIG_LOG_LEVEL_STATUS_REMOTE</TD>
     *    <TD>RTI_DL_INFO_LEVEL</TD>
     *    <TD>\ref getInfoLogLevel</TD>
     * </TR>
     * <TR>
     *    <TD>NDDS_CONFIG_LOG_LEVEL_DEBUG</TD>
     *    <TD>RTI_DL_DEBUG_LEVEL</TD>
     *    <TD>\ref getDebugLogLevel</TD>
     * </TR>
     * </TABLE></CENTER>
     *
     */
    DDS_ReturnCode_t setFilterLevel(DDS_Long newLevel);
 
    /*e
     *  \brief Assigns configurable options to RTI Distributed Logger before its
     *  creation.
     *
     *  Assigns the values in the \c options to the \ref RTI_DLDistLogger
     *  singleton \b before its creation. If the singleton was already created,
     *  this function has no effect.
     *
     *  \param [in]     options   The new options to be assigned to the
     *                  \ref RTI_DLDistLogger singleton.
     *  \pre The \b singleton must be NULL.
     *  \return     RTI_TRUE if everything went as planned. RTI_FALSE if RTI
     *  Distributed Logger already existed.
     */
    static bool setOptions(RTI_DLOptions& options);
    
    /*e
     *  \brief Sets PrintFormat of RTI Logger to the provided value.
     *
     *  This method is mostly a pass-through to the appropriate call in RTI
     *  DDS library, but it also has the benefit of keeping the state of RTI
     *  Logger and RTI Distributed Logger in sync.
     *  \param [in]     logPrintFormat     The new PrintFormat.
     *  \return     RTI_TRUE if everything went as planned.
     */
    bool setRTILoggerPrintFormat(NDDS_Config_LogPrintFormat logPrintFormat);
    
    /*e
     *  \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 RTI
     *  DDS library, but it also has the benefit of keeping the state of RTI
     *  Logger and RTI Distributed Logger in sync.
     *  \param [in]     category    The category for which to set the verbosity.
     *  \param [in]     verbosity   The new verbosity level for the category.
     */
    void setRTILoggerVerbosityByCategory(NDDS_Config_LogCategory category, 
            NDDS_Config_LogVerbosity verbosity);
    
    /*e
     *  \brief Logs a message at the specified level and with the specified
     *  category.
     *
     *  \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.
     */
    void logMessageWithLevelCategory(int logLevel, const char *message, const char *category);
    
    /*e 
     *  \brief Performs the same function as \ref logMessageWithLevelCategory
     *  except that it also allows specification of the message timestamp.
     *
     *  \param [in] params      Parameters.
     */
    void logMessageWithParams(const struct RTI_DL_DistLogger_MessageParams & params);
    
    /*e
     *  \brief Logs a fatal message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_FATAL_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void fatal(const char *message);
    
    /*e
     *  \brief Logs a severe message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_SEVERE_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void severe(const char *message);
    
    /*e
     *  \brief Logs a error message
     *
     *  The message received is logged using  the default category and the
     *  RTI_DL_ERROR_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void error(const char *message);
    
    /*e
     *  \brief Logs a warning message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_WARNING_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void warning(const char *message);
    
    /*e
     *  \brief Logs a notice message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_NOTICE_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void notice(const char *message);
    
    /*e
     *  \brief Logs a info message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_INFO_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void info(const char *message);
    
    /*e
     *  \brief Logs a debug message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_DEBUG_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void debug(const char *message);
    
    /*e
     *  \brief Logs a trace message
     *
     *  The message received is logged using the default category and the
     *  RTI_DL_TRACE_LEVEL log level.
 
     *  \param [in] message     The message to log.
     */
    void trace(const char *message);
    
    /*e
     *  \brief Logs a message
     *
     *  The message received is logged using the default category and the
     *  given log level.
 
     *  \param [in] logLevel    The level of the log message.
     *  \param [in] message     The message to log.
     */
    void log(int logLevel, const char *message);
    
    /*e
     *  \brief Finalizes and delete the RTI_DL_DistLogger singleton. 
     *
     *  Unset the connections with DDS, frees memory and set singleton to NULL.
     */
    void finalizeInstance();
 
    /*e
    *  \brief Return Fatal log level.
    *
    *  \return  Fatal log level.
    */
    DDS_Long getFatalLogLevel();
 
    /*e
    *  \brief Return Error log level.
    *
    *  \return Error log level.
    */
    DDS_Long getErrorLogLevel();
 
    /*e
    *  \brief Return Warning log level.
    *
    *  \return Warning log level.
    */
    DDS_Long getWarningLogLevel();
 
    /*e
    *  \brief Return Notice log level.
    *
    *  \return Notice log level.
    */
    DDS_Long getNoticeLogLevel();
 
    /*e
    *  \brief Return Info log level.
    *
    *  \return Info log level.
    */
    DDS_Long getInfoLogLevel();
 
    /*e
    *  \brief Return Debug log level.
    *
    *  \return Debug log level.
    */
    DDS_Long getDebugLogLevel();
 
};
 
 
 
#endif /* rti_dl_cpp_h */