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
*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
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
code	ds_get_recv (code recv_callback, code eod_callback, *code body_callback, *bool extern_decode)
	returns a closure useful for receiving HTTP chunked data
nothing	ds_set_chunked_headers (reference< hash< auto > > hdr, *string content_encoding, *softbool req)
	sets up HTTP headers for DataStream chunked data transfers
nothing	ds_set_non_chunked_headers (reference< hash< auto > > hdr, *string content_encoding, *softbool req)
	sets up HTTP headers for DataStream non-chunked data transfers
*string	ds_get_ds_accept_enc_header (*string ae)
	returns the "DataStream-Accept-Encoding" header value or a default value

Variables
const	DataStreamContentType = "DataStream-Content-Type"
	HTTP header for the data stream Content-Type header equivalent where each HTTP chunk is encoded/decoded separately.
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

ds_get_content_decode()

*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:

*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-ERROR

this exception is thrown if the content encoding is not recognized

Note

HTTP headers in requests are converted to lower-case only on receipt

ds_get_content_encode()

*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:

*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-ERROR

this exception is thrown if the content encoding is not recognized

ds_get_ds_accept_enc_header()

*string DataStreamUtil::ds_get_ds_accept_enc_header

(

*string

ae

)

returns the "DataStream-Accept-Encoding" header value or a default value

Example:

string dae = ds_get_ds_accept_enc_header(hdr."Accept-Encoding");

Parameters

ae	the value of the "Accept-Encoding" header

Returns

the "DataStream-Accept-Encoding" value corresponding to the "Accept-Encoding" header passed as an argument; if no value is passed, then the default value "gzip,bzip2,deflate" is returned

ds_get_recv()

code DataStreamUtil::ds_get_recv	(	code	recv_callback,
		code	eod_callback,
		*code	body_callback,
		*bool	extern_decode
	)

returns a closure useful for receiving HTTP chunked data

The closure returned if useful with Qore methods taking receive callbacks; YAML data is deserialized and passed as Qore data to the given argument

Example:

httpclient.sendWithRecvCallback(ds_get_recv(recv_callback), body, method, path, hdr, timeout_ms, False, \info);

Parameters

recv_callback	the 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
eod_callback	the "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
body_callback	an 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
extern_decode	non-DataStream messages will be decoded externally

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 recv_callback 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.

ds_get_send()

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:

httpclient.sendWithSendCallback(ds_get_send(scb, enc_func), method, path, hdr, timeout_ms, False, \info);

Parameters

scb	the send data callback that should return data for sending
enc_func	an 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

ds_set_chunked_headers()

nothing DataStreamUtil::ds_set_chunked_headers	(	reference< hash< auto > >	hdr,
		*string	content_encoding,
		*softbool	req
	)

sets up HTTP headers for DataStream chunked data transfers

Example:

ds_set_chunked_headers(\hdr, "bzip");

Parameters

hdr	a 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_encoding	an optional string giving the "DataStream-Content-Encoding" header to set (must be a recognized content encoding as recognized by ds_get_content_encode())
req	set to True if the headers are required for a request

ds_set_non_chunked_headers()

nothing DataStreamUtil::ds_set_non_chunked_headers	(	reference< hash< auto > >	hdr,
		*string	content_encoding,
		*softbool	req
	)

sets up HTTP headers for DataStream non-chunked data transfers

Example:

ds_set_non_chunked_headers(\hdr, "bzip");

Parameters

hdr	a 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_encoding	an optional string giving the "Content-Encoding" header to set (must be a recognized content encoding as recognized by ds_get_content_encode())
req	set to True if the headers are required for a request