Qore HttpServer Module Reference  0.3.8
 All Classes Namespaces Functions Variables Groups Pages
HttpServer::AbstractStreamRequestHandler Class Referenceabstract

abstract class for embedded objects serving streaming requests More...

Public Member Functions

 constructor (hash cx)
 creates the object with the given arguments More...
 
hash getResponseHeaderMessage ()
 this method returns the response message description hash by calling getResponseHeaderMessageImpl() More...
 
abstract hash getResponseHeaderMessageImpl ()
 this method should return the response message description hash More...
 
nothing recv (hash v)
 this method provides the callback method for receiving chunked data by calling recvImpl() More...
 
abstract nothing recvImpl (hash v)
 abstract callback method for receiving chunked data More...
 
any send ()
 this method provides the callback method for sending chunked data by calling sendImpl() More...
 
abstract any sendImpl ()
 abstract callback method for sending chunked data More...
 

Private Attributes

hash cx
 call context hash
 
*hash ex
 if an exception is raised in a callback then the exception hash is saved here
 

Detailed Description

abstract class for embedded objects serving streaming requests

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

HttpServer::AbstractStreamRequestHandler::constructor ( hash  cx)

creates the object with the given arguments

Parameters
cxcall context hash; this hash will have the following keys:
  • 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 Qore::Socket::getSocketInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  • url: a hash of broken-down URL information (as returned from parseURL())
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • user: the current RBAC username (if any)
  • hdr: a hash of header information as returned by Qore::Socket::readHTTPHeader()
  • body: the deserialized message body
  • aih: a hash of "Accept" values
hash HttpServer::AbstractStreamRequestHandler::getResponseHeaderMessage ( )

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

Returns
a 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
abstract hash HttpServer::AbstractStreamRequestHandler::getResponseHeaderMessageImpl ( )
pure virtual

this method should return the response message description hash

Returns
a 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
nothing HttpServer::AbstractStreamRequestHandler::recv ( hash  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)
abstract nothing HttpServer::AbstractStreamRequestHandler::recvImpl ( hash  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)
any HttpServer::AbstractStreamRequestHandler::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
abstract any HttpServer::AbstractStreamRequestHandler::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