Qore RestHandler Module Reference 1.6.2
Loading...
Searching...
No Matches
RestHandler::AbstractRestStreamRequestHandler Class Referenceabstract

the base abstract class for REST stream request handlers More...

#include <RestHandler.qm.dox.h>

Public Member Methods

 constructor (hash< auto > cx, *hash< auto > ah)
 creates the object with the given arguments More...
 
*code getPersistentClosedNotification ()
 returns a callable value in case a persistent connection is in progress; NOTHING if not; this method in the base class returns NOTHING
 
hash< HttpServer::HttpHandlerResponseInfogetResponseHeaderMessage ()
 this method returns the response message description hash by calling getResponseHeaderMessageImpl() More...
 
abstract hash< auto > getResponseHeaderMessageImpl ()
 this method should return the response message description hash More...
 
*int getTimeout ()
 returns the timeout in milliseconds or NOTHING if no timeout is set
 
bool isPersistent ()
 returns True if the connection is persistent; this method in the base class returns False by default
 
nothing recv (hash< auto > v)
 this method provides the callback method for receiving chunked data by calling recvImpl() More...
 
abstract nothing recvImpl (hash< auto > v)
 abstract callback method for receiving chunked data More...
 
auto send ()
 this method provides the callback method for sending chunked data by calling sendImpl() More...
 
abstract auto sendImpl ()
 abstract callback method for sending chunked data More...
 
 setTimeout (timeout n_timeout_ms)
 sets the internal socket I/O timeout value in ms
 
 streamError (hash< auto > n_ex)
 registers stream errors in the send operation with the stream handler if no error is already present
 

Private Attributes

*hash< auto > ah
 call argument hash
 
hash< auto > cx
 call context hash
 
*hash< auto > ex
 if an exception is raised in a callback then the exception hash is saved here
 
hash< auto > rhdr
 headers to add in the response
 
*int timeout_ms
 socket I/O timeout in milliseconds
 

Detailed Description

the base abstract class for REST stream request handlers

The calling order is as follows:

  • constructor(): this is called when the request is received; then context argument contains the request header along with other information
  • recv(): this is called once for each HTTP chunk (if data is sent chunked), and then once with any message trailer. If data is sent non-chunked, then this method is called with the monolithic message body and then again with NOTHING to signify the end of the transfer and to simulate a chunked transfer. Subclasses should re-implement recvImpl() which is called by this method
  • getResponseHeaderMessage(): this is called after the message body has been received to get the response headers and optionally a message body. Subclasses should reimplement getResponseHeaderMessageImpl() which is called by this method
  • send(): this is called if no message body is returned by getResponseHeaderMessage(); each time this method returns data, the data is sent in a response chunk; when this method returns NOTHING, then no more data is sent. Subclasses should re-implement sendImpl() which is called by this method

Member Function Documentation

◆ constructor()

RestHandler::AbstractRestStreamRequestHandler::constructor ( hash< auto >  cx,
*hash< auto >  ah 
)

creates the object with the given arguments

Parameters
cxcall context hash; this hash will have the following keys:
  • aih: a hash of "Accept" values, keys are hash values, values are boolean True
  • body: the deserialized message body
  • hdr: a hash of header information as returned by Socket::readHTTPHeader()
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
  • socket: the bind address used to bind the listener ("socket-info" provides more detailed information)
  • socket-info: a hash of socket information for the listening socket (as returned by Socket::getSocketInfo())
  • ssl: True if the request was encrypted with HTTPS, False if not
  • url: a hash of broken-down URL information (as returned from parse_url())
  • user: the current authorized username (if any)
ahany URI arguments in the request

◆ getResponseHeaderMessage()

hash< HttpServer::HttpHandlerResponseInfo > RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage ( )

this method returns the response message description hash by calling getResponseHeaderMessageImpl()

Returns
a HttpHandlerResponseInfo hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response; if this key is returned, then the reply is sent immediately; a chunked reply is not made, and send() and sendImpl() are not called
  • "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
  • "hdr": (optional) set this key to a hash of extra header information to be returned with the response
Note
this method is called after the message body has been received

◆ getResponseHeaderMessageImpl()

abstract hash< auto > RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessageImpl ( )
pure virtual

this method should return the response message description hash

Returns
an HttpServer::HttpHandlerResponseInfo hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response; if this key is returned, then the reply is sent immediately; a chunked reply is not made, and send() and sendImpl() are not called
  • "close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
  • "hdr": (optional) set this key to a hash of extra header information to be returned with the response
Note
this method is called after the message body has been received

◆ recv()

nothing RestHandler::AbstractRestStreamRequestHandler::recv ( hash< auto >  v)

this method provides the callback method for receiving chunked data by calling recvImpl()

Parameters
vthe first time this method is called with a hash of the message headers in the "hdr" key, and then with any message body in the "data"; if a chunked HTTP message is received, then this method is called once for each chunk; when the message has been received, then this method 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, or, in the case of a non-chunked request, the already decoded and deserialized request body, in which case the "deserialized" key will be True
  • "chunked": True if the data was received with chunked transfer encoding, False if not
  • "deserialized": present and set to True if a non-chunked request was received, and the body has already been deserialized
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)

◆ recvImpl()

abstract nothing RestHandler::AbstractRestStreamRequestHandler::recvImpl ( hash< auto >  v)
pure virtual

abstract callback method for receiving chunked data

Parameters
vthe first time this method is called with a hash of the message headers in the "hdr" key, and then with any message body in the "data"; if a chunked HTTP message is received, then this method is called once for each chunk; when the message has been received, then this method 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, or, in the case of a non-chunked request, the already decoded and deserialized request body, in which case the "deserialized" key will be True
  • "chunked": True if the data was received with chunked transfer encoding, False if not
  • "deserialized": present and set to True if a non-chunked request was received, and the body has already been deserialized
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)

◆ send()

auto RestHandler::AbstractRestStreamRequestHandler::send ( )

this method provides the callback method for sending chunked data by calling sendImpl()

Returns
The chunked HTTP data to send; this method 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 returned or simply NOTHING which will close the chunked message

◆ sendImpl()

abstract auto RestHandler::AbstractRestStreamRequestHandler::sendImpl ( )
pure virtual

abstract callback method for sending chunked data

Returns
The chunked HTTP data to send; this method 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 returned or simply NOTHING which will close the chunked message