Nuria::HttpNode Class Reference

Virtual directory for HttpServer. More...

#include <httpnode.hpp>

Inheritance diagram for Nuria::HttpNode:

Public Types
enum	StaticResourcesMode { NoStaticResources = 0, UseStaticResources = 1, UseNestedStaticResources = 2 }

Public Member Functions
	HttpNode (const QString &resourceName, HttpNode *parent=0)
	HttpNode (QObject *parent=0)
	~HttpNode ()
bool	addNode (HttpNode *node)
SlotInfo	connectSlot (const QString &name, const Callback &callback)
SlotInfo	connectSlot (const QString &name, QObject *receiver, const char *slot)
bool	disconnectSlot (const QString &name)
bool	isChild () const
HttpNode *	parentNode () const
const QString &	resourceName () const
const QDir &	staticResourceDir () const
StaticResourcesMode	staticResourceMode () const

is a empty string.
Sets the resource name of this node. If this node is a subnode, the call fails if there is already a node with this name or if
class	HttpServer
class	HttpClient
bool	setResourceName (const QString &name)
void	setStaticResourceDir (QDir path)
void	setStaticResourceMode (StaticResourcesMode mode)
bool	hasNode (const QString &name)
bool	hasSlot (const QString &name)
HttpNode *	findNode (const QString &name) const
virtual bool	invokePath (const QString &path, const QStringList &parts, int index, HttpClient *client)
virtual bool	allowAccessToClient (const QString &path, const QStringList &parts, int index, HttpClient *client)
virtual bool	callSlotByName (const QString &name, HttpClient *client)
bool	sendStaticResource (const QString &name, HttpClient *client)
bool	sendStaticResource (const QStringList &path, int indexInPath, HttpClient *client)

Detailed Description

Virtual directory for HttpServer.

A node is the equivalent to a directory of other HTTP servers and provides a hierarchical system to manage resources. They may contain other nodes or slots, all of which are named.

Slots may be invokable Callback's or static files.

Usage

To add a node as child node, just call addNode(). This will make the node available to HTTP requests. If you want to invoke a C++ function when a certain path was requested, use connectSlot(), which accepts a Nuria::Callback and will work with any callback of this sort.

Note

Slots are only invoked if it's the last element in the requested path.

For example, if you have a slot called "foo", it will only be called, if "foo" is at the end of the path, like "/stuff/foo". It won't be invoked if the request path would be "/foo/stuff".

Note

It's possible to have a child node and a slot with the same name in a single HttpNode instance.

It's also possible to easily serve static files from the file-system. See setStaticResourceDir() and setStaticResourceMode() for more information.

How a path is invoked

Nodes are hierarchical, meaning you can put nodes into other nodes to build paths. When a HTTP request was made and the request header has been parsed, the HttpClient instance will try to "invoke" the path. It does this by calling invokePath() on the HttpServer's root node. The root node will, in the default implementation, look for a matching slot if it's at the last part of the path, or else, try to find a child node with a matching name, which if found will be invoked recursively.

Other HttpNode implementations may change this behaviour significantly by re-implementing invokePath(). RestfulHttpNode is a good example, which allows to write RESTful services easily by parsing the requested path for variables passed to the call.

Advanced usage

It can happen that the default HttpNode doesn't satisfy your needs. In this case you can subclass HttpNode and reimplement one of the protected virtual methods.

If all you want to do is session management, re-implement allowAccessToClient(). Want to enhance HttpNode's slot invocation mechanism? Re-implement callSlotByName(). And if you want to have as much control over everything as possible, you can also re-implement invokePath(). Please bear in mind that doing this is more complex as it involves checking for permissions, finding a slot to be called and handing the request over to another HttpNode for processing.

Please note that if you want to use clients in a non-streamed fashion (Which is the default), that you'll need to create a SlotInfo for each method and use HttpClient::setSlotInfo to assign one to any client.

See also

HttpServer invokePath

Member Enumeration Documentation

enum Nuria::HttpNode::StaticResourcesMode

This enum describes the mode of static resource handling in a node. The default is NoStaticResources.

Enumerator
NoStaticResources	No static resources will be served by this node.
UseStaticResources	This node will serve static resources, but won't go deeper in the directory hierarchy after the the set resource directory.
UseNestedStaticResources	This node will server static resources and will follow the directory hierarchy.

Constructor & Destructor Documentation

Nuria::HttpNode::HttpNode	(	const QString &	resourceName,
		HttpNode *	parent = 0
	)

Constructs a node. If parent points to a HttpNode, this node will be added to parent. You can check if this was successful by calling isChild().

Nuria::HttpNode::HttpNode

(

QObject *

parent = 0

)

Constructs a node.

Nuria::HttpNode::~HttpNode

(

)

Destructor.

Member Function Documentation

bool Nuria::HttpNode::addNode

(

HttpNode *

node

)

Adds a subnode to this node. Returns true on success. If there is already a node with the same resource name of node, node is 0 or node doesn't have a resource name the call will fail and return false. The call succeeds if node is already a subnode of this node. On success node will be reparented.

virtual bool Nuria::HttpNode::allowAccessToClient ( const QString &  path, const QStringList &  parts, int  index, HttpClient *  client  )

protectedvirtual

This method is used by invokePath() to check if client is allowed to access the resource as specified by path or by parts and index (As they're used in invokePath()). If access is not granted, you may use HttpClient::killConnection() to use a custom status code. If you don't do this and disallow access, then the client will receive a 403 (Forbidden) reply.

If access is allowed, this method must not send data to the client. This is the job of invokePath().

The default implementation always returns true.

Note

This method is not here to check if the path actually exists! Its purpose is to check whether or not the client is allowed to go through the current HttpNode.

As this method is called for every HttpNode the request recurses to, make sure to not do expensive calculations. If you need to do this, consider caching the result. This can be easily done by e.g. doing: client->setProperty("accessGranted", true);

Returns

true if the access should be allowed, otherwise false.

virtual bool Nuria::HttpNode::callSlotByName ( const QString &  name, HttpClient *  client  )

protectedvirtual

Used by HttpServer::invokeByPath to invoke a slot. Returns true if the slot has been found. This does not indicate a failure while calling. Only return false if the slot name has not been found.

Note

When this method is reached, allowAccessToClient has already been called.

SlotInfo Nuria::HttpNode::connectSlot	(	const QString &	name,
		const Callback &	callback
	)

Connects a slot to this resource. The slot is callable by requesting <ip or="" domain="" of="" server>="">/<resource path>="">/<name>. Returns a SlotInfo instance on success. The call fails if either name is already a registered slot or node or callback is invalid. In this case 0 is returned.

If you want to deliver static resource files take a look at setStaticResourceDir.

See also

SlotInfo setStaticResourceDir

Note

The prototype for a slot is void method (HttpClient *client); where client points to the connected client.

The slot 'index' is called when the user attempts to access this node directly.

SlotInfo Nuria::HttpNode::connectSlot	(	const QString &	name,
		QObject *	receiver,
		const char *	slot
	)

Connects a slot to this resource. The slot is callable by requesting <ip or="" domain="" of="" server>="">/<resource path>="">/<name>. Returns a SlotInfo instance on success. The call fails if either name is already a registered slot or node, receiver is 0 or slot points to a non-existing slot. In this case 0 is returned.

If you want to deliver static resource files take a look at setStaticResourceDir.

See also

SlotInfo setStaticResourceDir

Note

The prototype for a slot is void method (HttpClient *client); where client points to the connected client.

The slot 'index' is called when the user attempts to access this node directly.

bool Nuria::HttpNode::disconnectSlot

(

const QString &

name

)

Disconnects the slot name. If there was a slot with this name true is returned. On failure false is returned.

HttpNode* Nuria::HttpNode::findNode

(

const QString &

name

)

const

Looks for a node name and returns it if found. Returns 0 if there is no subnode with this name.

bool Nuria::HttpNode::hasNode

(

const QString &

name

)

Returns true if this node has a subnode called name.

bool Nuria::HttpNode::hasSlot

(

const QString &

name

)

Returns true if this node has a slot called name.

virtual bool Nuria::HttpNode::invokePath ( const QString &  path, const QStringList &  parts, int  index, HttpClient *  client  )

protectedvirtual

Recurses into the HttpNode structure to invoke the requested slot. The default implementation checks for the following:

• First it tries to find a matching node. If it finds one it calls invokePath() on it.
• If that fails it tries to call a slot with the name if index points to the last item in parts.
• Last it tries to deliver a static resource file.
• When everything fails it returns false.

If you need a more flexible approach than the default node/slot mechanism, subclass HttpNode and reimplement this method. Please note that if you're looking for a way to have session management, you can also re-implement allowAccessToClient() which was designed for this purpose.

Note

Consider re-implementing callSlotByName() instead, as implementing invokePath() can be a complex task.

If index is equal to parts.length() the user requested the index page of this node.

Warning

Special case: If index is 0 and parts is empty, the client requested the index page of the server (E.g. http://example.com/).

Parameters

path	The complete path as requested by the user
parts	The path split by '/'. Empty parts are ignored.
index	The current index in parts.
client	The client.

Returns

true on success, otherwise false.

See also

callSlotByName addNode connectSlot

Reimplemented in Nuria::RestfulHttpNode.

bool Nuria::HttpNode::isChild

(

)

const

Returns true when this node has a valid parent node.

HttpNode* Nuria::HttpNode::parentNode

(

)

const

Returns the parent node this node is associated to. If this node has no parent, 0 is returned.

const QString& Nuria::HttpNode::resourceName

(

)

const

Returns the resource name of this node.

bool Nuria::HttpNode::sendStaticResource ( const QString &  name, HttpClient *  client  )

protected

Tries to send a static resource file named name. If no static resource directory is set this method returns false immediately. If a resource file has been found, it will be opened by QFile and pipe()'d back to the client. In this case true is returned.

Note

This method supports range requests.

bool Nuria::HttpNode::sendStaticResource ( const QStringList &  path, int  indexInPath, HttpClient *  client  )

protected

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Nuria::HttpNode::setStaticResourceDir

(

QDir

path

)

Sets the directory which hosts static resources like images. If a client requests a resource which is not a slot it will be searched for in path. The default is an invalid path, which points at no directory. If the current staticResourceMode is NoStaticResources it will be changed to UseStaticResources.

Note

The index file is called "index.html"

void Nuria::HttpNode::setStaticResourceMode

(

StaticResourcesMode

mode

)

Sets the static resource mode.

See also

setStaticResourceDir StaticResourcesMode

const QDir& Nuria::HttpNode::staticResourceDir

(

)

const

Returns the static resource file directory of this node.

StaticResourcesMode Nuria::HttpNode::staticResourceMode

(

)

const

Returns the current static resource mode.

---

The documentation for this class was generated from the following file:

• httpnode.hpp