src/rpc/server.h

   1 // Copyright (c) 2010 Satoshi Nakamoto
   2 // Copyright (c) 2009-2016 The Bitcoin Core developers
   3 // Distributed under the MIT software license, see the accompanying
   4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
   5
   6 #ifndef BITCOIN_RPCSERVER_H
   7 #define BITCOIN_RPCSERVER_H
   8
   9 #include "amount.h"
  10 #include "rpc/protocol.h"
  11 #include "uint256.h"
  12
  13 #include <list>
  14 #include <map>
  15 #include <stdint.h>
  16 #include <string>
  17
  18 #include <univalue.h>
  19
  20 static const unsigned int DEFAULT_RPC_SERIALIZE_VERSION = 1;
  21
  22 class CRPCCommand;
  23
  24 namespace RPCServer
  25 {
  26     void OnStarted(std::function<void ()> slot);
  27     void OnStopped(std::function<void ()> slot);
  28     void OnPreCommand(std::function<void (const CRPCCommand&)> slot);
  29 }
  30
  31 /** Wrapper for UniValue::VType, which includes typeAny:
  32  * Used to denote don't care type. Only used by RPCTypeCheckObj */
  33 struct UniValueType {
  34     explicit UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
  35     UniValueType() : typeAny(true) {}
  36     bool typeAny;
  37     UniValue::VType type;
  38 };
  39
  40 class JSONRPCRequest
  41 {
  42 public:
  43     UniValue id;
  44     std::string strMethod;
  45     UniValue params;
  46     bool fHelp;
  47     std::string URI;
  48     std::string authUser;
  49
  50     JSONRPCRequest() : id(NullUniValue), params(NullUniValue), fHelp(false) {}
  51     void parse(const UniValue& valRequest);
  52 };
  53
  54 /** Query whether RPC is running */
  55 bool IsRPCRunning();
  56
  57 /**
  58  * Set the RPC warmup status.  When this is done, all RPC calls will error out
  59  * immediately with RPC_IN_WARMUP.
  60  */
  61 void SetRPCWarmupStatus(const std::string& newStatus);
  62 /* Mark warmup as done.  RPC calls will be processed from now on.  */
  63 void SetRPCWarmupFinished();
  64
  65 /* returns the current warmup state.  */
  66 bool RPCIsInWarmup(std::string *outStatus);
  67
  68 /**
  69  * Type-check arguments; throws JSONRPCError if wrong type given. Does not check that
  70  * the right number of arguments are passed, just that any passed are the correct type.
  71  */
  72 void RPCTypeCheck(const UniValue& params,
  73                   const std::list<UniValue::VType>& typesExpected, bool fAllowNull=false);
  74
  75 /**
  76  * Type-check one argument; throws JSONRPCError if wrong type given.
  77  */
  78 void RPCTypeCheckArgument(const UniValue& value, UniValue::VType typeExpected);
  79
  80 /*
  81   Check for expected keys/value types in an Object.
  82 */
  83 void RPCTypeCheckObj(const UniValue& o,
  84     const std::map<std::string, UniValueType>& typesExpected,
  85     bool fAllowNull = false,
  86     bool fStrict = false);
  87
  88 /** Opaque base class for timers returned by NewTimerFunc.
  89  * This provides no methods at the moment, but makes sure that delete
  90  * cleans up the whole state.
  91  */
  92 class RPCTimerBase
  93 {
  94 public:
  95     virtual ~RPCTimerBase() {}
  96 };
  97
  98 /**
  99  * RPC timer "driver".
 100  */
 101 class RPCTimerInterface
 102 {
 103 public:
 104     virtual ~RPCTimerInterface() {}
 105     /** Implementation name */
 106     virtual const char *Name() = 0;
 107     /** Factory function for timers.
 108      * RPC will call the function to create a timer that will call func in *millis* milliseconds.
 109      * @note As the RPC mechanism is backend-neutral, it can use different implementations of timers.
 110      * This is needed to cope with the case in which there is no HTTP server, but
 111      * only GUI RPC console, and to break the dependency of pcserver on httprpc.
 112      */
 113     virtual RPCTimerBase* NewTimer(std::function<void(void)>& func, int64_t millis) = 0;
 114 };
 115
 116 /** Set the factory function for timers */
 117 void RPCSetTimerInterface(RPCTimerInterface *iface);
 118 /** Set the factory function for timer, but only, if unset */
 119 void RPCSetTimerInterfaceIfUnset(RPCTimerInterface *iface);
 120 /** Unset factory function for timers */
 121 void RPCUnsetTimerInterface(RPCTimerInterface *iface);
 122
 123 /**
 124  * Run func nSeconds from now.
 125  * Overrides previous timer <name> (if any).
 126  */
 127 void RPCRunLater(const std::string& name, std::function<void(void)> func, int64_t nSeconds);
 128
 129 typedef UniValue(*rpcfn_type)(const JSONRPCRequest& jsonRequest);
 130
 131 class CRPCCommand
 132 {
 133 public:
 134     std::string category;
 135     std::string name;
 136     rpcfn_type actor;
 137     bool okSafeMode;
 138     std::vector<std::string> argNames;
 139 };
 140
 141 /**
 142  * Bitcoin RPC command dispatcher.
 143  */
 144 class CRPCTable
 145 {
 146 private:
 147     std::map<std::string, const CRPCCommand*> mapCommands;
 148 public:
 149     CRPCTable();
 150     const CRPCCommand* operator[](const std::string& name) const;
 151     std::string help(const std::string& name, const JSONRPCRequest& helpreq) const;
 152
 153     /**
 154      * Execute a method.
 155      * @param request The JSONRPCRequest to execute
 156      * @returns Result of the call.
 157      * @throws an exception (UniValue) when an error happens.
 158      */
 159     UniValue execute(const JSONRPCRequest &request) const;
 160
 161     /**
 162     * Returns a list of registered commands
 163     * @returns List of registered commands.
 164     */
 165     std::vector<std::string> listCommands() const;
 166
 167
 168     /**
 169      * Appends a CRPCCommand to the dispatch table.
 170      * Returns false if RPC server is already running (dump concurrency protection).
 171      * Commands cannot be overwritten (returns false).
 172      */
 173     bool appendCommand(const std::string& name, const CRPCCommand* pcmd);
 174 };
 175
 176 extern CRPCTable tableRPC;
 177
 178 /**
 179  * Utilities: convert hex-encoded Values
 180  * (throws error if not hex).
 181  */
 182 extern uint256 ParseHashV(const UniValue& v, std::string strName);
 183 extern uint256 ParseHashO(const UniValue& o, std::string strKey);
 184 extern std::vector<unsigned char> ParseHexV(const UniValue& v, std::string strName);
 185 extern std::vector<unsigned char> ParseHexO(const UniValue& o, std::string strKey);
 186
 187 extern CAmount AmountFromValue(const UniValue& value);
 188 extern std::string HelpExampleCli(const std::string& methodname, const std::string& args);
 189 extern std::string HelpExampleRpc(const std::string& methodname, const std::string& args);
 190
 191 bool StartRPC();
 192 void InterruptRPC();
 193 void StopRPC();
 194 std::string JSONRPCExecBatch(const UniValue& vReq);
 195
 196 // Retrieves any serialization flags requested in command line argument
 197 int RPCSerializationFlags();
 198
 199 #endif // BITCOIN_RPCSERVER_H