Merge pull request #324 from krocard/make-command-interface-public

Allow a client to send "remote" commands programmatically

Users can already send commands to a Parameter Framework instance through a
socket (provided that they asked for this interface to be started). Some
features are only available through this interface.

In upcoming patches, we want to use those features and send such commands but
we don't want to use a remote interface, which is sometimes painful. This patch
makes the "remote" commands available through a programmatic API. This API
expects a command name and a string-vector containing the arguments; which
makes it fairly easy to use and to implement a user interface providing the
same commands as they are used to - but without the need of a socket.

The object that provides this API is allocated by the Parameter Framework but
is owned by the client - we want to be C++03-retrocompatible, which forbids us
from returning a unique_ptr, this is why we return a raw pointer.

Author: krocard

.clang-format

@@ -90,4 +90,5 @@ PenaltyReturnTypeOnItsOwnLine: 10000
 ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH, GIVEN, WHEN, AND_WHEN, THEN, AND_THEN,
     SECTION ]
 
+SortIncludes: 'false'
 ...

parameter/CMakeLists.txt

@@ -36,6 +36,7 @@ add_library(parameter SHARED
     BitParameterType.cpp
     BitwiseAreaConfiguration.cpp
     BooleanParameterType.cpp
+    CommandHandlerWrapper.cpp
     ComponentInstance.cpp
     ComponentLibrary.cpp
     ComponentType.cpp
@@ -107,7 +108,7 @@ generate_export_header(parameter)
 target_link_libraries(parameter
     # Unfortunatly xmlSink and xmlSource need to be exposed to the plugins
     PUBLIC xmlserializer
-    PRIVATE remote-processor pfw_utility
+    PRIVATE pfw_utility remote-processor
     PRIVATE ${CMAKE_DL_LIBS})
 
 target_include_directories(parameter
@@ -121,6 +122,7 @@ install(TARGETS parameter LIBRARY DESTINATION lib RUNTIME DESTINATION bin ARCHIV
 # Client headers
 install(FILES
     "${CMAKE_CURRENT_BINARY_DIR}/parameter_export.h"
+    include/CommandHandlerInterface.h
     include/ElementHandle.h
     include/ParameterHandle.h
     include/ParameterMgrLoggerForward.h

parameter/CommandHandlerWrapper.cpp

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2015, Intel Corporation
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation and/or
+ * other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "CommandHandlerWrapper.h"
+#include <RequestMessage.h>
+
+CommandHandlerWrapper::CommandHandlerWrapper(std::unique_ptr<IRemoteCommandHandler> &&wrapped)
+    : mWrapped(std::move(wrapped))
+{
+}
+
+bool CommandHandlerWrapper::process(const std::string &command,
+                                    const std::vector<std::string> &arguments, std::string &output)
+{
+    CRequestMessage request(command);
+
+    for (auto &arg : arguments) {
+        request.addArgument(arg);
+    }
+
+    return mWrapped->remoteCommandProcess(request, output);
+}

parameter/CommandHandlerWrapper.h

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2015, Intel Corporation
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation and/or
+ * other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+#pragma once
+
+#include "CommandHandlerInterface.h"
+#include <RemoteCommandHandler.h>
+#include <memory>
+
+class CommandHandlerWrapper : public CommandHandlerInterface
+{
+public:
+    CommandHandlerWrapper(std::unique_ptr<IRemoteCommandHandler> &&wrapped);
+
+    bool process(const std::string &command, const std::vector<std::string> &arguments,
+                 std::string &output) override;
+
+private:
+    std::unique_ptr<IRemoteCommandHandler> mWrapped;
+};

parameter/ParameterMgr.cpp

@@ -2643,8 +2643,8 @@ bool CParameterMgr::serializeElement(std::ostream &output,
 
     // Use a doc source by loading data from instantiated Configurable Domains
     CXmlMemoryDocSource memorySource(&element, _bValidateSchemasOnStart,
-                                     element.getXmlElementName(),
-                                     "parameter-framework", getVersion());
+                                     element.getXmlElementName(), "parameter-framework",
+                                     getVersion());
 
     // Use a doc sink to write the doc data in a stream
     CXmlStreamDocSink sink(output);
@@ -2813,8 +2813,8 @@ void CParameterMgr::feedElementLibraries()
     pParameterCreationLibrary->addElementBuilder(
         "FloatingPointParameter", new TNamedElementBuilderTemplate<CFloatingPointParameterType>);
     pParameterCreationLibrary->addElementBuilder(
-        "SubsystemInclude", new CFileIncluderElementBuilder(_bValidateSchemasOnStart,
-                                                            getSchemaUri()));
+        "SubsystemInclude",
+        new CFileIncluderElementBuilder(_bValidateSchemasOnStart, getSchemaUri()));
 
     _pElementLibrarySet->addElementLibrary(pParameterCreationLibrary);
 
@@ -2843,22 +2843,9 @@ void CParameterMgr::setForceNoRemoteInterface(bool bForceNoRemoteInterface)
     _bForceNoRemoteInterface = bForceNoRemoteInterface;
 }
 
-// Remote Processor Server connection handling
-bool CParameterMgr::handleRemoteProcessingInterface(string &strError)
+CParameterMgr::CommandHandler CParameterMgr::createCommandHandler()
 {
-    LOG_CONTEXT("Handling remote processing interface");
-
-    if (_bForceNoRemoteInterface) {
-        // The user requested not to start the remote interface
-        return true;
-    }
-
-    // Start server only if tuning allowed
-    if (!getConstFrameworkConfiguration()->isTuningAllowed()) {
-        return true;
-    }
-
-    CCommandHandler *commandHandler = new CCommandHandler(this);
+    auto commandHandler = utility::make_unique<CCommandHandler>(this);
 
     // Add command parsers
     for (const auto &remoteCommandParserItem : gastRemoteCommandParserItems) {
@@ -2867,12 +2854,30 @@ bool CParameterMgr::handleRemoteProcessingInterface(string &strError)
             remoteCommandParserItem._minArgumentCount, remoteCommandParserItem._pcHelp,
             remoteCommandParserItem._pcDescription);
     }
-    std::unique_ptr<IRemoteCommandHandler> remoteCommandHandler(commandHandler);
+
+    return commandHandler;
+}
+
+bool CParameterMgr::isRemoteInterfaceRequired()
+{
+    // The remote interface should only be started if the client didn't
+    // explicitly forbid it and if the configuration file allows it.
+    return (not _bForceNoRemoteInterface) and getConstFrameworkConfiguration()->isTuningAllowed();
+}
+
+// Remote Processor Server connection handling
+bool CParameterMgr::handleRemoteProcessingInterface(string &strError)
+{
+    LOG_CONTEXT("Handling remote processing interface");
+
+    if (not isRemoteInterfaceRequired()) {
+        return true;
+    }
 
     auto port = getConstFrameworkConfiguration()->getServerPort();
 
     // The ownership of remoteComandHandler is given to Bg remote processor server.
-    _pRemoteProcessorServer = new BackgroundRemoteProcessorServer(port, remoteCommandHandler);
+    _pRemoteProcessorServer = new BackgroundRemoteProcessorServer(port, createCommandHandler());
 
     if (_pRemoteProcessorServer == NULL) {
         strError = "ParameterMgr: Unable to create Remote Processor Server";

parameter/ParameterMgr.h

@@ -79,21 +79,6 @@ class CParameterMgr : private CElement
         EParameterConfigurationLibrary
     };
 
-    // Remote command parsers
-    typedef TRemoteCommandHandlerTemplate<CParameterMgr> CCommandHandler;
-
-    typedef CCommandHandler::CommandStatus (CParameterMgr::*RemoteCommandParser)(
-        const IRemoteCommand &remoteCommand, std::string &strResult);
-
-    // Parser descriptions
-    struct SRemoteCommandParserItem
-    {
-        const char *_pcCommandName;
-        CParameterMgr::RemoteCommandParser _pfnParser;
-        size_t _minArgumentCount;
-        const char *_pcHelp;
-        const char *_pcDescription;
-    };
     // Version
     static const uint32_t guiEditionMajor = 3;
     static const uint32_t guiEditionMinor = 1;
@@ -116,6 +101,15 @@ class CParameterMgr : private CElement
       */
     bool load(std::string &strError);
 
+    // Remote command parsers
+    using CommandHandler = std::unique_ptr<TRemoteCommandHandlerTemplate<CParameterMgr>>;
+
+    /** Create and return a command handler for this ParameterMgr instance
+     *
+     * @returns a Command Handler
+     */
+    CommandHandler createCommandHandler();
+
     // Selection Criteria
     CSelectionCriterionType *createSelectionCriterionType(bool bIsInclusive);
     CSelectionCriterion *createSelectionCriterion(
@@ -411,6 +405,24 @@ class CParameterMgr : private CElement
     // Version
     std::string getVersion() const;
 
+    // This using is here for internal reasons: CommandHandler is public and is
+    // a unique_ptr but we want the type that's inside. And for legacy reason
+    // because that's the original name before a rework; this directive avoids
+    // renaming a lot of stuff.
+    using CCommandHandler = CommandHandler::element_type;
+    using RemoteCommandParser = CCommandHandler::CommandStatus (CParameterMgr::*)(
+        const IRemoteCommand &remoteCommand, std::string &strResult);
+
+    // Parser descriptions
+    struct SRemoteCommandParserItem
+    {
+        const char *_pcCommandName;
+        CParameterMgr::RemoteCommandParser _pfnParser;
+        size_t _minArgumentCount;
+        const char *_pcHelp;
+        const char *_pcDescription;
+    };
+
     ////////////////:: Remote command parsers
     /// Version
     CCommandHandler::CommandStatus versionCommandProcess(const IRemoteCommand &remoteCommand,
@@ -819,6 +831,7 @@ class CParameterMgr : private CElement
     void feedElementLibraries();
 
     // Remote Processor Server connection handling
+    bool isRemoteInterfaceRequired();
     bool handleRemoteProcessingInterface(std::string &strError);
 
     /** Log the result of a function

parameter/ParameterMgrFullConnector.cpp

@@ -31,6 +31,8 @@
 #include "ParameterMgr.h"
 #include "ParameterMgrLogger.h"
 
+#include "CommandHandlerWrapper.h"
+
 #include <list>
 
 using std::string;
@@ -40,6 +42,11 @@ CParameterMgrFullConnector::CParameterMgrFullConnector(const string &strConfigur
 {
 }
 
+CommandHandlerInterface *CParameterMgrFullConnector::createCommandHandler()
+{
+    return new CommandHandlerWrapper(_pParameterMgr->createCommandHandler());
+}
+
 void CParameterMgrFullConnector::setFailureOnMissingSubsystem(bool bFail)
 {
     std::string error;

parameter/include/CommandHandlerInterface.h

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2015, Intel Corporation
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation and/or
+ * other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+#pragma once
+
+#include <string>
+#include <vector>
+
+/** Class used to send commands to a parameter framework.
+ * @see the help command for more information on which command can be sent.
+ * @see ParameterMgrFullConnector::createCommandHandler to create an instance.
+ *
+ * This interface is primary designed to send commands without using a
+ * tcp socket for test purposes.
+ *
+ * Note: the fact that this class must be deleted by the client is because the
+ *       PF interface is not c++11.
+ * TODO: When the interface will transition to C++11, return directly the
+ *       CommandHandlerWrapper as this base class only use is to hide the
+ *       move semantic that is not supported in C++03.
+ */
+class CommandHandlerInterface
+{
+public:
+    /** Send a command synchronously and receive it's result.
+     *
+     * @see CParameterMgr::gastRemoteCommandParserItems for the list of possible
+     *      command and their description.
+     *
+     * @param[in] command the command to execute.
+     * @param[in] arguments the command arguments.
+     * @param[out] the result of the command.
+     *
+     * return true in the command executed succesfuly,
+     *        false otherwise.
+     */
+    virtual bool process(const std::string &command, const std::vector<std::string> &arguments,
+                         std::string &output) = 0;
+
+    virtual ~CommandHandlerInterface(){};
+};