CppCMS

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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:

## 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