class WebServerDispatcher

Library: OSP/Web
Package: Web
Header: Poco/OSP/Web/WebServerDispatcher.h


A WebServerDispatcher is some sort of meta HTTPRequestHandlerFactory. It groups together several other HTTPRequestHandlerFactory instances and distributes requests to them according to the registered request handler extension points (see the WebServerExtensionPoint class).


Direct Base Classes: Poco::OSP::Service

All Base Classes: Poco::OSP::Service, Poco::RefCountedObject

Member Summary

Member Functions: addCustomResponseHeaders, addFilter, addVirtualPath, authService, authorize, authorizeBasic, authorizeBearer, authorizeSession, cleanPath, findFilter, findResource, formatMessage, getCachedResource, handleRequest, htmlize, isA, jsonize, listVirtualPaths, logRequest, mapPath, normalizePath, onBundleStopping, parseAuthMethods, removeBundle, removeFilter, removeVirtualPath, sendBadRequest, sendForbidden, sendFound, sendHTMLResponse, sendInternalError, sendJSONResponse, sendMethodNotAllowed, sendNotAuthorized, sendNotFound, sendResource, sendResponse, sessionManager, shouldCompressMediaType, threadPool, tokenValidator, type, uncacheBundleResources, virtualPathMappings

Inherited Functions: duplicate, isA, referenceCount, release, type

Nested Classes

struct Config


struct PathInfo


struct PathSecurity

Security attributes for a registered path. more...

struct VirtualPath

A VirtualPath struct is used to specify a path mapping for a bundle. more...



typedef std::map < std::string, PathInfo > PathInfoMap;


typedef std::map < std::string, VirtualPath > PathMap;


typedef std::vector < VirtualPath > PatternVec;


typedef Poco::SharedPtr < Poco::RegularExpression > RegularExpressionPtr;


typedef Poco::SharedPtr < Poco::Net::HTTPRequestHandlerFactory > RequestHandlerFactoryPtr;


typedef Poco::SharedPtr < WebFilterFactory > WebFilterFactoryPtr;


typedef Poco::SharedPtr < WebFilter > WebFilterPtr;




HTTP Basic authentication


Session-based authentication


Bearer token-based authentication (OAuth 2.0)




Compress responses using gzip content encoding.


Enable in-memory caching of bundle resources.


Add X-OSP-Authorized-User header to authenticated requests.


Add server signature to generated HTML error responses.


A bundle that registers a resource mapping or request handler for a certain path can specify whether other bundles can register subdirectories of this directory.


No one can register subdirectories


Only the owner bundle can register subdirectories

SM_ALL = 2

Everyone can register subdirectories



explicit WebServerDispatcher(
    const Config & config

Creates the WebServerDispatcher.


~WebServerDispatcher virtual

virtual ~WebServerDispatcher();

Destroys the WebServerDispatcher.

Member Functions


void addFilter(
    const std::string & mediaType,
    WebFilterFactoryPtr pFilterFactory,
    const WebFilter::Args & args

Adds a filter factory for the given media type.

Throws a Poco::ExistsException if a filter already exists for the given mediaType.


void addVirtualPath(
    const VirtualPath & virtualPath

Adds the given VirtualPath to the path mapping table.

Throws an ExistsException if a mapping for the given path already exists.


void handleRequest(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPServerResponse & response,
    bool secure

Handles the given request. Secure specifies whether the request has been sent over a secure (HTTPS) connection.

isA virtual

virtual bool isA(
    const std::type_info & otherType
) const;


void listVirtualPaths(
    PathInfoMap & paths
) const;

Returns a map containing all virtual paths (key) that are not patterns and not marked as hidden, and their descriptions (value).

parseAuthMethods static

static int parseAuthMethods(
    const std::string & methods

Parses a comma-separated list of authentication method names and returns a value with the corresponding AuthMethod flags set.


void removeBundle(
    Bundle::ConstPtr pBundle

Removes all mappings from the given bundle.


void removeFilter(
    const std::string & mediaType

Removes the filter for the given mediaType.


void removeVirtualPath(
    const std::string & virtualPath

Removes a path mapping from the path mapping table.

Throws a NotFoundException if the given path does not exist.

threadPool inline

Poco::ThreadPool & threadPool();

Returns the thread pool for use by Poco::Net::HTTPServer.

type virtual

virtual const std::type_info & type() const;


void uncacheBundleResources(
    Bundle::ConstPtr pBundle

Removes all cached resources from the given bundle form the cache.


void virtualPathMappings(
    PathMap & mappings
) const;

Returns all path mappings. This member function creates a full copy of the internal path map.

addCustomResponseHeaders protected

void addCustomResponseHeaders(
    Poco::Net::HTTPServerResponse & response

Adds any configured custom response headers.

authService protected

Poco::OSP::Auth::AuthService::Ptr authService() const;

Returns a pointer to the auth service, if it is available, or null otherwise.

authorize protected

bool authorize(
    Poco::Net::HTTPServerRequest & request,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request.

authorizeBasic protected

bool authorizeBasic(
    Poco::Net::HTTPServerRequest & request,
    const std::string & creds,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request using a HTTP Basic Authentication.

authorizeBearer protected

bool authorizeBearer(
    Poco::Net::HTTPServerRequest & request,
    const std::string & token,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request using bearer token-based authentication.

authorizeSession protected

bool authorizeSession(
    Poco::Net::HTTPServerRequest & request,
    const VirtualPath & vPath,
    std::string & username
) const;

Authorizes the request using a session-based authentication.

cleanPath protected static

static bool cleanPath(
    std::string & path

Removes unnecessary characters (such as trailing dots) from the path and checks for illegal or dangerous characters.

Returns true if the path is okay, false otherwise.

findFilter protected

WebFilterPtr findFilter(
    const std::string & mediaType

Returns a WebFilter instance for the given mediaType, or a null pointer if no WebFilterFactory has been registered for the given mediaType.

findResource protected

std::istream * findResource(
    Bundle::ConstPtr pBundle,
    const std::string & base,
    const std::string & res,
    const std::string & index,
    std::string & mediaType,
    std::string & resolvedPath,
    bool canCache
) const;

Returns a resource stream for the given path, or a null pointer if no matching resource exists.

formatMessage protected

std::string formatMessage(
    const std::string & messageId,
    const std::string & arg1 = std::string (),
    const std::string & arg2 = std::string ()

Reads a message from the bundle.properties resource and replaces placeholders $1 and $2 with arg1 and arg2, respectively.

getCachedResource protected

std::istream * getCachedResource(
    Bundle::ConstPtr pBundle,
    const std::string & path,
    bool canCache
) const;

Returns a resource stream for the given path, or a null pointer if no matching resource exists. If caching is enabled both globally and for the specific resource, attempts to cache the resource.

htmlize protected static

static std::string htmlize(
    const std::string & str

Returns a HTML-ized version of the given string.

jsonize protected static

static std::string jsonize(
    const std::string & str

Returns a JSON-ized (escaped) version of the given string.

logRequest protected

void logRequest(
    const Poco::Net::HTTPServerRequest & request,
    const Poco::Net::HTTPServerResponse & response,
    const std::string & username

Logs the HTTP request.

mapPath protected

const VirtualPath & mapPath(
    const std::string & path,
    const std::string & method
) const;

Maps a URI to a VirtualPath.

Throws a NotFoundException if no suitable mapping can be found.

normalizePath protected static

static std::string normalizePath(
    const std::string & path

Creates normalized path for internal storage. The normalized path always starts and ends with a slash.

onBundleStopping protected

void onBundleStopping(
    const void * pSender,
    BundleEvent & ev

When a bundle is stopped, all of its request handlers and mappings are automatically disabled.

sendBadRequest protected

void sendBadRequest(
    Poco::Net::HTTPServerRequest & request,
    const std::string & message

Sends a 404 Not Found error response.

sendForbidden protected

void sendForbidden(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path

Sends a 403 Forbidden error response.

sendFound protected

void sendFound(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path

Sends a 302 Found response.

sendHTMLResponse protected

void sendHTMLResponse(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPResponse::HTTPStatus status,
    const std::string & message

Sends a standard status/error response in HTML format.

sendInternalError protected

void sendInternalError(
    Poco::Net::HTTPServerRequest & request,
    const std::string & message

Sends a 500 Internal Server Error response.

sendJSONResponse protected

void sendJSONResponse(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPResponse::HTTPStatus status,
    const std::string & message

Sends a standard status/error response in JSON format.

sendMethodNotAllowed protected

void sendMethodNotAllowed(
    Poco::Net::HTTPServerRequest & request,
    const std::string & message

Sends a 405 Method Not Allowed error response.

sendNotAuthorized protected

void sendNotAuthorized(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path

Sends a 401 Unauthorized error response.

sendNotFound protected

void sendNotFound(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path

Sends a 404 Not Found error response.

sendResource protected

void sendResource(
    Poco::Net::HTTPServerRequest & request,
    const std::string & path,
    const std::string & vpath,
    const std::string & resPath,
    const std::string & resBase,
    const std::string & index,
    Bundle::ConstPtr pBundle,
    bool canCache

Sends a bundle resource as response.

sendResponse protected

void sendResponse(
    Poco::Net::HTTPServerRequest & request,
    Poco::Net::HTTPResponse::HTTPStatus status,
    const std::string & message

Sends a standard status/error response.

sessionManager protected

WebSessionManager::Ptr sessionManager() const;

Returns a pointer to the WebSessionManager.

shouldCompressMediaType protected

bool shouldCompressMediaType(
    const std::string & mediaType
) const;

Returns true if and only if content with the given media type should be compressed.

tokenValidator protected

TokenValidator::Ptr tokenValidator() const;

Returns a pointer to the token validator, if it is available, or null otherwise.



static const std::string SERVICE_NAME;

BEARER protected static

static const std::string BEARER;

X_OSP_AUTHORIZED_USER protected static

static const std::string X_OSP_AUTHORIZED_USER;

Securely control IoT edge devices from anywhere   Connect a Device