CppCMS
Classes | Public Types | Public Member Functions | List of all members
cppcms::url_dispatcher Class Reference

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:
booster::noncopyable

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

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(...)
{
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(...)
{
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: