This class is used to glue between member function of application class and urls. More...

#include <cppcms/url_dispatcher.h>

Inheritance diagram for cppcms::url_dispatcher:

Public Types
typedef booster::function< bool(cppcms::application &, booster::cmatch const &)>	generic_handler
	RESTful API Handler that validates parameters and executes a method. More...

typedef booster::function< void()>	handler

typedef booster::function< void(booster::cmatch const &)>	rhandler

typedef booster::function< void(std::string)>	handler1

typedef booster::function< void(std::string, std::string)>	handler2

typedef booster::function< void(std::string, std::string, std::string)>	handler3

typedef booster::function< void(std::string, std::string, std::string, std::string)>	handler4

typedef booster::function< void(std::string, std::string, std::string, std::string, std::string)>	handler5

typedef booster::function< void(std::string, std::string, std::string, std::string, std::string, std::string)>	handler6

Public Member Functions
void	map_generic (std::string const &method, booster::regex const &re, generic_handler const &h)

void	map_generic (booster::regex const &re, generic_handler const &h)

template<typename Application , typename... ApplicationMemberArgs>
void	map (std::string const &method, std::string const &re, void(Application::member)(ApplicationMemberArgs...), Application app, int...groups)
	Map member of app as a URL handler that matches regualr expression re and HTTP method method. More...

template<typename Application , typename... ApplicationMemberArgs>
void	map (std::string const &re, void(Application::member)(ApplicationMemberArgs...), Application app, int...groups)
	Map member of app as a URL handler that matches regualr expression re. More...

template<typename Application , typename... ApplicationMemberArgs>
void	map (std::string const &method, booster::regex const &re, void(Application::member)(ApplicationMemberArgs...), Application app, int...groups)
	Map member of app as a URL handler that matches regualr expression re and HTTP method method. More...

template<typename Application , typename... ApplicationMemberArgs>
void	map (booster::regex const &re, void(Application::member)(ApplicationMemberArgs...), Application app, int...groups)
	Map member of app as a URL handler that matches regualr expression re. More...

void	assign_generic (std::string const &regex, rhandler handler)

void	assign (std::string const &regex, handler handler)

void	assign (std::string const &regex, handler1 handler, int exp1)

void	assign (std::string const &regex, handler2 handler, int exp1, int exp2)

void	assign (std::string const &regex, handler3 handler, int exp1, int exp2, int exp3)

void	assign (std::string const &regex, handler4 handler, int exp1, int exp2, int exp3, int exp4)

void	assign (std::string const &regex, handler5 handler, int exp1, int exp2, int exp3, int exp4, int exp5)

void	assign (std::string const &regex, handler6 handler, int exp1, int exp2, int exp3, int exp4, int exp5, int exp6)

bool	dispatch (std::string url)

template<typename C >
void	assign (std::string const &regex, void(C::member)(), C object)

template<typename C >
void	assign_generic (std::string const &regex, void(C::member)(booster::cmatch const &), C object)

template<typename C >
void	assign (std::string const &regex, void(C::member)(std::string), C object, int e1)

template<typename C >
void	assign (std::string const &regex, void(C::member)(std::string, std::string), C object, int e1, int e2)

template<typename C >
void	assign (std::string const &regex, void(C::member)(std::string, std::string, std::string), C object, int e1, int e2, int e3)

template<typename C >
void	assign (std::string const &regex, void(C::member)(std::string, std::string, std::string, std::string), C object, int e1, int e2, int e3, int e4)

template<typename C >
void	assign (std::string const &regex, void(C::member)(std::string, std::string, std::string, std::string, std::string), C object, int e1, int e2, int e3, int e4, int e5)

template<typename C >
void	assign (std::string const &regex, void(C::member)(std::string, std::string, std::string, std::string, std::string, std::string), C object, int e1, int e2, int e3, int e4, int e5, int e6)

void	mount (std::string const &match, application &app, int part)

Detailed Description

This class is used to glue between member function of application class and urls.

This class is used in context of cppcms::application with its url member function. It uses regular expression to bind between url and callbacks that actually process the request. It also allows mount sub-applications to the root of the primary application.

There are two families of functions, assign and map. Older assign interface allows matching only URL against regular expression. and passes std::string as parameter. All the validation must be performed by regular expression or the code that was called.

Newer map interface allows both matching an URL and an HTTP request method. Parameters are parsed using bool parse_url_parameter(util::const_char_istream &parameter,Type &param) that by default uses std::istream to perform casting.

Additionally every matched parameter is checked to contain valid text encoding

Newer API uses map member functions family that was introduced in CppCMS 1.1.

For example:

class my_web_project : public cppcms::application {
    users_app users_;
    /* Older Handlers */
    void display_page(std::string)
     ...
    /* Newer CppCMS 1.1 handlers */
    void get_resource(int id);
    void update_resource(int id);
    void new_resource();
    void id_by_name(std::string const &name); /* name checked for valid encoding */
    void display_page_by_id(int id)
public:
   my_web_project() {
    /* Older API */
    dispatcher().assign("/page/(\\d+)/?",&my_web_project::display_page,this,1);
    /* New API - CppCMS 1.1 and above */
    dispatcher().map("GET","/resource/(\\d+)",&my_web_project::get_resource,this,1);
    dispatcher().map("PUT","/resource/(\\d+)",&my_web_project::update_resource,this,1);
    dispatcher().map("POST","/resources",&my_web_project::new_resource,this);
    dispatcher().map("GET"."/id_by_name/(.*)",&my_web_project::id_by_name,this,1);
    dispatcher().map("/page/(\\d+)",&my_web_project::display_page_by_id,this,1); /* any method */
    ...

Member Typedef Documentation

typedef booster::function<bool(cppcms::application &,booster::cmatch const &)> cppcms::url_dispatcher::generic_handler

RESTful API Handler that validates parameters and executes a method.

If validation fails it should return false and thus the matching would continue to next handler

New in CppCMS 1.2

Member Function Documentation

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler	handler
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler1	handler,
		int	exp1
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with first parameters the string that was matched at position exp1.

For example: if regular expression is "^/page/(\\d+)/(\\w+)$" , exp1=2, and the url is "/page/13/to_be_or_not", then handler would be called with "to_be_or_not" as its first parameter

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler2	handler,
		int	exp1,
		int	exp2
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with 1st and 2nd parameters the string that was matched at position exp1 and exp2

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler3	handler,
		int	exp1,
		int	exp2,
		int	exp3
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with 1st, 2nd and 3rd parameters the string that was matched at position exp1, exp2 and exp2

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler4	handler,
		int	exp1,
		int	exp2,
		int	exp3,
		int	exp4
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with 1st, 2nd, 3rd and 4th parameters the string that was matched at position exp1, exp2, exp3 and exp4

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler5	handler,
		int	exp1,
		int	exp2,
		int	exp3,
		int	exp4,
		int	exp5
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with 1st, 2nd, 3rd, 4th and 5th parameters the string that was matched at position exp1, exp2, exp3, exp4 and exp5

New in CppCMS 1.2

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		handler6	handler,
		int	exp1,
		int	exp2,
		int	exp3,
		int	exp4,
		int	exp5,
		int	exp6
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with 1st, 2nd, 3rd, 4th, 5th and 6th parameters the string that was matched at position exp1, exp2, exp3, exp4, exp 5 and exp6

New in CppCMS 1.2

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)()	member,
		C *	object
	)

inline

This template function is a shortcut to assign(regex,callback). It allows assignment of member function of an object with signature void handler() as simple as assign(expr,&bar::foo,this);

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)(std::string)	member,
		C *	object,
		int	e1
	)

inline

This template function is a shortcut to assign(regex,callback,int). It allows assignment of member function of an object with signature void handler(string)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)(std::string, std::string)	member,
		C *	object,
		int	e1,
		int	e2
	)

inline

This template function is a shortcut to assign(regex,callback,int,int). It allows assignment of member function of an object with signature void handler(string,string)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)(std::string, std::string, std::string)	member,
		C *	object,
		int	e1,
		int	e2,
		int	e3
	)

inline

This template function is a shortcut to assign(regex,callback,int,int,int). It allows assignment of member function of an object with signature void handler(string,string,string)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)(std::string, std::string, std::string, std::string)	member,
		C *	object,
		int	e1,
		int	e2,
		int	e3,
		int	e4
	)

inline

This template function is a shortcut to assign(regex,callback,int,int,int,int). It allows assignment of member function of an object with signature void handler(string,string,string,string)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)(std::string, std::string, std::string, std::string, std::string)	member,
		C *	object,
		int	e1,
		int	e2,
		int	e3,
		int	e4,
		int	e5
	)

inline

This template function is a shortcut to assign(regex,callback,int,int,int,int,int). It allows assignment of member function of an object with signature void handler(string,string,string,string,string)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

New in CppCMS 1.2

template<typename C >

void cppcms::url_dispatcher::assign	(	std::string const &	regex,
		void(C::*)(std::string, std::string, std::string, std::string, std::string, std::string)	member,
		C *	object,
		int	e1,
		int	e2,
		int	e3,
		int	e4,
		int	e5,
		int	e6
	)

inline

This template function is a shortcut to assign(regex,callback,int,int,int,int,int,int). It allows assignment of member function of an object with signature void handler(string,string,string,string,string,string)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

New in CppCMS 1.2

References cppcms::application::clear(), cppcms::parse_url_parameter(), and cppcms::util::const_char_istream::range().

void cppcms::url_dispatcher::assign_generic	(	std::string const &	regex,
		rhandler	handler
	)

Assign handler to pattern regex thus if URL that matches this pattern requested, handler is called with matched results

template<typename C >

void cppcms::url_dispatcher::assign_generic	(	std::string const &	regex,
		void(C::*)(booster::cmatch const &)	member,
		C *	object
	)

inline

This template function is a shortcut to assign_generic(regex,rhandler). It allows assignment of member function of an object with signature void handler(booster::cmatch const &)

In addition to calling member function it calls object->init() before call and object->clean() after the call of the C is derived from cppcms::application

New in CppCMS 1.2

bool cppcms::url_dispatcher::dispatch ( std::string url )

Try to find match between url and registered handlers and applications. If the match was found, it returns the method, how handler should bd dispatched synchronous or asynchronous, meaning the handler would be executed in thread pool or in the main non-blocking loop

template<typename Application , typename... ApplicationMemberArgs>

void cppcms::url_dispatcher::map	(	std::string const &	method,
		std::string const &	re,
		void(Application::*)(ApplicationMemberArgs...)	member,
		Application *	app,
		int...	groups
	)

Map member of app as a URL handler that matches regualr expression re and HTTP method method.

Parameters

method	- HTTP method to match like GET, POST, note regular expression can be used as well, for example "(POST\|PUT)"
re	- regular expression to match the URL
member	- member function of application app
app	- application that its member is called
groups	- matched groups converted to ApplicationMemberArgs

Note:

number of integers in groups should match the number of arguments of member
member can have up to 8 arguments MemberArgs and the function should receive same number of integer parameters representing matched groups

For exaample

class foo : public cppcms::application {
    ...
   void page(int x,std::string const &name);
   void update(int x);
   foo(...) 
   {
      dispatcher().map("GET","/page/(\\d+)(/(.*))?",&foo::page,this,1,3);
      dispatcher().map("POST","/update/(\\d+)",&foo::update,this,1);
   }

When the reuqest matches the method and regualr expression re, member of app is called, For case of page that has two parameters the first matched group is converted to integer and passed to as first parameter and 3rd group is passed as string to 2nd parameter

In case of update - that has only 1 parameter, a single integer should be passed

In addition to calling member function it calls app->init() before call and app->clean() after the call if Application is derived from cppcms::application

New in CppCMS 1.2

template<typename Application , typename... ApplicationMemberArgs>

void cppcms::url_dispatcher::map	(	std::string const &	re,
		void(Application::*)(ApplicationMemberArgs...)	member,
		Application *	app,
		int...	groups
	)

Map member of app as a URL handler that matches regualr expression re.

Parameters

re	- regular expression to match the URL
member	- member function of application app
app	- application that its member is called
groups	- matched groups converted to ApplicationMemberArgs

Note:

number of integers in groups should match the number of arguments of member
member can have up to 8 arguments MemberArgs and the function should receive same number of integer parameters representing matched groups

For exaample

class foo : public cppcms::application {
    ...
   void page(int x,std::string const &name);
   void update(int x);
   foo(...) 
   {
      dispatcher().map("/page/(\\d+)(/(.*))?",&foo::page,this,1,3);
      dispatcher().map("/update/(\\d+)",&foo::update,this,1);
   }

When the reuqest URL the regualr expression re, member of app is called, For case of page that has two parameters the first matched group is converted to integer and passed to as first parameter and 3rd group is passed as string to 2nd parameter

In case of update - that has only 1 parameter, a single integer should be passed

In addition to calling member function it calls app->init() before call and app->clean() after the call if Application is derived from cppcms::application

New in CppCMS 1.2

template<typename Application , typename... ApplicationMemberArgs>

void cppcms::url_dispatcher::map	(	std::string const &	method,
		booster::regex const &	re,
		void(Application::*)(ApplicationMemberArgs...)	member,
		Application *	app,
		int...	groups
	)

Map member of app as a URL handler that matches regualr expression re and HTTP method method.

Parameters

method	- HTTP method to match like GET, POST, note regular expression can be used as well, for example "(POST\|PUT)"
re	- regular expression to match the URL
member	- member function of application app
app	- application that its member is called
groups	- matched groups converted to ApplicationMemberArgs

Note:

number of integers in groups should match the number of arguments of member
member can have up to 8 arguments MemberArgs and the function should receive same number of integer parameters representing matched groups

For exaample

class foo : public cppcms::application {
    ...
   void page(int x,std::string const &name);
   void update(int x);
   foo(...) 
   {
      using booster::regex;
      dispatcher().map(regex("/page/(\\d+)(/(.*))?",regex::icase),&foo::page,this,1,3);
      dispatcher().map("POST","/update/(\\d+)",&foo::update,this,1);
   }

When the reuqest matches the method and regualr expression re, member of app is called, For case of page that has two parameters the first matched group is converted to integer and passed to as first parameter and 3rd group is passed as string to 2nd parameter

In case of update - that has only 1 parameter, a single integer should be passed

In addition to calling member function it calls app->init() before call and app->clean() after the call if Application is derived from cppcms::application

New in CppCMS 1.2

template<typename Application , typename... ApplicationMemberArgs>

void cppcms::url_dispatcher::map	(	booster::regex const &	re,
		void(Application::*)(ApplicationMemberArgs...)	member,
		Application *	app,
		int...	groups
	)

Map member of app as a URL handler that matches regualr expression re.

Parameters

re	- regular expression to match the URL
member	- member function of application app
app	- application that its member is called
groups	- matched groups converted to ApplicationMemberArgs

Note:

number of integers in groups should match the number of arguments of member
member can have up to 8 arguments MemberArgs and the function should receive same number of integer parameters representing matched groups

For exaample

class foo : public cppcms::application {
    ...
   void page(int x,std::string const &name);
   void update(int x);
   foo(...) 
   {
      using booster::regex;
      dispatcher().map(regex("/page/(\\d+)(/(.*))?",regex::icase),&foo::page,this,1,3);
      dispatcher().map("/update/(\\d+)",&foo::update,this,1);
   }

When the reuqest URL the regualr expression re, member of app is called, For case of page that has two parameters the first matched group is converted to integer and passed to as first parameter and 3rd group is passed as string to 2nd parameter

In case of update - that has only 1 parameter, a single integer should be passed

In addition to calling member function it calls app->init() before call and app->clean() after the call if Application is derived from cppcms::application

New in CppCMS 1.2

void cppcms::url_dispatcher::map_generic	(	std::string const &	method,
		booster::regex const &	re,
		generic_handler const &	h
	)

Map a callback h to a URL matching regular expression re and an HTTP method

Parameters

method	- HTTP method to match like GET, POST, note regular expression can be used as well, for example "(POST\|PUT)"
re	- regular expression to match the URL
h	- handler to execute

New in CppCMS 1.2

void cppcms::url_dispatcher::map_generic	(	booster::regex const &	re,
		generic_handler const &	h
	)

Map a callback h to a URL matching regular expression re

Parameters

re	- regular expression to match the URL
h	- handler to execute

New in CppCMS 1.2

void cppcms::url_dispatcher::mount	(	std::string const &	match,
		application &	app,
		int	part
	)

Mount a sub application app to the URL dispatcher, using regular expression match.

When mounted the URL is checked against match expression and then calls app.main(substr) where substr is the matched subexpression part. For example:

dispatcher().mount("/formums((/.*)?)",forums,1);

For example: for url /forums/page/3 it would call forums::main with value "/page/3"

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

cppcms/url_dispatcher.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Function Documentation