docs/AddingHandlers.html at main · kourier-server/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
<!-- HTML header for doxygen 1.9.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Kourier: Adding Handlers</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,100..900;1,100..900&family=Noto+Sans+Mono:wght@100..900&display=swap" rel="stylesheet">
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
        <script type="text/javascript" src="doxygen-awesome-darkmode-toggle.js"></script>
        <script type="text/javascript">
            DoxygenAwesomeDarkModeToggle.init()
        </script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only.css" rel="stylesheet" type="text/css"/>
<link href="doxygen-awesome-sidebar-only-darkmode-toggle.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Kourier<span id="projectnumber">&#160;1.0.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('AddingHandlers.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Adding Handlers</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> provides the <a class="el" href="classKourier_1_1HttpServer.html#ae8fa9324d81069559888d8853eec7b98">addRoute</a> method that you can use to map handlers to HTTP methods and paths.</p>
<p>Whenever <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> parses a request with a mapped method, it calls the handler mapped to the most specific path to handle it. For example, if you map <em>/food</em> and <em>/food/pasta</em> paths to <a class="el" href="classKourier_1_1HttpRequest.html#a68e941fd4fe8f501e0a1de78a70f7be7a7528035a93ee69cedb1dbddb2f0bfcc8">GET</a> requests, a <a class="el" href="classKourier_1_1HttpRequest.html#a68e941fd4fe8f501e0a1de78a70f7be7a7528035a93ee69cedb1dbddb2f0bfcc8">GET</a> request targeting <em>/food/fish/salmon</em> will be handled by the handler mapped to <em>/food</em>, and a <a class="el" href="classKourier_1_1HttpRequest.html#a68e941fd4fe8f501e0a1de78a70f7be7a7528035a93ee69cedb1dbddb2f0bfcc8">GET</a> request targeting <em>/food/pasta/spaghetti</em> will be handled by the handler mapped to <em>/food/pasta</em>.</p>
<p><a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> accepts as handlers pointers to functions having the following signature:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> handlerFcn(<span class="keyword">const</span> <a class="code hl_class" href="classKourier_1_1HttpRequest.html" title="The HttpRequest class represents an HTTP request.">Kourier::HttpRequest</a> &amp;request, <a class="code hl_class" href="classKourier_1_1HttpBroker.html" title="The HttpBroker class acts as a broker for HTTP-based communication. You can use it to receive the rem...">Kourier::HttpBroker</a> &amp;broker)</div>
</div><!-- fragment --><p>If you add a route to an already mapped path and method, <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> replaces the previous handler with the new one. The routes you add to <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> are used after you start the server. If you add a route to an already running server, it will only be available the next time you start it.</p>
<p>If <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> fails to find a mapped handler for a given request, it responds with a <em>404 Not Found</em> status code and closes the connection. If the mapped handler throws an unhandled exception, <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> responds with a <em>500 Internal Server Error</em> status code and closes the connection.</p>
<p><a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> provides a flexible request-handling mechanism, but you must know how it works. First, <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> calls the mapped handler as soon as when it parses the request header block. If the request has a body that is not chunked, <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> processes all body data available when it parses the header block before calling the mapped handler. You can call <a class="el" href="classKourier_1_1HttpRequest.html#a35eef34b6856c7f89e889bb6aa845204">isComplete</a> on the <a class="el" href="classKourier_1_1HttpRequest.html">HttpRequest</a> instance that <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> passes to the handler to know if the request is complete. Thus, <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> must allow you to handle requests outside the mapped handler. To this end, <a class="el" href="classKourier_1_1HttpBroker.html">HttpBroker</a> provides the <a class="el" href="classKourier_1_1HttpBroker.html#a5e64af503675366235e575286b54c717">setQObject</a> method that you can use to process the request after the handler function returns.</p>
<p>It is uncommon, but you can respond to the request before receiving it. In this case, <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> reads the entire request message body after sending the response, per section 9.3 of RFC 9112. <a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> responds automatically with the <em>100 Continue</em> status code when the request contains an <em>Expect</em> header field with a <em>100-continue</em> expectation.</p>
<p><a class="el" href="classKourier_1_1HttpServer.html">HttpServer</a> closes the connection if the mapped handler neither writes a complete response nor calls <a class="el" href="classKourier_1_1HttpBroker.html#a5e64af503675366235e575286b54c717">setQObject</a> to set an object to the broker. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.9.6-->
<!-- start footer part -->
</body>
</html>