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.
6 #ifndef BITCOIN_RPCSERVER_H
7 #define BITCOIN_RPCSERVER_H
10 #include "rpc/protocol.h"
20 static const unsigned int DEFAULT_RPC_SERIALIZE_VERSION
= 1;
26 void OnStarted(std::function
<void ()> slot
);
27 void OnStopped(std::function
<void ()> slot
);
28 void OnPreCommand(std::function
<void (const CRPCCommand
&)> slot
);
31 /** Wrapper for UniValue::VType, which includes typeAny:
32 * Used to denote don't care type. Only used by RPCTypeCheckObj */
34 UniValueType(UniValue::VType _type
) : typeAny(false), type(_type
) {}
35 UniValueType() : typeAny(true) {}
44 std::string strMethod
;
50 JSONRPCRequest() : id(NullUniValue
), params(NullUniValue
), fHelp(false) {}
51 void parse(const UniValue
& valRequest
);
54 /** Query whether RPC is running */
58 * Set the RPC warmup status. When this is done, all RPC calls will error out
59 * immediately with RPC_IN_WARMUP.
61 void SetRPCWarmupStatus(const std::string
& newStatus
);
62 /* Mark warmup as done. RPC calls will be processed from now on. */
63 void SetRPCWarmupFinished();
65 /* returns the current warmup state. */
66 bool RPCIsInWarmup(std::string
*outStatus
);
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.
72 void RPCTypeCheck(const UniValue
& params
,
73 const std::list
<UniValue::VType
>& typesExpected
, bool fAllowNull
=false);
76 * Type-check one argument; throws JSONRPCError if wrong type given.
78 void RPCTypeCheckArgument(const UniValue
& value
, UniValue::VType typeExpected
);
81 Check for expected keys/value types in an Object.
83 void RPCTypeCheckObj(const UniValue
& o
,
84 const std::map
<std::string
, UniValueType
>& typesExpected
,
85 bool fAllowNull
= false,
86 bool fStrict
= false);
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.
95 virtual ~RPCTimerBase() {}
101 class RPCTimerInterface
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.
113 virtual RPCTimerBase
* NewTimer(std::function
<void(void)>& func
, int64_t millis
) = 0;
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
);
124 * Run func nSeconds from now.
125 * Overrides previous timer <name> (if any).
127 void RPCRunLater(const std::string
& name
, std::function
<void(void)> func
, int64_t nSeconds
);
129 typedef UniValue(*rpcfn_type
)(const JSONRPCRequest
& jsonRequest
);
134 std::string category
;
138 std::vector
<std::string
> argNames
;
142 * Bitcoin RPC command dispatcher.
147 std::map
<std::string
, const CRPCCommand
*> mapCommands
;
150 const CRPCCommand
* operator[](const std::string
& name
) const;
151 std::string
help(const std::string
& name
, const JSONRPCRequest
& helpreq
) const;
155 * @param request The JSONRPCRequest to execute
156 * @returns Result of the call.
157 * @throws an exception (UniValue) when an error happens.
159 UniValue
execute(const JSONRPCRequest
&request
) const;
162 * Returns a list of registered commands
163 * @returns List of registered commands.
165 std::vector
<std::string
> listCommands() const;
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).
173 bool appendCommand(const std::string
& name
, const CRPCCommand
* pcmd
);
176 extern CRPCTable tableRPC
;
179 * Utilities: convert hex-encoded Values
180 * (throws error if not hex).
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
);
187 extern CAmount
AmountFromValue(const UniValue
& value
);
188 extern UniValue
ValueFromAmount(const CAmount
& amount
);
189 extern std::string
HelpExampleCli(const std::string
& methodname
, const std::string
& args
);
190 extern std::string
HelpExampleRpc(const std::string
& methodname
, const std::string
& args
);
195 std::string
JSONRPCExecBatch(const UniValue
& vReq
);
197 // Retrieves any serialization flags requested in command line argument
198 int RPCSerializationFlags();
200 #endif // BITCOIN_RPCSERVER_H