Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTTP_SERVLET(3)	       FreeBSD Library Functions Manual	       HTTP_SERVLET(3)

NAME
     http_servlet -- HTTP response generation API

LIBRARY
     PDEL Library (libpdel, -lpdel)

SYNOPSIS
     #include <sys/types.h>
     #include <stdio.h>
     #include <netinet/in.h>
     #include <openssl/ssl.h>
     #include <pdel/http/http_defs.h>
     #include <pdel/http/http_server.h>
     #include <pdel/http/http_servlet.h>

DESCRIPTION
     The http_servlet API provides an interface	for user code to generate HTTP
     responses for the http_server(3) HTTP server.

     The PDEL library comes with these predefined servlets:

	-   HTTP basic authentication: http_servlet_basicauth(3)
	-   HTTP secure	cookie authentication: http_servlet_cookieauth(3)
	-   HTTP redirect servlet: http_servlet_redirect(3)
	-   File servlet: http_servlet_file(3)
	-   tmpl(3) template servlet: http_servlet_tmpl(3)
	-   XML	servlet: http_servlet_xml(3)
	-   XML-RPC servlet: http_servlet_xmlrpc(3)

     Servlets are registered by	first constructing the servlet object and then
     invoking http_server_register_servlet().  A servlet is represented	by a
     struct http_servlet:

	typedef	int  http_servlet_run_t(struct http_servlet *servlet,
		       struct http_request *req, struct	http_response *resp);
	typedef	void http_servlet_destroy_t(struct http_servlet	*servlet);

	struct http_servlet {
	    void		     *arg;	   /* servlet cookie */
	    struct http_servlet_hook *hook;	   /* server info */
	    http_servlet_run_t	     *run;	   /* execute method */
	    http_servlet_destroy_t   *destroy;	   /* destructor */
	};

     The arg fields is private to the servlet itself and is ignored by the
     server.

     The hook is an http_server(3) private pointer that	should be initialized
     to	NULL when the servlet is constructed.  This pointer is set to a	non-
     NULL value	when the servlet is registered with a server.  The servlet it-
     self should not dereference or modify this	field.

     run() executes the	servlet	for a single request/response pair.  Each re-
     sponse is handled by the server in	a separate thread, and several re-
     quest/response pairs may exist at the same	time for the same servlet ob-
     ject; i.e., servlets are multi-threaded.  Synchronization is the respon-
     sibility of the servlet.  The thread executing the	servlet	may be can-
     celed at any cancellation point, e.g., if the requesting user-agent
     closes the	connection before the response has been	sent.  This means that
     the servlet code may need to register thread cleanup hooks	to avoid leak-
     ing memory	or other resources.

     destroy() will be called when the servlet is being	unregistered and de-
     stroyed (servlets can be registered only once; unregistering a servlet
     destroys it).  It should free any resources allocated when	the servlet
     was constructed.  The http_server(3) code guarantees that when destroy()
     is	invoked, there will be no instances of the run() method	currently exe-
     cuting.

RETURN VALUES
     If	successful, run() should return	1 to indicate that the response	is
     complete, or 0 to indicate	that the servlet did not generate a response
     and execution should continue with	the next-best matching servlet.	 Zero
     return values are used by servlets	that only generate a response condi-
     tionally, e.g., authorization servlets.

     On	failure	run() should -1	and set	errno.	In this	case (typically	due to
     a system error), if a response has	not yet	been sent, a generic "500 In-
     ternal Server Error" response will	be automatically generated with	the
     error string from strerror(3).

SEE ALSO
     http_client(3), http_request(3), http_response(3),	http_server(3),
     http_servlet_basicauth(3),	http_servlet_cookieauth(3),
     http_servlet_file(3), http_servlet_redirect(3), http_servlet_tmpl(3),
     http_servlet_xml(3), http_servlet_xmlrpc(3), libpdel(3)

     R.	Fielding, J. Gettys, J.	Mogul, H. Frystyk, L. Masinter,	P. Leach, and
     T.	Berners-Lee, Hypertext Transfer	Protocol -- HTTP/1.1, RFC 2616.

HISTORY
     The PDEL library was developed at Packet Design, LLC.
     http://www.packetdesign.com/

AUTHORS
     Archie Cobbs <archie@freebsd.org>

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=http_servlet&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help