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
);
34 /** Wrapper for UniValue::VType, which includes typeAny:
35 * Used to denote don't care type. Only used by RPCTypeCheckObj */
37 UniValueType(UniValue::VType _type
) : typeAny(false), type(_type
) {}
38 UniValueType() : typeAny(true) {}
47 std::string strMethod
;
53 JSONRPCRequest() : id(NullUniValue
), params(NullUniValue
), fHelp(false) {}
54 void parse(const UniValue
& valRequest
);
57 /** Query whether RPC is running */
61 * Set the RPC warmup status. When this is done, all RPC calls will error out
62 * immediately with RPC_IN_WARMUP.
64 void SetRPCWarmupStatus(const std::string
& newStatus
);
65 /* Mark warmup as done. RPC calls will be processed from now on. */
66 void SetRPCWarmupFinished();
68 /* returns the current warmup state. */
69 bool RPCIsInWarmup(std::string
*outStatus
);
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.
75 void RPCTypeCheck(const UniValue
& params
,
76 const std::list
<UniValue::VType
>& typesExpected
, bool fAllowNull
=false);
79 * Type-check one argument; throws JSONRPCError if wrong type given.
81 void RPCTypeCheckArgument(const UniValue
& value
, UniValue::VType typeExpected
);
84 Check for expected keys/value types in an Object.
86 void RPCTypeCheckObj(const UniValue
& o
,
87 const std::map
<std::string
, UniValueType
>& typesExpected
,
88 bool fAllowNull
= false,
89 bool fStrict
= false);
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.
98 virtual ~RPCTimerBase() {}
102 * RPC timer "driver".
104 class RPCTimerInterface
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.
116 virtual RPCTimerBase
* NewTimer(std::function
<void(void)>& func
, int64_t millis
) = 0;
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
);
127 * Run func nSeconds from now.
128 * Overrides previous timer <name> (if any).
130 void RPCRunLater(const std::string
& name
, std::function
<void(void)> func
, int64_t nSeconds
);
132 typedef UniValue(*rpcfn_type
)(const JSONRPCRequest
& jsonRequest
);
137 std::string category
;
141 std::vector
<std::string
> argNames
;
145 * Bitcoin RPC command dispatcher.
150 std::map
<std::string
, const CRPCCommand
*> mapCommands
;
153 const CRPCCommand
* operator[](const std::string
& name
) const;
154 std::string
help(const std::string
& name
, const JSONRPCRequest
& helpreq
) const;
158 * @param request The JSONRPCRequest to execute
159 * @returns Result of the call.
160 * @throws an exception (UniValue) when an error happens.
162 UniValue
execute(const JSONRPCRequest
&request
) const;
165 * Returns a list of registered commands
166 * @returns List of registered commands.
168 std::vector
<std::string
> listCommands() const;
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).
176 bool appendCommand(const std::string
& name
, const CRPCCommand
* pcmd
);
179 extern CRPCTable tableRPC
;
182 * Utilities: convert hex-encoded Values
183 * (throws error if not hex).
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
);
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
);
198 std::string
JSONRPCExecBatch(const UniValue
& vReq
);
200 // Retrieves any serialization flags requested in command line argument
201 int RPCSerializationFlags();
203 #endif // BITCOIN_RPCSERVER_H