code.vuplus.com Git - vuplus_xbmc/blob - xbmc/interfaces/json-rpc/JSONServiceDescription.h

   1 #pragma once
   2 /*
   3  *      Copyright (C) 2005-2010 Team XBMC
   4  *      http://www.xbmc.org
   5  *
   6  *  This Program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2, or (at your option)
   9  *  any later version.
  10  *
  11  *  This Program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with XBMC; see the file COPYING.  If not, write to
  18  *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  19  *  http://www.gnu.org/copyleft/gpl.html
  20  *
  21  */
  22
  23 #include <string>
  24 #include <vector>
  25 #include <limits>
  26 #include "JSONUtils.h"
  27
  28 namespace JSONRPC
  29 {
  30   /*!
  31    \ingroup jsonrpc
  32    \brief Structure for a parameter of a
  33    json rpc method.
  34
  35    Represents a parameter of a defined
  36    json rpc method and is used to verify
  37    and extract the value of the parameter
  38    in a method call.
  39    */
  40   typedef struct JSONSchemaTypeDefinition
  41   {
  42     JSONSchemaTypeDefinition()
  43       : type(AnyValue), minimum(std::numeric_limits<double>::min()), maximum(std::numeric_limits<double>::max()),
  44         exclusiveMinimum(false), exclusiveMaximum(false), divisibleBy(0),
  45         minLength(-1), maxLength(-1),
  46         minItems(0), maxItems(0), uniqueItems(false),
  47         hasAdditionalProperties(false), additionalProperties(NULL)
  48     { }
  49
  50     /*!
  51      \brief Name of the parameter (for
  52      by-name calls)
  53      */
  54     std::string name;
  55
  56     /*!
  57      \brief Id of the type (for
  58      referenced types)
  59      Renamed from "id" because of possible
  60      issues with Objective-C.
  61      */
  62     std::string ID;
  63
  64     /*!
  65      \brief Array of reference types
  66      which are extended by this type.
  67      */
  68     std::vector<JSONSchemaTypeDefinition> extends;
  69
  70     /*!
  71      \brief Description of the parameter
  72      */
  73     std::string description;
  74
  75     /*!
  76      \brief JSON schema type of the parameter's value
  77      */
  78     JSONSchemaType type;
  79
  80     /*!
  81      \brief JSON schema type definitions in case
  82      of a union type
  83      */
  84     std::vector<JSONSchemaTypeDefinition> unionTypes;
  85
  86     /*!
  87      \brief Whether or not the parameter is
  88      optional
  89      */
  90     bool optional;
  91
  92     /*!
  93      \brief Default value of the parameter
  94      (only needed when it is optional)
  95      */
  96     CVariant defaultValue;
  97
  98     /*!
  99      \brief Minimum value for Integer
 100      or Number types
 101      */
 102     double minimum;
 103
 104     /*!
 105      \brief Maximum value for Integer or Number types
 106      */
 107     double maximum;
 108
 109     /*!
 110      \brief Whether to exclude the defined Minimum
 111      value from the valid range or not
 112      */
 113     bool exclusiveMinimum;
 114
 115     /*!
 116      \brief  Whether to exclude the defined Maximum
 117      value from the valid range or not
 118      */
 119     bool exclusiveMaximum;
 120
 121     /*!
 122      \brief Integer by which the value (of type
 123      Integer) must be divisible without rest
 124      */
 125     unsigned int divisibleBy;
 126
 127     /*!
 128      \brief Minimum length for String types
 129      */
 130     int minLength;
 131
 132     /*!
 133      \brief Maximum length for String types
 134      */
 135     int maxLength;
 136
 137     /*!
 138      \brief (Optional) List of allowed values
 139      for the type
 140      */
 141     std::vector<CVariant> enums;
 142
 143     /*!
 144      \brief List of possible values in an array
 145      */
 146     std::vector<JSONSchemaTypeDefinition> items;
 147
 148     /*!
 149      \brief Minimum amount of items in the array
 150      */
 151     unsigned int minItems;
 152
 153     /*!
 154      \brief Maximum amount of items in the array
 155      */
 156     unsigned int maxItems;
 157
 158     /*!
 159      \brief Whether every value in the array
 160      must be unique or not
 161      */
 162     bool uniqueItems;
 163
 164     /*!
 165      \brief List of json schema definitions for
 166      additional items in an array with tuple
 167      typing (defined schemas in "items")
 168      */
 169     std::vector<JSONSchemaTypeDefinition> additionalItems;
 170
 171     /*!
 172      \brief Maps a properties name to its
 173      json schema type definition
 174      */
 175     class CJsonSchemaPropertiesMap
 176     {
 177     public:
 178       CJsonSchemaPropertiesMap();
 179
 180       void add(JSONSchemaTypeDefinition &property);
 181
 182       typedef std::map<std::string, JSONSchemaTypeDefinition>::const_iterator JSONSchemaPropertiesIterator;
 183       JSONSchemaPropertiesIterator begin() const;
 184       JSONSchemaPropertiesIterator find(const std::string& key) const;
 185       JSONSchemaPropertiesIterator end() const;
 186       unsigned int size() const;
 187     private:
 188       std::map<std::string, JSONSchemaTypeDefinition> m_propertiesmap;
 189     };
 190
 191     /*!
 192      \brief List of properties of the parameter (only needed when the
 193      parameter is an object)
 194      */
 195     CJsonSchemaPropertiesMap properties;
 196
 197     /*!
 198      \brief Whether the type can have additional properties
 199      or not
 200      */
 201     bool hasAdditionalProperties;
 202
 203     /*!
 204      \brief Type definition for additional properties
 205      */
 206     JSONSchemaTypeDefinition* additionalProperties;
 207   } JSONSchemaTypeDefinition;
 208
 209   /*!
 210    \ingroup jsonrpc
 211    \brief Structure for a published json
 212    rpc method.
 213
 214    Represents a published json rpc method
 215    and is used to verify an incoming json
 216    rpc request against a defined method.
 217    */
 218   typedef struct
 219   {
 220     /*!
 221      \brief Name of the represented method
 222      */
 223     std::string name;
 224     /*!
 225      \brief Pointer tot he implementation
 226      of the represented method
 227      */
 228     MethodCall method;
 229     /*!
 230      \brief Definition of the type of
 231      request/response
 232      */
 233     TransportLayerCapability transportneed;
 234     /*!
 235      \brief Definition of the permissions needed
 236      to execute the method
 237      */
 238     OperationPermission permission;
 239     /*!
 240      \brief Description of the method
 241      */
 242     std::string description;
 243     /*!
 244      \brief List of accepted parameters
 245      */
 246     std::vector<JSONSchemaTypeDefinition> parameters;
 247     /*!
 248      \brief Definition of the return value
 249      */
 250     JSONSchemaTypeDefinition returns;
 251   } JsonRpcMethod;
 252
 253   /*!
 254    \ingroup jsonrpc
 255    \brief Structure mapping a json rpc method
 256    definition to an actual method implementation.
 257    */
 258   typedef struct
 259   {
 260     /*!
 261      \brief Name of the json rpc method.
 262      */
 263     std::string name;
 264     /*!
 265      \brief Pointer to the actual
 266      implementation of the json rpc
 267      method.
 268      */
 269     MethodCall method;
 270   } JsonRpcMethodMap;
 271
 272   /*!
 273    \ingroup jsonrpc
 274    \brief Helper class for json schema service descriptor based
 275    service descriptions for the json rpc API
 276
 277    Provides static functions to parse a complete json schema
 278    service descriptor of a published service containing json rpc
 279    methods, print the json schema service descriptor representation
 280    into a string (mainly for output purposes) and evaluate and verify
 281    parameters provided in a call to one of the publish json rpc methods
 282    against a parameter definition parsed from a json schema service
 283    descriptor.
 284    */
 285   class CJSONServiceDescription : public CJSONUtils
 286   {
 287   public:
 288     /*!
 289      \brief Parses the given json schema description and evaluates
 290      and stores the defined type
 291      \param jsonType json schema description to parse
 292      \return True if the json schema description has been parsed sucessfully otherwise false
 293      */
 294     static bool AddType(std::string jsonType);
 295
 296     /*!
 297      \brief Parses the given json schema description and evaluates
 298      and stores the defined method
 299      \param jsonMethod json schema description to parse
 300      \param method pointer to the implementation
 301      \return True if the json schema description has been parsed sucessfully otherwise false
 302      */
 303     static bool AddMethod(std::string jsonMethod, MethodCall method);
 304
 305     /*!
 306      \brief Parses the given json schema description and evaluates
 307      and stores the defined builtin method
 308      \param jsonMethod json schema description to parse
 309      \return True if the json schema description has been parsed sucessfully otherwise false
 310      */
 311     static bool AddBuiltinMethod(std::string jsonMethod);
 312
 313     /*!
 314      \brief Parses the given json schema description and evaluates
 315      and stores the defined notification
 316      \param jsonNotification json schema description to parse
 317      \return True if the json schema description has been parsed sucessfully otherwise false
 318      */
 319     static bool AddNotification(std::string jsonNotification);
 320
 321     /*!
 322      \brief Gets the version of the json
 323      schema description
 324      \return Version of the json schema description
 325      */
 326     static int GetVersion();
 327
 328     /*!
 329      \brief Prints the json schema description into the given result object
 330      \param result Object into which the json schema description is printed
 331      \param transport Transport layer capabilities
 332      \param client Client requesting a print
 333      \param printDescriptions Whether to print descriptions or not
 334      \param printMetadata Whether to print XBMC specific data or not
 335      \param filterByTransport Whether to filter by transport or not
 336      */
 337     static JSON_STATUS Print(CVariant &result, ITransportLayer *transport, IClient *client, bool printDescriptions = true, bool printMetadata = false, bool filterByTransport = true, std::string filterByName = "", std::string filterByType = "", bool printReferences = true);
 338
 339     /*!
 340      \brief Checks the given parameters from the request against the
 341      json schema description for the given method
 342      \param method Called method
 343      \param requestParameters Parameters from the request
 344      \param client Client who sent the request
 345      \param notification Whether the request was sent as a notification or not
 346      \param methodCall Object which will contain the actual C/C++ method to be called
 347      \param outputParameters Cleaned up parameter list
 348      \return OK if the validation of the request succeeded otherwise an appropriate error code
 349
 350      Checks if the given method is a valid json rpc method, if the client has the permission
 351      to call this method, if the method can be called as a notification or not, assigns the
 352      actual C/C++ implementation of the method to the "methodCall" parameter and checks the
 353      given parameters from the request against the json schema description for the given method.
 354      */
 355     static JSON_STATUS CheckCall(const char* const method, const CVariant &requestParameters, ITransportLayer *transport, IClient *client, bool notification, MethodCall &methodCall, CVariant &outputParameters);
 356
 357   private:
 358     static bool prepareDescription(std::string &description, CVariant &descriptionObject, std::string &name);
 359     static bool addMethod(std::string &jsonMethod, MethodCall method);
 360     static void printType(const JSONSchemaTypeDefinition &type, bool isParameter, bool isGlobal, bool printDefault, bool printDescriptions, CVariant &output);
 361     static JSON_STATUS checkParameter(const CVariant &requestParameters, const JSONSchemaTypeDefinition &type, unsigned int position, CVariant &outputParameters, unsigned int &handled, CVariant &errorData);
 362     static JSON_STATUS checkType(const CVariant &value, const JSONSchemaTypeDefinition &type, CVariant &outputValue, CVariant &errorData);
 363     static void parseHeader(const CVariant &descriptionObject);
 364     static bool parseMethod(const CVariant &value, JsonRpcMethod &method);
 365     static bool parseParameter(CVariant &value, JSONSchemaTypeDefinition &parameter);
 366     static bool parseTypeDefinition(const CVariant &value, JSONSchemaTypeDefinition &type, bool isParameter);
 367     static void parseReturn(const CVariant &value, JSONSchemaTypeDefinition &returns);
 368     static JSONSchemaType parseJSONSchemaType(const CVariant &value, std::vector<JSONSchemaTypeDefinition>& typeDefinitions);
 369     static void addReferenceTypeDefinition(JSONSchemaTypeDefinition &typeDefinition);
 370
 371     static void getReferencedTypes(const JSONSchemaTypeDefinition &type, std::vector<std::string> &referencedTypes);
 372
 373     class CJsonRpcMethodMap
 374     {
 375     public:
 376       CJsonRpcMethodMap();
 377
 378       void add(const JsonRpcMethod &method);
 379
 380       typedef std::map<std::string, JsonRpcMethod>::const_iterator JsonRpcMethodIterator;
 381       JsonRpcMethodIterator begin() const;
 382       JsonRpcMethodIterator find(const std::string& key) const;
 383       JsonRpcMethodIterator end() const;
 384     private:
 385       std::map<std::string, JsonRpcMethod> m_actionmap;
 386     };
 387
 388     static CJsonRpcMethodMap m_actionMap;
 389     static std::map<std::string, JSONSchemaTypeDefinition> m_types;
 390     static std::map<std::string, CVariant> m_notifications;
 391     static JsonRpcMethodMap m_methodMaps[];
 392   };
 393 }