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