zhangbo
/
GD32F450_BMC_BaseCode


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264
							<!DOCTYPE html>
<html lang="en">
<head>
    <title>Creating Handlers</title>
    <!-- Copyright Embedthis Software. All Rights Reserved. -->
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
    <meta name="description" content="Simple, fast, secure embedded web server" />
    <link href='https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700|Open+Sans:300italic,400,300,700'
        rel='stylesheet' type='text/css'>
    <link href='https://fonts.googleapis.com/css?family=Julius+Sans+One' rel='stylesheet' type='text/css'>
    
    <link href="../images/favicon.ico" rel="shortcut icon" />
    <link href="../lib/semantic-ui/semantic.min.css" rel="stylesheet" type="text/css" />
    <link href="../css/all.min.css" rel="stylesheet" type="text/css" />
    <link href="../css/api.min.css" rel="stylesheet" type="text/css" />
    

</head>
<body class="show-sidebar">
    <div class="sidebar">
        <div class="ui large left vertical inverted labeled menu">
            <div class="item">
                <a href="../" class="logo">GoAhead Docs</a>
            </div>
            <div class="item">
                <a href="../">
                    <b>General</b>
                </a>
                <div class="menu">
                    <a class="item" href="../">GoAhead Overview</a>
                    <a class="item" href="../users/features.html">GoAhead Features</a>
                    <a class="item" href="https://embedthis.com/goahead/download.html">Download</a> 
                    <a class="item" href="../licensing/">Licensing</a>
                </div>
            </div>
            <div class="item">
                <a href="../start/">
                    <b>Getting Started</b>
                </a>
                <div class="menu">
                    <a class="item" href="../start/quick.html">Quick Start</a>
                    <a class="item" href="../start/installing.html">Installing GoAhead</a>
                    <a class="item" href="../start/running.html">Running GoAhead</a>
                    <a class="item" href="../start/releaseNotes.html">Release Notes</a>
                    <a class="item" href="../start/faq.html">GoAhead FAQ</a>
                    <a class="item" href="../start/source.html">Building from Source</a>
                </div>
            </div>
            <div class="item">
                <a href="../users/"><b>User's Guide</b></a>
                <div class="menu">
                    <a class="item" href="../users/ports.html">Ports and Binding</a>
                    <a class="item" href="../users/routing.html">Routing Requests</a>
                    <a class="item" href="../users/handlers.html">Request Handlers</a>
                    <a class="item" href="../users/js.html">Embedded Javascript</a>
                    <a class="item" href="../users/jst.html">Javascript Templates</a>
                    <a class="item" href="../users/goactions.html">GoActions</a>
                    <a class="item" href="../users/cgi.html">CGI Programs</a>
                    <a class="item" href="../users/authentication.html">User Authentication</a>
                    <a class="item" href="../users/logFiles.html">Log Files</a>
                    <a class="item" href="../users/ssl.html">Secure Sockets (SSL)</a>
                    <a class="item" href="../users/security.html">Security Considerations</a>
                    <a class="item" href="../users/man.html">Man Pages</a>
                </div>
            </div>
            <div class="item">
                <a href="../developers/">Developer's Guide</a>
                <div class="menu">
                    <a class="item" href="../developers/embedding.html">Embedding GoAhead</a>
                    <a class="item" href="../developers/handlers.html">Creating GoAhead Handlers</a>
                    <a class="item" href="../developers/authstore.html">Creating Password Verifiers</a>
                    <a class="item" href="../developers/migrating.html">Migrating to GoAhead 3</a>
                    <a class="item" href="../developers/rom.html">Serving Pages from ROM</a>
                </div>
            </div>
            <div class="item">
                <a href="../ref/">Reference Guide</a>
                <div class="menu">
                    <a class="item" href="../ref/compatibility.html">Compatibility</a>
                    <a class="item" href="../ref/native.html">API Library</a>
                    <a class="item" href="../ref/architecture.html">GoAhead Architecture</a>
                    <a class="item" href="../standards/http.html">HTTP References</a>
                </div>
            </div>
            <div class="item">
                <a href="../developers/project.html">Project Resources</a>
                <div class="menu">
                    <a class="item" href="http://goo.gl/IGbiio">Official GoAhead News</a>
                    <a class="item" href="https://embedthis.com/goahead/">GoAhead Web Site</a>
                    <a class="item" href="https://github.com/embedthis/goahead">Source Code Repository</a>
                    <a class="item" href="https://github.com/embedthis/goahead/issues/99">GoAhead Security Alerts</a>
                    <a class="item" href="https://github.com/embedthis/goahead/issues">Project Issue Database</a>
                    <a class="item" href="https://github.com/embedthis/goahead/releases">Change Log</a>
                    <a class="item" href="https://github.com/embedthis/goahead/milestones">Roadmap</a>
                    <a class="item" href="https://embedthis.com/developers/contributors.html">Contributors Agreement</a>
                </div>
            </div>
            <div class="item">
                <b>Links</b>
                <div class="menu">
                    <a class="item" href="https://embedthis.com/">Embedthis Web Site</a>
                    <a class="item" href="https://embedthis.com/blog/">Embedthis Blog</a>
                    <a class="item" href="http://twitter.com/embedthat">Twitter</a>
                </div>
            </div>
        </div>
    </div>


    <div class="ui inverted masthead">
        <div class="ui fixed inverted menu">
            <div class="ui sidebar-launch button">
                <i class="icon list layout"></i>
            </div>
            <div class="right menu">
                <a class="item" href="https://embedthis.com/">Embedthis</a>
                    <a class="item" href="https://embedthis.com/goahead/">GoAhead Site</a>
                    <span class="desktop-only">
                        <a class="item" href="http://goo.gl/9bL9rM">GoAhead News</a>
                        <a class="item" href="https://github.com/embedthis/goahead">Repository</a>
                        <a class="item" href="https://embedthis.com/blog/">Blog</a>
                        <a class="item" href="https://twitter.com/embedthat">Twitter</a>
                    </span>

            </div>
        </div>
        
        <div class="ui breadcrumb">
            <a class="section" href="../">Home</a>
            
            <div class="divider">/</div>
            <a class="section" href="../developers/">
                Developer's Guide
            </a>
            
            
            <div class="divider">/</div>
            <a class="active section" href="handlers.html">Creating Handlers</a>
            
        </div>
        
        <iframe class="version desktop-only" src="../version.html"></iframe>

    </div>
    <div class="content">

            <h1>Creating GoAhead Handlers</h1>
            <p>GoAhead responds to client requests by routing the request to a request handler. The
            request handler is responsible for generating the response content or redirecting to another
            more suitable handler.</p>
            
            <p>GoAhead provides a suite of handlers for standard content types and web frameworks. But you can also create your own custom handler to process Http requests and perform any processing you desire. Once created handlers are configured via routes in the route table. See <a href="../users/routing.html">Request Routing</a> for more details about Routing.</p>

            <a id="processing"></a>
            <h2>Request Processing</h2>
            <p>When a request is received from the client, GoAhead parses the HTTP request headers and then determines the best GoAhead <a href="../users/routing.html">route</a> for the request. A route contains the full details for how to process a request including the required handler and required authentication. GoAhead matches each route in the route table in-order and selects the first matching route. The route specifies the desired handler for requests matching that route.</p>
            
            <h3>Matching a Handler</h3>
            <p>The last step of selecting a route is calling the candidate handler's optional match() callback. If the match callback returns true, the handler will be selected. If it returns false, the handler and route will be skipped and the route selection process continues.</p>
             
            <h3>Running a Handler</h3>
            <p>Once the route has been selected, GoAhead invokes the handler service callback to process the request and generate a response. At this point, request body data will be received and buffered. The handler may choose to not handler the request by returning a zero status code. In that case, the router continues matching routes to find a more suitable route and handler combination.</p>
            
            <a id="responses"></a>
            <h2>Generating Responses</h2>
            <p>An HTTP response consists of a status code, a set of HTTP headers and optionally a response body. If a
            status is not set, the successful status of 200 will be used. If not custom headers are defined, then a
          minimal standard set will be generated.</p>
            <h3>Setting Status and Headers</h3>
            <p>The response status may be set via:
                <a href="../ref/api/goahead.html#group___webs_1gaef03eccfb6f0d42b34f1a7a90bac62b6">websSetStatus</a>. 
                The response headers may be set via:
                <a href="../ref/api/goahead.html#group___webs_1ga506c041a3eb2dfeaab1e9d1f322eea0b">websWriteHeaders</a>.
                For example:</p>
            <pre class="ui code segment">
websSetStatus(wp, 200);
websWriteHeaders(wp, contentLength, 0);
websWriteHeader(wp, "X-MyCustomHeader", "1234");
websWriteEndHeaders(wp);
websWriteBlock(wp, buf, len);
websDone(wp);
</pre>
                <p>The websWriteBlock function will buffer written data that will be written to the client in the
                background.</p>
            <a id="errors"></a>
            <h3>Generating an Error Response</h3>
            <p>If the request has an error, the status and a response message may be set in one step via:
                <a href="../ref/api/goahead.html#group___webs_1ga3a9158494088fc25249543e69481e00e">websError</a>.
                When websError is called to indicate a request error, the supplied response text is used instead of
                any partially generated response body and the the connection field <em>conn-&gt;error</em> is set. Once
                set, pipeline processing is abbreviated and handler callbacks will not be called anymore. Consequently, if
                you need to continue handler processing, but want to set a non-zero status return code, do <i>not</i>
                use websError. Rather, use websSetStatus.</p>
<pre class="ui code segment">
websError(conn, 404, "Can't find %s", path);
</pre>
                <h4>Aborting Requests</h4>
                <p>The status argument to websError can also accept flags to control how the socket connection is
                managed. If WEBS_CLOSE is supplied, the connection will be closed when the request is completed. 
                Normally the connection is kept-open for subsequent requests on the same socket.</p>
<pre class="ui code segment">
websError(conn, 404 | WEBS_CLOSE, "Protocol error");
</pre>
            <a id="redirecting"></a>
            <h3>Redirecting</h3>
            <p>Sometimes a handler will want to generate a response that will redirect the client to a new URI.
            Use the 
            <a href="../ref/api/goahead.html#group___webs_1ga2a3e594ef28c12f3be0d7b54461af36e">websRedirect</a> call 
            to redirect the client. For example:
            <pre class="ui code segment">websRedirect(wp, WEBS_CODE_MOVED_PERMANENTLY, uri);</pre>
            <h3>Generating Response Body</h3>
            <p>The simplest way to generate a response is to use 
            <a href="../ref/api/goahead.html#group___webs_1ga8d5489a7fa2a2126bc0b6c703da4b964">websWrite</a>. 
            The websWrite routine will automatically flush data as required. This routine may block while data drains
            to the client if the data cannot be buffered. See the <i>main.bit</i> configuration limit:
            <a href="../start/source.html#main">LimitBuffer</a> for how to control the internal buffer size.
            When all the data has been written, call:
            <a href="../ref/api/goahead.html#group___webs_1gac2af58b7a686cb33e44eb010cf755ce1">websDone</a>. This
            finalizes the request.</p>
        <pre class="ui code segment">
websWrite(p, "Hello World\n");
websDone(wp);
</pre>
        <a id="defining"></a>
        <h2>Defining a Handler</h2>
        <p>To define an GoAhead handler, you need to call <a href=
            "../ref/api/goahead.html#group___webs_1gaac26a36fb28e1486fd54443ad59674a5">websDefineHandler</a>. For example:
<pre class="ui code segment">
static bool matchFoo(Webs *wp)
{
    /* Handle request */
    return 1;
}
static bool serviceFoo(Webs *wp)
{
    /* Do work here */
    return 1;
}
static void closeFoo() {
    /* Cleanup when goahead is exiting */
}
...
websDefineHandler("foo", matchFoo, serviceFoo, closeFoo, 0);
</pre>

    </div>
    <div class="terms ui basic center aligned segment">
        <p>&copy; Embedthis Software, 2003-2015. All rights reserved.</p>
    </div>

    <script src="../lib/jquery/jquery.min.js"></script>
    <script src="../lib/semantic-ui/semantic.min.js"></script>
    <script src="../scripts/sidebar.min.js"></script>
     

</body>
</html>