DataStreamClient::DataStreamClient Class Reference

this class extends RestClient with support for the DataStream protocol More...

Inherits RestClient.

Public Member Methods
	constructor (*hash opts, *softbool do_not_connect)
	calls the base class RestClient constructor and optionally connects to the REST server More...
	recvDataStream (code rcb, code ecb, string method, string path, any body, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	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 More...
	recvDataStream (DataStreamRecvMessage dsm, string method, string path, any body, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	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 More...
hash	sendDataStream (code scb, string method, string path, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	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. More...
hash	sendDataStream (DataStreamSendMessage dsm, string method, string path, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	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. More...
	sendRecvDataStream (code scb, code rcb, code ecb, string method, string path, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	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. More...
	sendRecvDataStream (DataStreamMessage dsm, string method, string path, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	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. More...
hash	sendRawStream (code scb, string method, *string path, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	send raw chunked data to the client and expect a YAML-formatted response More...
hash	getRawStream (code rcb, string method, *string path, any body, timeout timeout_ms=0, *reference< hash > info, *hash hdr)
	receives raw chunked data using the given closure and returns any headers received More...
	addDefaultHeaders (hash h)
	adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well More...
	setContentEncoding (string enc='auto')
	sets the request and desired response encoding for the object; see EncodingSupport for valid options More...
hash	sendAndDecodeResponse (*data body, string m, string path, hash hdr, *reference< hash > info, *softbool decode_errors)
	sends the outgoing HTTP message and recodes the response to data

Public Attributes
const	Version = "1.1"
	DataStreamClient Version.
const	VersionString = sprintf("Qore-DataStreamClient/%s", DataStreamClient::Version)
	DataStreamClient Version String.
const	DefaultHeaders
	default HTTP headers

Private Member Methods
nothing	prepareMsg (string method, string path, reference body, reference< hash > hdr, string ct='Content-Type')
	sets up headers and encodes any body for sending

Detailed Description

this class extends RestClient with support for the DataStream protocol

Member Function Documentation

addDefaultHeaders()

DataStreamClient::DataStreamClient::addDefaultHeaders

(

hash

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()

constructor()

DataStreamClient::DataStreamClient::constructor	(	*hash	opts,
		*softbool	do_not_connect
	)

calls the base class RestClient constructor and optionally connects to the REST server

Example:

DataStreamClient ds(("url": "http://localhost:8001/rest"));

Parameters

opts

valid options are: connect_timeout: The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: 20s) default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL default_port: The default port number to connect to if none is given in the URL headers: an optional hash of headers to send with every request, these can also be overridden in request method calls http_version: Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers max_redirects: The maximum number of redirects before throwing an exception (the default is 5) proxy: The proxy URL for connecting through a proxy timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 30s) url: A string giving the URL to connect to

do_not_connect

if False (the default), then a connection will be immediately established to the remote server

Exceptions

RESTCLIENT-ERROR

invalid option passed to constructor, unsupported data serialization, etc

Note

the data argument to RestClient::constructor() is set to "yaml" automatically

getRawStream()

hash DataStreamClient::DataStreamClient::getRawStream	(	code	rcb,
		string	method,
		*string	path,
		any	body,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

receives raw chunked data using the given closure and returns any headers received

Example:

hash h = rest.getRawStream(recv, "GET", uri_path, 20s);

Any message body will be serialized as YAML and the "Content-Type" header will be set to "application/x-yaml".

Parameters

rcb	The receive callback for the data received; first this method is called with a hash of the message headers, and then with any message body; if a chunked HTTP message is received, then the callback is called once for each chunk; when the message has been received, then the receive callback is called with a hash representing any trailer data received in a chunked transfer or nothing if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys: "data": the string or binary data "chunked": True if the data was received with chunked transfer encoding, False if not Header or trailer data is placed in a hash with the following keys: "hdr": this can be assigned to nothing for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message "obj": this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)
method	The name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT"). Additional methods can be added in the constructor as a additional_methods option.
path	The path for the message (i.e. "/path/resource?method&param=value")
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 an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request.
hdr	An optional hash of headers to include in the message.

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

For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

recvDataStream() [1/2]

DataStreamClient::DataStreamClient::recvDataStream	(	code	rcb,
		code	ecb,
		string	method,
		string	path,
		any	body,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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(recvcallback, endcallback, "GET", "/orders/1", body);

Parameters

rcb	The receive callback for the data received; the argument passed to this callback is the decoded and deserialized data in the message
ecb	When the chunked transfer has completed; this must accept a *string argument; this is called with no arguments once all data has been received if the sender does not report a send error, otherwise it's called with a single string giving the send error reported by the sending side in the DataStream-Error trailer record
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

recvDataStream() [2/2]

DataStreamClient::DataStreamClient::recvDataStream	(	DataStreamRecvMessage	dsm,
		string	method,
		string	path,
		any	body,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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() [1/2]

hash DataStreamClient::DataStreamClient::sendDataStream	(	code	scb,
		string	method,
		string	path,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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 h = rest.sendDataStream(callback, "POST", "/path");

Parameters

scb	The callback giving the chunked HTTP data to send; the data returned by this callback will be serialized to YAML and send via the DataStream protocol to the remote HTTP REST server in HTTP chunked format; when all data has been send then this callback should return nothing, which will close the chunked message and terminate the request
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

sendDataStream() [2/2]

hash DataStreamClient::DataStreamClient::sendDataStream	(	DataStreamSendMessage	dsm,
		string	method,
		string	path,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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 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 DataStreamClient::DataStreamClient::sendRawStream	(	code	scb,
		string	method,
		*string	path,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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

Example:

hash 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() [1/2]

DataStreamClient::DataStreamClient::sendRecvDataStream	(	code	scb,
		code	rcb,
		code	ecb,
		string	method,
		string	path,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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

scb	The callback giving the chunked HTTP data to send; the data returned by this callback will be serialized to YAML and send via the DataStream protocol to the remote HTTP REST server in HTTP chunked format; when all data has been send then this callback should return nothing, which will close the chunked message and terminate the request
rcb	The receive callback for the data received; the argument passed to this callback is the decoded and deserialized data in the message
ecb	When the chunked transfer has completed; this must accept a *string argument; this is called with no arguments once all data has been received if the sender does not report a send error, otherwise it's called with a single string giving the send error reported by the sending side in the DataStream-Error trailer record
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

sendRecvDataStream() [2/2]

DataStreamClient::DataStreamClient::sendRecvDataStream	(	DataStreamMessage	dsm,
		string	method,
		string	path,
		timeout	timeout_ms = 0,
		*reference< hash >	info,
		*hash	hdr
	)

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()

DataStreamClient::DataStreamClient::setContentEncoding

(

string

enc = 'auto'

)

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