src/rpc/server.h

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