rti_dl_xml_c.h

/*
 * (c) Copyright, Real-Time Innovations, 2012-2015.
 * 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_xml_c_h
#define rti_dl_xml_c_h
 
#include "rti_dl/rti_dl_dll_c.h"
#include "rti_dl/rti_dl_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_xml.h"
 
 
/* ------------------------------------------------------------ */
/*i
 * @defgroup RTI_DL_XMLConfig RTI DL XML Configuration API
 *
 * @brief This API contains the functions necessary by the RTI infrastructure
 * services and tools to use the RTI Distributed Logger.
 *
 * This API can be used for internal development when integrating RTI
 * Distributed Logger in the XML configuration of their application or service.
*/
/* ------------------------------------------------------------ */
 
/*i
 * @ingroup RTI_DL_XMLConfig
 * @brief The top level tag text for the Distributed Logger XML configuration
 * extension class. This constant is intended to be used by applications and
 * services using the Distributed Logger XML configuration capabilities when
 * registering the XML extension class with their RTI XML Parser instances.
 */
#define RTI_DL_XML_TOP_LEVEL_TAG "distributed_logger"
 
typedef void (*RTI_DL_XMLConfig_ParseErrorLogFunction)(
        const char *logMessage,
        const char *methodName,
        int lineNumber);
 
/* Forward declaration of type */
struct RTI_DL_XMLConfig;
 
 
typedef struct RTI_DL_XMLConfig RTI_DL_XMLConfig;
 
 
/*i
 * @ingroup RTI_DL_XMLConfig
 * @brief Create a new instance of the RTI Distributed Logger XML extension
 * class.
 *
 * The calling service or application is responsible for registering the
 * extension class with the RTI XML Parser.
 * @param parseErrorFunction A pointer to the method used to log
 * @return An instance of XML extension class associated with Distributed
 * Logger. If the instance could not be created, <code>NULL</code> is returned.
 */
extern RTIDLCDllExport struct RTIXMLExtensionClass *
RTI_DL_XMLConfig_createXMLExtensionClass(
        RTI_DL_XMLConfig_ParseErrorLogFunction parseErrorFunction);
 
 
/*i
 * @ingroup RTI_DL_XMLConfig
 * @brief Delete an instance of the Distributed Logger XML extension class.
 * @param extensionClass The extension class to be deleted.
 */
extern RTIDLCDllExport void RTI_DL_XMLConfig_destroyXMLExtensionClass(
        struct RTIXMLExtensionClass *extensionClass);
 
 
/*i
 * @ingroup RTI_DL_XMLConfig
 * @brief Helper method that gets the XML object associated with Distributed
 * Logger from a root XML object passed as a parameter.
 *
 * @param rootObject A valid non-null parent XML object.
 * @return The XML object associated with the Distributed Logger configuration.
 * If the object couldn't be found, <code>null</code> is returned.
 */
extern RTIDLCDllExport const RTI_DL_XMLConfig *
RTI_DL_XMLConfig_getXMLConfigFromXMLRoot(struct RTIXMLObject *rootObject);
 
/*i
 * Get the associated Distributed Logger XML object from a root XML DOM.
 * @param rootObject The root XML object to look for the Distributed Logger XML
 * configuration.
 * @return It returns <code>true</code> if the XML object associated with the
 * Distributed Logger configuration was found; otherwise it returns
 * <code>false</code>.
 */
extern RTIDLCDllExport struct RTIXMLObject *
RTI_DL_XMLConfig_getDLXMLObjectFromRoot(struct RTIXMLObject *rootObject);
 
/*i
 * @ingroup RTI_DL_XMLConfig
 * @brief Starts Distributed Logger using the options, the domain participant,
 * and a specific application kind string.
 *
 * This method is a utility method, useful for using Distributed Logger
 * within other services or applications that will provide the options (maybe
 * parsed via XML), the domain participant to hook up to, and the application
 * kind identification.
 * If the enabled setting in the options is set to false (it's disabled) then
 * Distributed Logger won't be started.
 * Also, if the Distributed Logger instance has already been created this method
 * has no effect (it doesn't finalize Distributed Logger and restart it; if this
 * is needed, the <code>RTI_DL_DistLogger_finalizeInstance</code> method has to
 * be used before calling this method again).
 * @pre The domainParticipant instance must be valid and non-null.
 * @pre The Distributed Logger options object passed as a parameter must be
 * valid and non-null.
 * @param domainParticipant The domain participant to use for logging.
 * @param xmlConfiguration The Distributed Logger configuration extracted from
 * the XML parsing process.
 * @param applicationKind The application kind string for the configuration
 * settings.
 * @return If the parameters are <code>null</code> or Distributed Logger could
 * not be started, returns <code>false</code>. If the <b>enabled</b> option in
 * the XML configuration is <code>true</code> and Distributed Logger could be
 * started, or the <b>enabled</b> option is <code>false</code>, returns
 * <code>true</code>.
 */
extern RTIDLCDllExport RTIBool RTI_DL_XMLConfig_startWithXMLConfiguration(
        DDS_DomainParticipant * domainParticipant, 
        RTI_DL_Options * options, 
        const char * applicationKind);
 
 
/*i
 * Get the Distributed Logger options obtained by the parsing process.
 * @param self A valid and non-null XML configuration instance to get the
 * Distributed Logger options from.
 * @return The DL options instance associated with this XML configuration
 * object, or <code>null</code> if it doesn't exist.
 */
extern RTIDLCDllExport RTI_DL_Options * RTI_DL_XMLConfig_getDLOptions(
        const struct RTI_DL_XMLConfig * self);
 
#endif /* rti_dl_xml_c_h */