Deep Learning SDK for Geospatial Data
 1.0.0+
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Groups Pages
Network

Detailed Description

Contains network functionality specifically handling JSON-RPC communication.

Handle the processing of a JSON-RPC request-response with Simple-Web-Server http.

Handle the processing of a JSON-RPC request-response.

Create a hook for use with Simple-Web-Server.

Returns
A function pointer which accepts a request and generates a response

Assuming that MilNetServer is a concrete implementation for this class, a simple JSON-RPC service can be started with:

HttpServer server(8080, 4);
MilNetServer rpcServer;
server.resource["^/string$"]["GET"] = rpcServer.makeHttpHook();
server.start();
Parameters
[in]rpcRequestThe request to process
[out]rpcResponseThe response to return if the result of this function is true
Returns
True if the response should be sent to the server
Parameters
[in]responseThe http request to process
[out]requestThe http response to return

This method may be directly passed to a Simple-Web-Server HttpServer to manage JSON-RPC requests

Namespaces

 dg::deepcore::network
 Contains networking functionality.
 

Classes

struct  dg::deepcore::network::ApacheTomcatError
 Represents an HTML Apache Tomcat error report. More...
 
struct  dg::deepcore::network::DownloadRequest
 Represents an asynchronous download request. More...
 
class  dg::deepcore::network::HttpDownloader
 Downloads from HTTP/HTTPS endpoints. More...
 
class  dg::deepcore::network::HttpError
 Represents an HTTP error response. More...
 
class  dg::deepcore::network::HttpCleanup
 Safely manages the global curl initialization and cleanup. Should be used instead of curlpp::Cleaner or curl_global_init. More...
 
class  dg::deepcore::network::JsonRpc
 An abstract class for JSON-RPC communication. More...
 
class  dg::deepcore::network::JsonRpcError
 JSON-RPC error codes, messages and data. More...
 
class  dg::deepcore::network::JsonRpcRequest
 JSON-RPC Request container, parsing, and marshalling. More...
 
class  dg::deepcore::network::JsonRpcResponse
 JSON-RPC Response container, parsing, and marshalling. More...
 
class  dg::deepcore::network::JsonRpcServer
 A virtual class to handle JSON-RPC interaction. More...
 

Macros

#define DG_HTTP_ERROR_THROW(url, code, response)   throw dg::deepcore::network::HttpError(__FILENAME__, __LINE__, __FUNCTION__, url, code, response)
 Throws an HttpError for the current position in code. More...
 
#define DG_JSONRPC_ERROR_INIT(errorType, format,...)   dg::deepcore::network::JsonRpcError::fromFormat(__FILENAME__, __LINE__, __FUNCTION__, errorType, format, ##__VA_ARGS__)
 Initializes an Error for the current position in code, allows for sprintf-style message formatting. More...
 
#define DG_JSONRPC_ERROR_THROW(errorType, message,...)   throw DG_JSONRPC_ERROR_INIT(errorType, message, ##__VA_ARGS__)
 Throws an Error for the current position in code, allows for sprintf-style message formatting. More...
 
#define DG_JSONRPC_CHECK(condition, errorType, message,...)   if(!(condition)) { DG_JSONRPC_ERROR_THROW(errorType, message, ##__VA_ARGS__); }
 Checks the condition and throws an Error if the condition is false. More...
 

Typedefs

using dg::deepcore::network::DownloadCallback = std::function< bool(std::istream &stream)>
 
using dg::deepcore::network::DownloadRequests = std::vector< DownloadRequest >
 An std::vector of DownloadRequest objects. More...
 

Functions

virtual Json::Value dg::deepcore::network::JsonObject::toJson () const =0
 Marshal this object to a JSON container. More...
 
virtual void dg::deepcore::network::JsonObject::fromJson (const Json::Value &root)=0
 Unmarshal this object to a JSON container. More...
 
void dg::deepcore::network::JsonObject::fromJsonString (const std::string &root)
 Unmarshal this object from a JSON string. More...
 
std::string dg::deepcore::network::buildUrl (const string &baseUrl, const map< string, string > &args)
 Combines a base URL and query string. More...
 
std::string dg::deepcore::network::splitUrlQuery (const string &url, map< string, string > &args)
 Split the URL into base url and query arguments. More...
 
std::string dg::deepcore::network::urlEncode (const string &str)
 Encodes a string to be used as a URL query component. Equivalent to the JavaScript encodeURIComponent. More...
 
std::string dg::deepcore::network::urlDecode (const string &str)
 Decodes a string previously encoded with urlEncode, or equivalent. Equivalent to the JavaScript decodeURIComponent. More...
 
static ApacheTomcatError dg::deepcore::network::ApacheTomcatError::fromHtml (const std::string &html)
 Parses an HTML Apache Tomcat error report from a string. More...
 
static std::shared_ptr
< HttpCleanup > 
dg::deepcore::network::HttpCleanup::get ()
 Initialize curl for the lifetime of the returned shared pointer. More...
 
 dg::deepcore::network::HttpCleanup::~HttpCleanup ()
 The destructor. More...
 
 dg::deepcore::network::HttpError::HttpError ()
 The default constructor. More...
 
 dg::deepcore::network::HttpError::HttpError (const char *file, const unsigned int line, const char *function, const std::string &url, int code, const std::vector< uint8_t > &response)
 Constructs an HttpError. More...
 
 dg::deepcore::network::HttpError::HttpError (const char *file, const unsigned int line, const char *function, const std::string &url, int code, std::vector< uint8_t > &&response)
 Constructs an HttpError. More...
 
 dg::deepcore::network::HttpError::HttpError (const char *file, const unsigned int line, const char *function, const std::string &url, int code, std::istream &response)
 Constructs an HttpError. More...
 
const std::string & dg::deepcore::network::HttpError::url () const noexcept
 Gets the request URL. More...
 
int dg::deepcore::network::HttpError::code () const noexcept
 Gets the HTTP result code. More...
 
const std::string & dg::deepcore::network::HttpError::status () const noexcept
 Gets the description of the HTTP status code. More...
 
const std::vector< uint8_t > & dg::deepcore::network::HttpError::response () const noexcept
 Gets the response body. More...
 
std::string dg::deepcore::network::HttpError::responseAsString () const noexcept
 Gets the response body as an std::string. More...
 
const std::string & dg::deepcore::network::JsonRpc::version () const noexcept
 Get a string specifying the version of the JSON-RPC protocol. More...
 
void dg::deepcore::network::JsonRpc::setVersion (const std::string &version) noexcept
 Set a string specifying the version of the JSON-RPC protocol. More...
 
const Json::Value & dg::deepcore::network::JsonRpc::id () const noexcept
 Get an identifier established by the Client to disambiguate responses. More...
 
void dg::deepcore::network::JsonRpc::setId (const Json::Value &id) noexcept
 Set an identifier established by the Client to disambiguate responses. More...
 
void dg::deepcore::network::JsonRpc::clearId () noexcept
 Clear the id if it had been previously set. More...
 
const bool dg::deepcore::network::JsonRpc::hasId () const noexcept
 Determine if the id in this JSON-RPC packet has been set. More...
 
 dg::deepcore::network::JsonRpcError::JsonRpcError ()
 The default constructor. More...
 
 dg::deepcore::network::JsonRpcError::JsonRpcError (const std::string &file, const unsigned int line, const std::string &function, const JsonRpcErrorType type, const std::string &message)
 Constructs an Error. More...
 
 dg::deepcore::network::JsonRpcError::JsonRpcError (const std::string &file, const unsigned int line, const std::string &function, const int code, const std::string &shortMessage, const std::string &message)
 Constructs an Error. More...
 
 dg::deepcore::network::JsonRpcError::JsonRpcError (const Error &error, const JsonRpcErrorType type)
 Constructs a JsonRpcError based on an error. More...
 
static JsonRpcError dg::deepcore::network::JsonRpcError::fromData (const int code, const std::string &message, const Json::Value &data)
 Constructs a JsonRpcError without thrown metadata. More...
 
static JsonRpcError dg::deepcore::network::JsonRpcError::fromFormat (const char *file, const unsigned int line, const char *function, const JsonRpcErrorType type, const char *format,...) noexcept
 Creates an error with a message that can be formatted using sprintf-style format. More...
 
int dg::deepcore::network::JsonRpcError::code () const
 A Number that indicates the error type that occurred. More...
 
std::string dg::deepcore::network::JsonRpcError::shortMessage () const
 Get a string providing a short description of the error. More...
 
Json::Value dg::deepcore::network::JsonRpcError::data () const
 Get additional information about the error. More...
 
const std::string & dg::deepcore::network::JsonRpcRequest::method () const noexcept
 Get the name of the method to be invoked. More...
 
void dg::deepcore::network::JsonRpcRequest::setMethod (const std::string &method) noexcept
 Set the name of the method to be invoked. More...
 
const Json::Value & dg::deepcore::network::JsonRpcRequest::params () const noexcept
 Get a marshalled set of parameters. More...
 
void dg::deepcore::network::JsonRpcRequest::setParams (const Json::Value &params) noexcept
 Set a marshalled set of parameters. More...
 
bool dg::deepcore::network::JsonRpcResponse::hasError () const noexcept
 Does this response contain an error object? More...
 
const JsonRpcError & dg::deepcore::network::JsonRpcResponse::error () const noexcept
 If this response contains an error, get it. More...
 
void dg::deepcore::network::JsonRpcResponse::setError (const JsonRpcError &error) noexcept
 If this response contains an error, get it. More...
 
bool dg::deepcore::network::JsonRpcResponse::hasResult () const noexcept
 Does this response contain an result object? More...
 
const Json::Value & dg::deepcore::network::JsonRpcResponse::result () const noexcept
 If this response contains an result, get it. More...
 
void dg::deepcore::network::JsonRpcResponse::setResult (const Json::Value &result) noexcept
 Set a result object for this response. More...
 

Macro Definition Documentation

#define DG_HTTP_ERROR_THROW (   url,
  code,
  response 
)    throw dg::deepcore::network::HttpError(__FILENAME__, __LINE__, __FUNCTION__, url, code, response)

Throws an HttpError for the current position in code.

Parameters
[in]urlThe request URL.
[in]codeThe HTTP result code.
[in]responseThe response body.
#define DG_JSONRPC_CHECK (   condition,
  errorType,
  message,
  ... 
)    if(!(condition)) { DG_JSONRPC_ERROR_THROW(errorType, message, ##__VA_ARGS__); }

Checks the condition and throws an Error if the condition is false.

Parameters
[in]conditionThe condition to check.
[in]errorTypeThe type of error that will be checked
[in]messageThe sprintf-style format for the error message if condition is false.
#define DG_JSONRPC_ERROR_INIT (   errorType,
  format,
  ... 
)    dg::deepcore::network::JsonRpcError::fromFormat(__FILENAME__, __LINE__, __FUNCTION__, errorType, format, ##__VA_ARGS__)

Initializes an Error for the current position in code, allows for sprintf-style message formatting.

Parameters
[in]errorTypeThe type of error that will be initialized
[in]formatThe sprintf-style format for the error message.
[in]...Arguments for format specification.
Returns
A new instance of the Error class initialized with the message and the current file, line, and function.
#define DG_JSONRPC_ERROR_THROW (   errorType,
  message,
  ... 
)    throw DG_JSONRPC_ERROR_INIT(errorType, message, ##__VA_ARGS__)

Throws an Error for the current position in code, allows for sprintf-style message formatting.

Parameters
[in]errorTypeThe type of error that will be thrown
[in]messageThe message that the error will throw
[in]...Arguments for format specification.

Typedef Documentation

Parameters
[in,out]streamAn input stream containing the downloaded data.

Function Documentation

dg::deepcore::network::HttpError::HttpError ( )

The default constructor.

dg::deepcore::network::HttpError::HttpError ( const char *  file,
const unsigned int  line,
const char *  function,
const std::string &  url,
int  code,
const std::vector< uint8_t > &  response 
)

Constructs an HttpError.

Parameters
[in]fileName of source file in which the error occurred.
[in]lineSource line number for the error.
[in]functionFunction name in which the error occured.
[in]urlThe request URL.
[in]codeThe HTTP result code.
[in]responseThe response body.
dg::deepcore::network::HttpError::HttpError ( const char *  file,
const unsigned int  line,
const char *  function,
const std::string &  url,
int  code,
std::vector< uint8_t > &&  response 
)

Constructs an HttpError.

Parameters
[in]fileName of source file in which the error occurred.
[in]lineSource line number for the error.
[in]functionFunction name in which the error occured.
[in]urlThe request URL.
[in]codeThe HTTP result code.
[in,out]responseThe response body.
dg::deepcore::network::HttpError::HttpError ( const char *  file,
const unsigned int  line,
const char *  function,
const std::string &  url,
int  code,
std::istream &  response 
)

Constructs an HttpError.

Parameters
[in]fileName of source file in which the error occurred.
[in]lineSource line number for the error.
[in]functionFunction name in which the error occured.
[in]urlThe request URL.
[in]codeThe HTTP result code.
[in,out]responseThe response body.
dg::deepcore::network::JsonRpcError::JsonRpcError ( )

The default constructor.

dg::deepcore::network::JsonRpcError::JsonRpcError ( const std::string &  file,
const unsigned int  line,
const std::string &  function,
const JsonRpcErrorType  type,
const std::string &  message 
)

Constructs an Error.

Parameters
[in]fileName of source file in which the error occurred.
[in]lineSource line number for the error.
[in]functionFunction name in which the error occured.
[in]typeA preset code-short message pair from the JSON-RPC standard.
[in]messageThe error message.
dg::deepcore::network::JsonRpcError::JsonRpcError ( const std::string &  file,
const unsigned int  line,
const std::string &  function,
const int  code,
const std::string &  shortMessage,
const std::string &  message 
)

Constructs an Error.

Parameters
[in]fileName of source file in which the error occurred.
[in]lineSource line number for the error.
[in]functionFunction name in which the error occurred.
[in]codeThe code for the JSON-RPC error.
[in]shortMessageThe short message for the JSON-RPC error.
[in]messageThe error message.
dg::deepcore::network::JsonRpcError::JsonRpcError ( const Error error,
const JsonRpcErrorType  type 
)

Constructs a JsonRpcError based on an error.

Parameters
[in]errorThe error from which to copy the file, line, function, and message.
[in]typeA preset code-short message pair from the JSON-RPC standard.
dg::deepcore::network::HttpCleanup::~HttpCleanup ( )

The destructor.

string dg::deepcore::network::buildUrl ( const string &  baseUrl,
const map< string, string > &  args 
)

Combines a base URL and query string.

Parameters
[in]baseUrlThe base URL.
[in]argsArguments for the query string.
Returns
The combined URL.
void dg::deepcore::network::JsonRpc::clearId ( )
noexcept

Clear the id if it had been previously set.

See Also
JsonRpc::setId()
int dg::deepcore::network::HttpError::code ( ) const
noexcept

Gets the HTTP result code.

Returns
The HTTP result code.
int dg::deepcore::network::JsonRpcError::code ( ) const

A Number that indicates the error type that occurred.

Returns
the error code

The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use. See http://www.jsonrpc.org/specification for predefined errors.

The remainder of the space is available for application defined errors.

Json::Value dg::deepcore::network::JsonRpcError::data ( ) const

Get additional information about the error.

Returns
A marshalled Json::Value object with error data (or JSON::Value::Null ff error data has not been set.)

In general, this is a Primitive or Structured value that contains additional information about the error. It may be omitted.

If this is created from an exception, this is populated with an object that contains the line, function, file, and message from the exception.

const JsonRpcError & dg::deepcore::network::JsonRpcResponse::error ( ) const
noexcept

If this response contains an error, get it.

Returns
The error object
See Also
JsonRpcResponse::setError()
JsonRpcError dg::deepcore::network::JsonRpcError::fromData ( const int  code,
const std::string &  shortMessage,
const Json::Value &  data 
)
static

Constructs a JsonRpcError without thrown metadata.

Parameters
[in]codeThe code for the JSON-RPC error.
[in]shortMessageThe short message for the JSON-RPC error.
[in]dataA object containing the exception details. If this is parsable, it will be split into file/line/function/message
JsonRpcError dg::deepcore::network::JsonRpcError::fromFormat ( const char *  file,
const unsigned int  line,
const char *  function,
const JsonRpcErrorType  type,
const char *  format,
  ... 
)
staticnoexcept

Creates an error with a message that can be formatted using sprintf-style format.

Parameters
[in]fileName of source file in which the error occurred.
[in]lineSource line number for the error.
[in]functionFunction name in which the error occured.
[in]typeJSON error type.
[in]formatThe sprintf-style format specifier for the error message.
[in]...Arguments for format specification.
Returns
The error.
ApacheTomcatError dg::deepcore::network::ApacheTomcatError::fromHtml ( const std::string &  html)
static

Parses an HTML Apache Tomcat error report from a string.

Parameters
[in]htmlThe HTML string to parse.
Returns
The parsed object.
virtual void dg::deepcore::network::JsonObject::fromJson ( const Json::Value &  root)
pure virtual

Unmarshal this object to a JSON container.

Beware that a string is also valid json, so fromJson will interpret a passed in string as a string literal without parsing it.

Implemented in dg::deepcore::network::JsonRpcResponse, and dg::deepcore::network::JsonRpcRequest.

void dg::deepcore::network::JsonObject::fromJsonString ( const std::string &  root)

Unmarshal this object from a JSON string.

shared_ptr< HttpCleanup > dg::deepcore::network::HttpCleanup::get ( )
static

Initialize curl for the lifetime of the returned shared pointer.

Returns
A shared pointer that keeps curl initialized.
bool dg::deepcore::network::JsonRpcResponse::hasError ( ) const
noexcept

Does this response contain an error object?

Returns
True if this response contains an error object
See Also
JsonRpcResponse::setError()
const bool dg::deepcore::network::JsonRpc::hasId ( ) const
noexcept

Determine if the id in this JSON-RPC packet has been set.

Returns
True if the ID for this object has been set
See Also
JsonRpc::id()
bool dg::deepcore::network::JsonRpcResponse::hasResult ( ) const
noexcept

Does this response contain an result object?

Returns
True if this response contains an result object
See Also
JsonRpcResponse::setResult()
const Json::Value & dg::deepcore::network::JsonRpc::id ( ) const
noexcept

Get an identifier established by the Client to disambiguate responses.

Returns
An identifier as a JSON::Value object
See Also
JsonRpc::setId()
const std::string & dg::deepcore::network::JsonRpcRequest::method ( ) const
noexcept

Get the name of the method to be invoked.

Returns
the name of the method
See Also
JsonRpcRequest::setMethod()
const Json::Value & dg::deepcore::network::JsonRpcRequest::params ( ) const
noexcept

Get a marshalled set of parameters.

Returns
The parameters for this request, or JSON::Value::Null if none are set
See Also
JsonRpcRequest::setParams()
const vector< uint8_t > & dg::deepcore::network::HttpError::response ( ) const
noexcept

Gets the response body.

Returns
The response body.
std::string dg::deepcore::network::HttpError::responseAsString ( ) const
noexcept

Gets the response body as an std::string.

Returns
The response body.
const Json::Value & dg::deepcore::network::JsonRpcResponse::result ( ) const
noexcept

If this response contains an result, get it.

Returns
the marshalled result object
void dg::deepcore::network::JsonRpcResponse::setError ( const JsonRpcError error)
noexcept

If this response contains an error, get it.

Parameters
[in]errorThe error object

This member is REQUIRED on success.

This member MUST NOT exist if there was an error invoking the method.

The value of this member is determined by the method invoked on the Server.

void dg::deepcore::network::JsonRpc::setId ( const Json::Value &  id)
noexcept

Set an identifier established by the Client to disambiguate responses.

Parameters
[in]idThe identifier for this object

An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2] The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.

[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.

[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

void dg::deepcore::network::JsonRpcRequest::setMethod ( const std::string &  method)
noexcept

Set the name of the method to be invoked.

Parameters
[in]methodThe name of the method

A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else.

void dg::deepcore::network::JsonRpcRequest::setParams ( const Json::Value &  params)
noexcept

Set a marshalled set of parameters.

Parameters
[in]paramsThe parameters for this request

A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted.

void dg::deepcore::network::JsonRpcResponse::setResult ( const Json::Value &  result)
noexcept

Set a result object for this response.

Parameters
[in]resultA marshalled result object

This member is REQUIRED on error.

This member MUST NOT exist if there was no error triggered during invocation.

void dg::deepcore::network::JsonRpc::setVersion ( const std::string &  version)
noexcept

Set a string specifying the version of the JSON-RPC protocol.

Parameters
[in]versionThe version string of this object
std::string dg::deepcore::network::JsonRpcError::shortMessage ( ) const

Get a string providing a short description of the error.

Returns
a short description of the error

The message SHOULD be limited to a concise single sentence.

This is used for the JSON message element.

See Also
JsonRpcError::code() for recommented shortMessages with given error code-messages
string dg::deepcore::network::splitUrlQuery ( const string &  url,
map< string, string > &  args 
)

Split the URL into base url and query arguments.

Note
This does not check the URL for validity, just splits out the query string arguments. It will elimitate the trailing "/" from the base URL for consistency.
Parameters
[in]urlThe input URL.
[in,out]argsThe URL query arguments. Note that this function will append arguments to the existing map.
Returns
The base url.
const string & dg::deepcore::network::HttpError::status ( ) const
noexcept

Gets the description of the HTTP status code.

Returns
The description of the HTTP status code.
virtual Json::Value dg::deepcore::network::JsonObject::toJson ( ) const
pure virtual

Marshal this object to a JSON container.

Implemented in dg::deepcore::network::JsonRpcResponse, and dg::deepcore::network::JsonRpcRequest.

const string & dg::deepcore::network::HttpError::url ( ) const
noexcept

Gets the request URL.

Returns
The request URL.
string dg::deepcore::network::urlDecode ( const string &  str)

Decodes a string previously encoded with urlEncode, or equivalent. Equivalent to the JavaScript decodeURIComponent.

Parameters
[in]strThe string to decode.
Returns
The decoded string.
string dg::deepcore::network::urlEncode ( const string &  str)

Encodes a string to be used as a URL query component. Equivalent to the JavaScript encodeURIComponent.

Parameters
[in]strThe string to encode.
Returns
The encoded string
const std::string & dg::deepcore::network::JsonRpc::version ( ) const
noexcept

Get a string specifying the version of the JSON-RPC protocol.

Returns
the version string of this object
See Also
JsonRpc::setVersion()