Qore DataStreamClient Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
DataStreamClient::DataStreamClient Class Reference

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

Inherits RestClient.

Public Member Functions

 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 Functions

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

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:
1 # disable gzip and bzip encoding in responses
2 rest.addDefaultHeaders(("Accept-Encoding": "compress"));
Parameters
ha 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()
DataStreamClient::DataStreamClient::constructor ( *hash  opts,
*softbool  do_not_connect 
)

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

Example:
1 DataStreamClient ds(("url": "http://localhost:8001/rest"));
Parameters
optsvalid 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_connectif False (the default), then a connection will be immediately established to the remote server
Exceptions
RESTCLIENT-ERRORinvalid option passed to constructor, unsupported data serialization, etc
Note
the data argument to RestClient::constructor() is set to "yaml" automatically
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:
1 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
rcbThe 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)
methodThe 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.
pathThe path for the message (i.e. "/path/resource?method&param=value")
bodyan 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_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoAn 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.
hdrAn optional hash of headers to include in the message.
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
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:
1 rest.recvDataStream(recvcallback, endcallback, "GET", "/orders/1", body);
Parameters
rcbThe receive callback for the data received; the argument passed to this callback is the decoded and deserialized data in the message
ecbWhen 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
methodthe HTTP method to be used; case is ignored (if not a valid method an HTTP-CLIENT-METHOD-ERROR exception is raised)
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoan 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
hdrany headers to be sent with the request; headers here will override default headers for the object as well
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
DESERIALIZATION-ERRORthe 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
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:
1 rest.recvDataStream(reccallback, "GET", "/orders/1", body);
Parameters
dsmthe DataStreamRecvMessage object providing the DataStreamRecvMessage::recvData() and DataStreamRecvMessage::recvDataDone() methods to be used as callbacks
methodthe HTTP method to be used; case is ignored (if not a valid method an HTTP-CLIENT-METHOD-ERROR exception is raised)
paththe URI path to add (will be appended to any root path given in the constructor)
bodyan 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_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoan 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
hdrany headers to be sent with the request; headers here will override default headers for the object as well
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
DESERIALIZATION-ERRORthe 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
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:
1 hash h = rest.sendDataStream(callback, "POST", "/path");
Parameters
scbThe 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
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
paththe URI path to add (will be appended to any root path given in the constructor)
timeout_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoAn 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
hdrany 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
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:
1 hash h = rest.sendDataStream(callback, "POST", "/path");
Parameters
dsmthe DataStreamSendMessage object providing the DataStreamSendMessage::sendData() method to be used as a callback
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
paththe URI path to add (will be appended to any root path given in the constructor)
timeout_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoAn 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
hdrany 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
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:
1 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
scbThe 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
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
pathThe path for the message (i.e. "/path/resource?method&param=value")
timeout_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoAn 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.
hdrany 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-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
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:
1 rest.sendRecvDataStream(send_callback, reccallback, "POST", "/path");
Parameters
scbThe 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
rcbThe receive callback for the data received; the argument passed to this callback is the decoded and deserialized data in the message
ecbWhen 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
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
pathThe path for the message (i.e. "/path/resource?method&param=value")
timeout_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoAn 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.
hdrany headers to be sent with the request; headers here will override default headers for the object as well
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
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:
1 rest.sendRecvDataStream(send_callback, reccallback, "POST", "/path");
Parameters
dsmthe DataStreamMessage object providing the DataStreamMessage::sendData(), DataStreamMessage::recvData(), and DataStreamMessage::recvDataDone() methods method to be used as callbacks
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
pathThe path for the message (i.e. "/path/resource?method&param=value")
timeout_msthe timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
infoAn 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.
hdrany headers to be sent with the request; headers here will override default headers for the object as well
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown 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-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid 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
DataStreamClient::DataStreamClient::setContentEncoding ( string  enc = "auto")

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

Example:
1 rest.setContentEncoding("gzip");
Parameters
encthe 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-ERRORinvalid or unsupported data content encoding / compression option