DataStreamClient::DataStreamClient Class Reference

Extends RestClient with support for the DataStream protocol. More...

#include <DataStreamClient.qm.dox.h>

Inherits RestClient::RestClient.

Public Member Methods
void	recvDataStream (auto body, timeout timeout_ms, soft< hash< auto > > hdr, string path, soft< reference< hash< auto > > > info, DataStreamRecvMessage dsm, string method)
	sends an HTTP request to an HTTP REST server supporting the DataStream protocol and returns the decoded and deserialized response in the given callback as each HTTP chunk is received
hash< auto >	sendDataStream (string path, timeout timeout_ms, soft< hash< auto > > hdr, DataStreamSendMessage dsm, string method, soft< reference< hash< auto > > > info)
	Sends an HTTP request to an HTTP REST server supporting the DataStream protocol with the specified method and chunked message body as given by a send callback and returns the deserialized body and response headers received as a response.
void	sendRecvDataStream (string path, timeout timeout_ms, soft< hash< auto > > hdr, DataStreamMessage dsm, string method, soft< reference< hash< auto > > > info)
	Sends an HTTP request an HTTP REST server supporting the DataStream protocol with the specified method and serialized and encoded chunked message body as given by a send callback; decoded and deserialized data received from the HTTP server are returned through a receive callback.
hash< auto >	sendRawStream (soft< string > path, timeout timeout_ms, soft< hash< auto > > hdr, code scb, string method, soft< reference< hash< auto > > > info)
	send raw chunked data to the client and expect a YAML-formatted response
void	addDefaultHeaders (hash< auto > h)
	adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well
void	setContentEncoding (string enc)
	sets the request and desired response encoding for the object; see EncodingSupport for valid options
nothing	prepareMsg (reference< hash< auto > > hdr, string ct, reference< auto > body, string method, string path)
	sets up headers and encodes any body for sending

Public Attributes
const auto	Version = ...
	DataStreamClient Version.
const auto	VersionString = ...
	DataStreamClient Version String.
const auto	DefaultHeaders = ...
	default HTTP headers

Detailed Description

Extends RestClient with support for the DataStream protocol.

Member Function Documentation

addDefaultHeaders()

void DataStreamClient::DataStreamClient::addDefaultHeaders

(

hash< auto >

h

)

adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well

Example:

# disable gzip and bzip encoding in responses
rest.addDefaultHeaders(("Accept-Encoding": "compress"));

Parameters

h	a hash of headers to add to the default headers to send on each request

Note

default headers can also be set in the constructor

See also

RestClient::getDefaultHeaders()

recvDataStream()

void DataStreamClient::DataStreamClient::recvDataStream	(	auto	body,
		timeout	timeout_ms,
		soft< hash< auto > >	hdr,
		string	path,
		soft< reference< hash< auto > > >	info,
		DataStreamRecvMessage	dsm,
		string	method
	)

sends an HTTP request to an HTTP REST server supporting the DataStream protocol and returns the decoded and deserialized response in the given callback as each HTTP chunk is received

Example:

rest.recvDataStream(reccallback, "GET", "/orders/1", body);

Parameters

dsm	the DataStreamRecvMessage object providing the DataStreamRecvMessage::recvData() and DataStreamRecvMessage::recvDataDone() methods to be used as callbacks
method	the HTTP method to be used; case is ignored (if not a valid method an HTTP-CLIENT-METHOD-ERROR exception is raised)
path	the URI path to add (will be appended to any root path given in the constructor)
body	an optional message body to be included in the request; if a value for this parameter is passed to the method, then the body will be serialized with YAML serialization
timeout_ms	the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash equal to the normal return value of this method including a "status_code" key (giving the status code) and a "body" key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received
DESERIALIZATION-ERROR	the response body could not be deserialized (unknown Content-Type or invalid serialization)

Note

this method can also be used if the server returns a non-chunked response; the response body will be decoded, deserialized, and passed to the receive callback as if a chunked body were received, additionally the terminating call with no arguments is also made to signal the end of the chunked data

sendDataStream()

hash< auto > DataStreamClient::DataStreamClient::sendDataStream	(	string	path,
		timeout	timeout_ms,
		soft< hash< auto > >	hdr,
		DataStreamSendMessage	dsm,
		string	method,
		soft< reference< hash< auto > > >	info
	)

Sends an HTTP request to an HTTP REST server supporting the DataStream protocol with the specified method and chunked message body as given by a send callback and returns the deserialized body and response headers received as a response.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:

hash<auto> h = rest.sendDataStream(callback, "POST", "/path");

Parameters

dsm	the DataStreamSendMessage object providing the DataStreamSendMessage::sendData() method to be used as a callback
method	The name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
path	the URI path to add (will be appended to any root path given in the constructor)
timeout_ms	the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
info	An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns

The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be decoded and deserialized and assigned to the value of the "body" key, and the HTTP status will be assigned to the "status_code" key. In the case of a chunked DataStream response, the "body" key will be assigned a list where each list element is the data value of the respective DataStream chunk

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash equal to the normal return value of this method including a "status_code" key (giving the status code) and a "body" key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note

• The "Transfer-Encoding: chunked" header is automatically set with this method if no "Transfer-Encoding" header is already present
• For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
• this method can also be used when the server returns chunked DataStream protocol data; in this case the chunked response is received in its entirity and returns in the return value's "body" key as a list where each list element is the data value of the respective DataStream chunk
• the value of the return value's "body" key will be decoded and deserialized data

sendRawStream()

hash< auto > DataStreamClient::DataStreamClient::sendRawStream	(	soft< string >	path,
		timeout	timeout_ms,
		soft< hash< auto > >	hdr,
		code	scb,
		string	method,
		soft< reference< hash< auto > > >	info
	)

send raw chunked data to the client and expect a YAML-formatted response

Example:

hash<auto> h = rest.sendRawStream(sender, "POST", uri_path, 20s);

The request will be made with the "Accept" header set to "application/x-yaml"; replies are expected to be YAML-serialized data. Note that the "body" key in the return value will contain the deserialized YAML payload as Qore data.

Parameters

scb	The callback giving the chunked HTTP data to send; this callback must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be sent or simply nothing which will close the chunked message
method	The name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
path	The path for the message (i.e. "/path/resource?method&param=value")
timeout_ms	the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
info	An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request.
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Returns

The headers received from the HTTP server with all key names converted to lower-case. The deserialized YAML message body (if any) will be assigned to the value of the "body" key and the HTTP status will be assigned to the "status_code" key.

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash equal to the normal return value of this method including a "status_code" key (giving the status code) and a "body" key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

sendRecvDataStream()

void DataStreamClient::DataStreamClient::sendRecvDataStream	(	string	path,
		timeout	timeout_ms,
		soft< hash< auto > >	hdr,
		DataStreamMessage	dsm,
		string	method,
		soft< reference< hash< auto > > >	info
	)

Sends an HTTP request an HTTP REST server supporting the DataStream protocol with the specified method and serialized and encoded chunked message body as given by a send callback; decoded and deserialized data received from the HTTP server are returned through a receive callback.

This method is useful for sending streaming data in the request and where streaming data is also expected in the response.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:

rest.sendRecvDataStream(send_callback, reccallback, "POST", "/path");

Parameters

dsm	the DataStreamMessage object providing the DataStreamMessage::sendData(), DataStreamMessage::recvData(), and DataStreamMessage::recvDataDone() methods method to be used as callbacks
method	The name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
path	The path for the message (i.e. "/path/resource?method&param=value")
timeout_ms	the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
info	An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request.
hdr	any headers to be sent with the request; headers here will override default headers for the object as well

Exceptions

HTTP-CLIENT-METHOD-ERROR	invalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERROR	invalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED	maximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERROR	unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash equal to the normal return value of this method including a "status_code" key (giving the status code) and a "body" key (giving the message body returned by the server)
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	There was an error sending the data
SOCKET-CLOSED	The remote end closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	Data transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received

Note

• The "Transfer-Encoding: chunked" header is automatically set with this method if no "Transfer-Encoding" header is already present
• For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

this method can also be used if the server returns a non-chunked response; the response body will be decoded, deserialized, and passed to the receive callback as if a chunked body were received, additionally the terminating call with no arguments is also made to signal the end of the chunked data

setContentEncoding()

void DataStreamClient::DataStreamClient::setContentEncoding

(

string

enc

)

sets the request and desired response encoding for the object; see EncodingSupport for valid options

Example:

rest.setContentEncoding("gzip");

Parameters

enc	the data content encoding (compression) option for requests and the desired response content encoding for the object; see EncodingSupport for valid options; if the value "auto" is passed then "gzip" encoding is used for outgoing requests and requested for responses

Exceptions

RESTCLIENT-ERROR

invalid or unsupported data content encoding / compression option

---

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

• doxygen/qlib/DataStreamClient/DataStreamClient.qm.dox.h