Qore DataStreamUtil Module Reference  1.1
 All Namespaces Functions Variables Groups Pages
DataStreamUtil Namespace Reference

the DataStreamUtil namespace contains all the public objects in the DataStreamUtil module More...

Functions

*code ds_get_content_decode (*string ce)
 returns a call reference (or nothing) based on an optional "Content-Encoding" header value for decoding HTTP encoded data More...
 
*code ds_get_content_encode (*string ce)
 returns a call reference (or nothing) based on an optional "Content-Encoding" header value for encoding HTTP encoded data More...
 
code ds_get_send (code scb, *code enc_func)
 returns a call reference useful for sending HTTP chunked data with Qore methods taking send callbacks; data is encoded with YAML and optionally a content encoding call reference or closure More...
 
code ds_get_recv (code rcb, code ecb, *code bcb)
 returns a call reference useful for receiving HTTP chunked data with Qore methods taking receive callbacks; YAML data is deserialized and passed as Qore data to the given callback argument More...
 
nothing ds_set_chunked_headers (reference< hash > hdr, *string content_encoding, *softbool req)
 sets up HTTP headers for DataStream chunked data transfers More...
 
nothing ds_set_non_chunked_headers (reference< hash > hdr, *string content_encoding, *softbool req)
 sets up HTTP headers for DataStream non-chunked data transfers More...
 
string ds_get_ds_accept_enc_header (*string ae)
 returns the "DataStream-Accept-Encoding" header value corresponding to the "Accept-Encoding" header passed as an argument, or "identity" if none present More...
 

Variables

const DataStreamContentType = "DataStream-Content-Type"
 HTTP header for the data stream Content-Type header equivalent where each HTTP chunk is encoded/decoded separately. More...
 
const DataStreamContentEncoding = "DataStream-Content-Encoding"
 HTTP header for the data stream Content-Encoding header equivalent where each HTTP chunk is encoded/decoded separately.
 
const DataStreamAccept = "DataStream-Accept"
 HTTP header for the data stream Accept header equivalent where each HTTP chunk is encoded/decoded separately.
 
const DataStreamAcceptEncoding = "DataStream-Accept-Encoding"
 HTTP header for the data stream Accept-Encoding header equivalent where each HTTP chunk is encoded/decoded separately.
 
const DataStreamError = "DataStream-Error"
 HTTP trailer to be sent after chunked data has been transferred in case of an error on the sending side, giving a string describing the error.
 
const DataStreamContentEncodingHash
 supported values for the DataStream-Accept-Encoding header
 

Detailed Description

the DataStreamUtil namespace contains all the public objects in the DataStreamUtil module

Function Documentation

*code DataStreamUtil::ds_get_content_decode ( *string  ce)

returns a call reference (or nothing) based on an optional "Content-Encoding" header value for decoding HTTP encoded data

Example:
1 *code decode = ds_get_content_decode(hdr."content-encoding");

The following "Content-Encoding" values are recognized:

  • "deflate", "x-deflate": returns a call reference to uncompress_to_string()
  • "gzip", "x-gzip": returns a call reference to gunzip_to_string()
  • "bzip2", "x-bzip2": returns a call reference to bunzip2_to_string()
  • "identity", nothing: returns nothing
Returns
a call reference (or nothing) based on an optional "Content-Encoding" header value for decoding HTTP encoded data
Exceptions
DESERIALIZATION-ERRORthis exception is thrown if the content encoding is not recognized
Note
HTTP headers in requests are converted to lower-case only on receipt
*code DataStreamUtil::ds_get_content_encode ( *string  ce)

returns a call reference (or nothing) based on an optional "Content-Encoding" header value for encoding HTTP encoded data

Example:
1 *code decode = ds_get_content_encode("bzip2");

The following "Content-Encoding" values are recognized:

  • "deflate": returns a call reference to compress()
  • "gzip": returns a call reference to gzip()
  • "bzip2": returns a call reference to bzip2()
  • "identity", nothing: returns nothing
Returns
a call reference (or nothing) based on an optional "Content-Encoding" header value for encoding HTTP encoded data
Exceptions
SERIALIZATION-ERRORthis exception is thrown if the content encoding is not recognized
string DataStreamUtil::ds_get_ds_accept_enc_header ( *string  ae)

returns the "DataStream-Accept-Encoding" header value corresponding to the "Accept-Encoding" header passed as an argument, or "identity" if none present

Example:
1 string dae = ds_get_ds_accept_enc_header(hdr."Accept-Encoding");
Parameters
aethe value of the "Accept-Encoding" header or "identity" if not present
Returns
the "DataStream-Accept-Encoding" value corresponding to the "Accept-Encoding" header passed as an argument, or nothing if none should be sent
code DataStreamUtil::ds_get_recv ( code  rcb,
code  ecb,
*code  bcb 
)

returns a call reference useful for receiving HTTP chunked data with Qore methods taking receive callbacks; YAML data is deserialized and passed as Qore data to the given callback argument

Example:
1 httpclient.sendWithRecvCallback(ds_get_recv(rcb), body, method, path, hdr, timeout_ms, False, \info);
Parameters
rcbthe data callback; this is called once for each deserialized chunked transfer from the remote end with the deserialized data, and then once with nothing when all data has been received
ecbthe "end of data" callback; 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
bcban optional "body callback"; if this argument is passed, it must take a string argument which will be the content-decoded raw message body before any data deserialization and a second string argument giving the content-type of the body
Returns
a call reference useful for receiving HTTP chunked data with Qore methods taking receive callbacks; when HTTP headers are received, the closure sets up content decoding by calling ds_get_content_decode() on the "Content-Encoding" or "DataStream-Content-Encoding" header values; when raw chunked data is received, first the chunked body is decoded (if content encoding was indicated in the message headers), then YAML data is deserialized and passed as Qore data to the given callback argument; the return value of this function is design to be used as the receive callback parameter rcb in the following methods:
  • HTTPClient::sendWithRecvCallback()
  • HTTPClient::sendWithCallbacks()
  • Socket::readHTTPChunkedBodyBinaryWithCallback()
  • Socket::readHTTPChunkedBodyWithCallback()
Note
the callback returned here can throw a "DESERIALIZATION-ERROR" if the header's "Content-Type" or "DataStream-Content-Type" is not "text/yaml" or the "Content-Encoding" or "DataStream-Content-Encoding" headers give unrecognized content encodings.
code DataStreamUtil::ds_get_send ( code  scb,
*code  enc_func 
)

returns a call reference useful for sending HTTP chunked data with Qore methods taking send callbacks; data is encoded with YAML and optionally a content encoding call reference or closure

Example:
1 httpclient.sendWithSendCallback(ds_get_send(scb, enc_func), method, path, hdr, timeout_ms, False, \info);
Parameters
scbthe send data callback that should return data for sending
enc_funcan optional call reference or closure for performing content encoding after YAML serialization; see ds_get_content_encode()
Returns
a call reference useful for sending HTTP chunked data with Qore methods taking send callbacks; data is encoded with YAML and optionally a content encoding call reference or closure; the return value of this function is design to be used as the send callback parameter scb in the following methods:
  • HTTPClient::sendWithSendCallback()
  • HTTPClient::sendWithCallbacks()
  • Socket::sendHTTPMessageWithCallback()
  • Socket::sendHTTPResponseWithCallback()
Note
if using content encoding; the appropriate "DataStream-Content-Encoding" header will be added by ds_set_chunked_headers() if the content_encoding argument is used
nothing DataStreamUtil::ds_set_chunked_headers ( reference< hash >  hdr,
*string  content_encoding,
*softbool  req 
)

sets up HTTP headers for DataStream chunked data transfers

Example:
1 ds_set_chunked_headers(\hdr, "bzip");
Parameters
hdra reference to a hash of message headers when sending chunked DataStream data; the following headers are set:
  • "Content-Type: application/octet-stream" (set if header not already present in hash)
  • "DataStream-Content-Type: text/x-yaml;charset=utf8" (set if header not already present in hash)
  • "DataStream-Content-Encoding": set to the content_encoding argument, if present
  • "Transfer-Encoding: chunked"
For requests, the following headers are processed:
  • "Accept: text/x-yaml,application/octet-stream" (set if header not already present in hash)
  • "DataStream-Accept: text/x-yaml" (set if header not already present in hash)
content_encodingan optional string giving the "DataStream-Content-Encoding" header to set (must be a recognized content encoding as recognized by ds_get_content_encode())
reqset to True if the headers are required for a request
nothing DataStreamUtil::ds_set_non_chunked_headers ( reference< hash >  hdr,
*string  content_encoding,
*softbool  req 
)

sets up HTTP headers for DataStream non-chunked data transfers

Example:
1 ds_set_non_chunked_headers(\hdr, "bzip");
Parameters
hdra reference to a hash of message headers when sending chunked DataStream data; the following headers are set:
  • "Content-Type: text/x-yaml" (set if header not already present in hash)
For requests, the following headers are processed:
  • "Accept: text/x-yaml,application/octet-stream" (set if header not already present in hash)
  • "DataStream-Accept: text/x-yaml" (set if header not already present in hash)
content_encodingan optional string giving the "Content-Encoding" header to set (must be a recognized content encoding as recognized by ds_get_content_encode())
reqset to True if the headers are required for a request