include/settingsd/response_callback.hpp

   1 /**
   2  * @file response_callback.hpp
   3  *
   4  * @brief Settings response callback header.
   5  *
   6  * @author Ossama Othman @<ossama.othman@@intel.com@>
   7  *
   8  * @copyright @par
   9  * Copyright 2012, 2013 Intel Corporation All Rights Reserved.
  10  * @par
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public
  13  * License as published by the Free Software Foundation;
  14  * version 2.1 of the License.
  15  * @par
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  * @par
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with this library; if not, write to the Free Software
  23  * Foundation, Inc., 51 Franklin Street, Fifth Floor,
  24  * Boston, MA  02110-1301  USA
  25  */
  26
  27
  28 #ifndef IVI_SETTINGS_RESPONSE_CALLBACK_HPP
  29 #define IVI_SETTINGS_RESPONSE_CALLBACK_HPP
  30
  31 #include <settingsd/settings_api.hpp>
  32
  33 #include <libwebsockets.h>
  34 #include <json-glib/json-glib.h>
  35
  36 #include <functional>
  37 #include <string>
  38
  39
  40 namespace ivi
  41 {
  42   namespace settings
  43   {
  44     template<typename T> class smart_ptr;
  45
  46     /**
  47      * @class response_callback response_callback.hpp <settingsd/response_callback.hpp>
  48      *
  49      * @brief Callback that handles sending response to Settings app.
  50      *
  51      * A @c response_callback sends a JSON formatted response string
  52      * to the Settings app.  It is up to the specific settings plugin
  53      * to decide what goes in to the response.
  54      */
  55     class SETTINGS_API response_callback
  56     {
  57     public:
  58
  59       /// Constructor
  60       response_callback(struct libwebsocket * wsi,
  61                         std::string type,
  62                         std::string transaction_id);
  63
  64       /// Destructor.
  65       ~response_callback();
  66
  67       /**
  68        * Send (successful) response to Settings app.
  69        *
  70        * The settings daemon requires that plugins use the json-glib
  71        * library to build JSON respons strings.  Plugins will pass a
  72        * callback function @a response_builder that uses to the
  73        * json-glib high level "builder" API to append the results of
  74        * the successful Settings app request to the JSON response
  75        * string.  Plugins should take care to only use the builder
  76        * functions that add members and their corresponding to
  77        * values.  They should not attempt to start or end the top
  78        * level JSON object.  That will be automatically handled by
  79        * this class.
  80        *
  81        * @param[in] response_builder Callback function that appends
  82        *                             JSON formatted response data.
  83        */
  84       bool send_response(
  85         std::function<void(JsonBuilder *)> response_builder);
  86
  87       /**
  88        * Send error response to Settings app.
  89        *
  90        * @param[in] error_message Free form error message.
  91        */
  92       bool send_error(std::string error_message);
  93
  94       /**
  95        * The settings type/ID associated with the request and
  96        * response.
  97        *
  98        * @note This method is generally used for debugging purposes,
  99        *       alone.
 100        */
 101       std::string const & type() const { return type_; }
 102
 103     private:
 104
 105       /**
 106        * Add string value to the response.  If the string is empty a
 107        * null JSON value will be added instead.
 108        */
 109       void add_string_value(JsonBuilder * builder,
 110                             std::string const & name,
 111                             std::string const & value);
 112
 113       /**
 114        * Begin the JSON formatted response to the Settings app
 115        * request.
 116        *
 117        * The appropriate "header" information will be prepended to the
 118        * response, such as transaction ID and result success or
 119        * failure.
 120        *
 121        * @param[in] result @c "succeeded" or @c "failed"
 122        */
 123       smart_ptr<JsonBuilder> begin_response(char const * result);
 124
 125       /**
 126        * End the JSON formatted response to the Settings app request.
 127        */
 128       void end_response(smart_ptr<JsonBuilder> const & builder);
 129
 130       /**
 131        * Send the JSON formatted response to the Settings app
 132        * request over the corresponding websocket.
 133        */
 134       bool send_payload(smart_ptr<JsonBuilder> const & builder);
 135
 136     private:
 137
 138       /**
 139        * Pointer to the websocket through which the response will be
 140        * sent to the Settings app.
 141        */
 142       struct libwebsocket * const wsi_;
 143
 144       /**
 145        * Settings type (e.g. "bluetooth", "wifi", etc).
 146        */
 147       std::string const type_;
 148
 149       /**
 150        * Transaction/request ID created by Settings app.
 151        */
 152       std::string const transaction_id_;
 153
 154     };
 155
 156   }
 157 }
 158
 159 #endif  /* IVI_SETTINGS_RESPONSE_CALLBACK_HPP */
 160
 161
 162 // Local Variables:
 163 // mode:c++
 164 // c-basic-offset:2
 165 // indent-tabs-mode: nil
 166 // End: