HttpServer::AbstractHttpSocketHandlerInterface Class Reference

Abstract class for HTTP handlers for handling protocol switching. More...

#include <HttpServerUtil.qm.dox.h>

Inheritance diagram for HttpServer::AbstractHttpSocketHandlerInterface:

Public Member Methods
code	setExternallyManaged (softstring lid, hash< auto > cx, Socket s)
	Returns a closure that can be used to confirm that the connection has been closed.
bool	start (softstring lid, hash< auto > cx, hash< auto > hdr, Socket s)
	called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established
	stop ()
	called from the HTTP server when the socket should be closed due to an external request
	stop (softstring lid)
	called from the HTTP server when the socket should be closed due to an HTTP listener being stopped

Private Member Methods
	handlerStopped (softstring lid)
	Called when the handler stops.
Mutex	m ()
	listener reference hash mutex
abstract bool	startImpl (softstring lid, hash< auto > cx, hash< auto > hdr, Socket s)
	called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established
	stopImpl ()
	called from the HTTP server when the socket should be closed due to an external request
	stopImpl (string lid)
	called from the HTTP server when the socket should be closed because the listener is stopping

Private Attributes
hash< string, int >	lh
	hash of listener references; this is to stop all connections associated with a particular listener
hash< string, bool >	lsh
	hash of listener stop flags
bool	stop = False
	stop listener flag

Detailed Description

Abstract class for HTTP handlers for handling protocol switching.

To accept a new dedicated socket connection, make sure the return value of the handleRequest() method returns code 101 (ie Switching Protocols); after which this class's start() and then startImpl() methods are called.

To accept a dedicated socket connection, handleRequest() must return a hash (ideally an HttpServer::HttpResponseInfo hash) with the following keys:

• "code": assign to 101 (ie "Switching Protocols"); if this is returned, then the start() method will be called with the Socket object for the new connection
• "hdr": (optional) set this key to a hash of extra header information to be returned with the response
  or, to handle the request without a dedicated connection, return a hash with the following keys:
• "code": the HTTP return code (see HttpServer::HttpCodes)
• "body": the message body to return in the response
• "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

Member Function Documentation

start()

bool HttpServer::AbstractHttpSocketHandlerInterface::start	(	softstring	lid,
		hash< auto >	cx,
		hash< auto >	hdr,
		Socket	s
	)

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() method is called

Parameters

lid	the listener ID
cx	the call context hash; see HttpServerUtil Request Context for information about this value
hdr	a hash of headers in the request
s	the Socket object for the dedicated connection

Returns

True if externally managed

startImpl()

abstract bool HttpServer::AbstractHttpSocketHandlerInterface::startImpl ( softstring  lid, hash< auto >  cx, hash< auto >  hdr, Socket  s  )

private

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() (and therefore stopImpl()) method is called

Parameters

lid	the listener ID
cx	the call context hash; see HttpServerUtil Request Context for information about this value
hdr	a hash of headers in the request
s	the Socket object for the dedicated connection

Returns

True if externally managed

stop() [1/2]

HttpServer::AbstractHttpSocketHandlerInterface::stop

(

)

called from the HTTP server when the socket should be closed due to an external request

The start() method should return as soon as possible after this method is called

Child classes should implement the stopImpl() method which is called from this method to implement custom stop actions.

stop() [2/2]

HttpServer::AbstractHttpSocketHandlerInterface::stop

(

softstring

lid

)

called from the HTTP server when the socket should be closed due to an HTTP listener being stopped

The start() method for all connections on the particular listener should return as soon as possible after this method is called.

Child classes should implement the stopImpl(string) method which is called from this method to implement custom stop actions for particular listeners.

Parameters

lid	the listener ID

stopImpl() [1/2]

HttpServer::AbstractHttpSocketHandlerInterface::stopImpl ( )

private

called from the HTTP server when the socket should be closed due to an external request

The start() method should return as soon as possible after this method is called

stopImpl() [2/2]

HttpServer::AbstractHttpSocketHandlerInterface::stopImpl ( string  lid )

private

called from the HTTP server when the socket should be closed because the listener is stopping

The start() method for all connections handled by the given listener should return as soon as possible after this method is called

Parameters

lid	the listener ID