coral::net::reqrep::Client Class Reference

A backend class for clients that communicate with a Server. More...

#include "coral/net/reqrep.hpp"

Public Types
typedef std::function< void(const std::error_code &ec, const char *replyHeader, size_t replyHeaderSize, const char *replyBody, size_t replyBodySize)>	ReplyHandler
	A callback type for Request(). More...
typedef std::function< void(const std::error_code &ec, std::uint16_t version)>	MaxProtocolReplyHandler
	A callback type for RequestMaxProtocol(). More...

Public Member Functions
	Client (coral::net::Reactor &reactor, const std::string &protocolIdentifier, const coral::net::Endpoint &serverEndpoint)
	Constructs a new client instance connected to the given endpoint, and registers it with the given reactor to be notified of replies to the requests that are sent. More...
void	Request (std::uint16_t protocolVersion, const char *requestHeader, size_t requestHeaderSize, const char *requestBody, size_t requestBodySize, std::chrono::milliseconds timeout, ReplyHandler onComplete)
	Sends a request. More...
void	RequestMaxProtocol (std::chrono::milliseconds timeout, MaxProtocolReplyHandler onComplete)
	Sends a "meta request" to the server asking for the maximum protocol version it supports. More...

Detailed Description

A backend class for clients that communicate with a Server.

This class represents the client side of the generic request-reply protocol. An instance of this class may only connect to one server at a time.

See also

Server For the server-side class and more information about the protocol.

Member Typedef Documentation

typedef std::function<void( const std::error_code& ec, std::uint16_t version)> coral::net::reqrep::Client::MaxProtocolReplyHandler

A callback type for RequestMaxProtocol().

If ec contains an error code, the contents of protocolVersion are unspecified.

Parameters

[in]	ec	If the request failed, this holds an error code. This will typically be std::errc::timed_out, signifying that the server didn't respond in time, or std::errc::protocol_not_supported, which means that the server does not support any version of the protocol.
[in]	protocolVersion	The maximum version of the protocol that the server supports.

typedef std::function<void( const std::error_code& ec, const char* replyHeader, size_t replyHeaderSize, const char* replyBody, size_t replyBodySize)> coral::net::reqrep::Client::ReplyHandler

A callback type for Request().

If ec contains an error code, the contents of the other arguments are unspecified.

Parameters

[in]	ec	If the request failed, this holds an error code. This will typically be std::errc::timed_out, signifying that the server didn't respond in time.
[in]	replyHeader	A pointer to the start of a memory buffer which holds the reply header, the length of which is given by replyHeaderSize. This is never null, but may be empty (i.e., zero length).
[in]	replyHeaderSize	The length (in bytes) of the reply header.
[in]	replyBody	A pointer to the start of a memory buffer which holds the reply body, the length of which is given by replyBodySize. Iff the reply has no body, this will be null.
[in]	replyBodySize	The length (in bytes) of the reply body if replyBody is not null, otherwise unspecified.

Constructor & Destructor Documentation

coral::net::reqrep::Client::Client	(	coral::net::Reactor &	reactor,
		const std::string &	protocolIdentifier,
		const coral::net::Endpoint &	serverEndpoint
	)

Constructs a new client instance connected to the given endpoint, and registers it with the given reactor to be notified of replies to the requests that are sent.

protocolIdentifier must contain the identifier for the protocol with which requests will be made.

Member Function Documentation

void coral::net::reqrep::Client::Request	(	std::uint16_t	protocolVersion,
		const char *	requestHeader,
		size_t	requestHeaderSize,
		const char *	requestBody,
		size_t	requestBodySize,
		std::chrono::milliseconds	timeout,
		ReplyHandler	onComplete
	)

Sends a request.

This sends a request using the protocol whose identifier was given in the class constructor and whose version is given by protocolVersion. The Server on the other end must have a protocol handler associated with the same identifier and version.

Parameters

[in]	protocolVersion	The version number of the protocol with which the request is made.
[in]	requestHeader	A pointer to the start of a memory buffer which holds the request header, the length of which is given by requestHeaderSize. This cannot be null, but may be empty (i.e., zero length).
[in]	requestHeaderSize	The length (in bytes) of the request header.
[in]	requestBody	A pointer to the start of a memory buffer which holds the request body, the length of which is given by requestBodySize. If the request has no body, this may be null.
[in]	requestBodySize	The length (in bytes) of the request body if requestBody is not null, otherwise this is ignored.
[in]	timeout	How long to wait to be able to send the request before throwing an exception, or, if the actual sending was successful, how long to wait for a reply before calling onComplete with an error code.
[in]	onComplete	A callback that will be called when the server responds or the request times out. This function is guaranteed to be called unless Request() throws an exception or the Client is destroyed before a reply can be received.

Exceptions

std::runtime_error	If the timeout is reached before the message could even be sent (typically because the connection to the server has failed or has yet to be established).
zmq::error_t	On communications error.

void coral::net::reqrep::Client::RequestMaxProtocol	(	std::chrono::milliseconds	timeout,
		MaxProtocolReplyHandler	onComplete
	)

Sends a "meta request" to the server asking for the maximum protocol version it supports.

The server will respond with the greatest version number that has been added with Server::AddProtocolHandler().

Parameters

[in]	timeout	How long to wait to be able to send the request before throwing an exception, or, if the actual sending was successful, how long to wait for a reply before calling onComplete with an error code.
[in]	onComplete	A callback that will be called when the server responds or the request times out. This function is guaranteed to be called unless RequestMaxProtocol() throws an exception or the Client is destroyed before a reply can be received.

Exceptions

std::runtime_error	If the timeout is reached before the message could even be sent (typically because the connection to the server has failed or has yet to be established).
zmq::error_t	On communications error.

---

The documentation for this class was generated from the following file:

• coral/net/reqrep.hpp