client.cpp File Reference

#include <common/args.h>
#include <rpc/client.h>
#include <tinyformat.h>
#include <cstdint>
#include <set>
#include <string>
#include <string_view>

Include dependency graph for client.cpp:

Go to the source code of this file.

Classes
class	CRPCConvertParam

Namespaces
namespace	rpc_convert

Enumerations
enum	ParamFormat { JSON , STRING , JSON_OR_STRING }
	Specify whether parameter should be parsed by bitcoin-cli as a JSON value, or passed unchanged as a string, or a combination of both. More...

Functions
static UniValue	Parse (std::string_view raw, ParamFormat format=ParamFormat::JSON)
	Parse string to UniValue or throw runtime_error if string contains invalid JSON. More...
const CRPCConvertParam *	rpc_convert::FromPosition (std::string_view method, size_t pos)
const CRPCConvertParam *	rpc_convert::FromName (std::string_view method, std::string_view name)
static UniValue	ParseParam (const CRPCConvertParam *param, std::string_view raw)
UniValue	RPCConvertValues (const std::string &strMethod, const std::vector< std::string > &strParams)
	Convert command lines arguments to params object when -named is disabled. More...
UniValue	RPCConvertNamedValues (const std::string &strMethod, const std::vector< std::string > &strParams)
	Convert command line arguments to params object when -named is enabled. More...

Variables
static const CRPCConvertParam	vRPCConvertParams []
	Specify a (method, idx, name, format) here if the argument is a non-string RPC argument and needs to be converted from JSON, or if it is a string argument passed to a method that accepts '=' characters in any string arguments. More...

Enumeration Type Documentation

ParamFormat

enum ParamFormat

Specify whether parameter should be parsed by bitcoin-cli as a JSON value, or passed unchanged as a string, or a combination of both.

Enumerator
JSON
STRING
JSON_OR_STRING

Definition at line 17 of file client.cpp.

Function Documentation

Parse()

static UniValue Parse ( std::string_view  raw, ParamFormat  format = ParamFormat::JSON  )

static

Parse string to UniValue or throw runtime_error if string contains invalid JSON.

Definition at line 393 of file client.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

ParseParam()

static UniValue ParseParam ( const CRPCConvertParam *  param, std::string_view  raw  )

static

Definition at line 424 of file client.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

RPCConvertNamedValues()

UniValue RPCConvertNamedValues	(	const std::string &	strMethod,
		const std::vector< std::string > &	strParams
	)

Convert command line arguments to params object when -named is enabled.

Convert named arguments to command-specific RPC representation.

The -named syntax accepts named arguments in NAME=VALUE format, as well as positional arguments without names. The syntax is inherently ambiguous if names are omitted and values contain '=', so a heuristic is used to disambiguate:

• Arguments that do not contain '=' are treated as positional parameters.
• Arguments that do contain '=' are assumed to be named parameters in NAME=VALUE format except for two special cases:
  1. The case where NAME is not a known parameter name, and the next positional parameter requires a JSON value, and the argument parses as JSON. E.g. ["list", "with", "="].
  2. The case where NAME is not a known parameter name and the next positional parameter requires a string value. E.g. "my=wallet".

For example, the command bitcoin-cli -named createwallet "my=wallet", the parser initially sees "my=wallet" and attempts to process it as a parameter named "my". When it finds that "my" is not a valid named parameter parameter for this method, it falls back to checking the rule for the next available positional parameter (index 0). Because it finds the rule that this parameter is a ParamFormat::STRING, it correctly treats the entire "my=wallet" as a single positional string, successfully creating a wallet with that literal name.

Definition at line 473 of file client.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

RPCConvertValues()

UniValue RPCConvertValues	(	const std::string &	strMethod,
		const std::vector< std::string > &	strParams
	)

Convert command lines arguments to params object when -named is disabled.

Convert positional arguments to command-specific RPC representation.

Definition at line 433 of file client.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

vRPCConvertParams

const CRPCConvertParam vRPCConvertParams[]

static

Specify a (method, idx, name, format) here if the argument is a non-string RPC argument and needs to be converted from JSON, or if it is a string argument passed to a method that accepts '=' characters in any string arguments.

JSON parameters need to be listed here to make bitcoin-cli parse command line arguments as JSON, instead of passing them as raw strings. JSON and JSON_OR_STRING formats both make bitcoin-cli attempt to parse the argument as JSON. But if parsing fails, the former triggers an error while the latter falls back to passing the argument as a raw string. This is useful for arguments like hash_or_height, allowing invocations such as bitcoin-cli getblockstats <hash> without needing to quote the hash string as JSON (‘’"<hash>"'`).

String parameters that may contain an '=' character (e.g. base64 strings, filenames, or labels) need to be listed here with format ParamFormat::STRING to make bitcoin-cli treat them as positional parameters when -named is used. This prevents bitcoin-cli from splitting strings like "my=wallet" into a named argument "my" and value "wallet" when the whole string is intended to be a single positional argument. And if one string parameter is listed for a method, other string parameters for that method need to be listed as well so bitcoin-cli does not make the opposite mistake and pass other arguments by position instead of name because it does not recognize their names. See RPCConvertNamedValues for more information on how named and positional arguments are distinguished with -named.

Note

Parameter indexes start from 0.

Definition at line 57 of file client.cpp.