src/rpc/server.h

   1 // Copyright (c) 2010 Satoshi Nakamoto
   2 // Copyright (c) 2009-2017 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 }
  29
  30 /** Wrapper for UniValue::VType, which includes typeAny:
  31  * Used to denote don't care type. Only used by RPCTypeCheckObj */
  32 struct UniValueType {
  33     explicit UniValueType(UniValue::VType _type) : typeAny(false), type(_type) {}
  34     UniValueType() : typeAny(true) {}
  35     bool typeAny;
  36     UniValue::VType type;
  37 };
  38
  39 class JSONRPCRequest
  40 {
  41 public:
  42     UniValue id;
  43     std::string strMethod;
  44     UniValue params;
  45     bool fHelp;
  46     std::string URI;
  47     std::string authUser;
  48
  49     JSONRPCRequest() : id(NullUniValue), params(NullUniValue), fHelp(false) {}
  50     void parse(const UniValue& valRequest);
  51 };
  52
  53 /** Query whether RPC is running */
  54 bool IsRPCRunning();
  55
  56 /**
  57  * Set the RPC warmup status.  When this is done, all RPC calls will error out
  58  * immediately with RPC_IN_WARMUP.
  59  */
  60 void SetRPCWarmupStatus(const std::string& newStatus);
  61 /* Mark warmup as done.  RPC calls will be processed from now on.  */
  62 void SetRPCWarmupFinished();
  63
  64 /* returns the current warmup state.  */
  65 bool RPCIsInWarmup(std::string *outStatus);
  66
  67 /**
  68  * Type-check arguments; throws JSONRPCError if wrong type given. Does not check that
  69  * the right number of arguments are passed, just that any passed are the correct type.
  70  */
  71 void RPCTypeCheck(const UniValue& params,
  72                   const std::list<UniValue::VType>& typesExpected, bool fAllowNull=false);
  73
  74 /**
  75  * Type-check one argument; throws JSONRPCError if wrong type given.
  76  */
  77 void RPCTypeCheckArgument(const UniValue& value, UniValue::VType typeExpected);
  78
  79 /*
  80   Check for expected keys/value types in an Object.
  81 */
  82 void RPCTypeCheckObj(const UniValue& o,
  83     const std::map<std::string, UniValueType>& typesExpected,
  84     bool fAllowNull = false,
  85     bool fStrict = false);
  86
  87 /** Opaque base class for timers returned by NewTimerFunc.
  88  * This provides no methods at the moment, but makes sure that delete
  89  * cleans up the whole state.
  90  */
  91 class RPCTimerBase
  92 {
  93 public:
  94     virtual ~RPCTimerBase() {}
  95 };
  96
  97 /**
  98  * RPC timer "driver".
  99  */
 100 class RPCTimerInterface
 101 {
 102 public:
 103     virtual ~RPCTimerInterface() {}
 104     /** Implementation name */
 105     virtual const char *Name() = 0;
 106     /** Factory function for timers.
 107      * RPC will call the function to create a timer that will call func in *millis* milliseconds.
 108      * @note As the RPC mechanism is backend-neutral, it can use different implementations of timers.
 109      * This is needed to cope with the case in which there is no HTTP server, but
 110      * only GUI RPC console, and to break the dependency of pcserver on httprpc.
 111      */
 112     virtual RPCTimerBase* NewTimer(std::function<void(void)>& func, int64_t millis) = 0;
 113 };
 114
 115 /** Set the factory function for timers */
 116 void RPCSetTimerInterface(RPCTimerInterface *iface);
 117 /** Set the factory function for timer, but only, if unset */
 118 void RPCSetTimerInterfaceIfUnset(RPCTimerInterface *iface);
 119 /** Unset factory function for timers */
 120 void RPCUnsetTimerInterface(RPCTimerInterface *iface);
 121
 122 /**
 123  * Run func nSeconds from now.
 124  * Overrides previous timer <name> (if any).
 125  */
 126 void RPCRunLater(const std::string& name, std::function<void(void)> func, int64_t nSeconds);
 127
 128 typedef UniValue(*rpcfn_type)(const JSONRPCRequest& jsonRequest);
 129
 130 class CRPCCommand
 131 {
 132 public:
 133     std::string category;
 134     std::string name;
 135     rpcfn_type actor;
 136     std::vector<std::string> argNames;
 137 };
 138
 139 /**
 140  * Bitcoin RPC command dispatcher.
 141  */
 142 class CRPCTable
 143 {
 144 private:
 145     std::map<std::string, const CRPCCommand*> mapCommands;
 146 public:
 147     CRPCTable();
 148     const CRPCCommand* operator[](const std::string& name) const;
 149     std::string help(const std::string& name, const JSONRPCRequest& helpreq) const;
 150
 151     /**
 152      * Execute a method.
 153      * @param request The JSONRPCRequest to execute
 154      * @returns Result of the call.
 155      * @throws an exception (UniValue) when an error happens.
 156      */
 157     UniValue execute(const JSONRPCRequest &request) const;
 158
 159     /**
 160     * Returns a list of registered commands
 161     * @returns List of registered commands.
 162     */
 163     std::vector<std::string> listCommands() const;
 164
 165
 166     /**
 167      * Appends a CRPCCommand to the dispatch table.
 168      * Returns false if RPC server is already running (dump concurrency protection).
 169      * Commands cannot be overwritten (returns false).
 170      */
 171     bool appendCommand(const std::string& name, const CRPCCommand* pcmd);
 172 };
 173
 174 bool IsDeprecatedRPCEnabled(const std::string& method);
 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 JSONRPCRequest& jreq, const UniValue& vReq);
 195
 196 // Retrieves any serialization flags requested in command line argument
 197 int RPCSerializationFlags();
 198
 199 #endif // BITCOIN_RPCSERVER_H