GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  HTTP_SERVER (3)

NAME

http_server - threaded server for HTTP and HTTPS

CONTENTS

Library
Synopsis
Description
     Servlets
Return Values
See Also
History
Authors
Bugs

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In stdio.h
.In netinet/in.h
.In openssl/ssl.h
.In pdel/http/http_defs.h
.In pdel/http/http_server.h struct http_server * http_server_start struct pevent_ctx *ctx struct in_addr ip u_int16_t port const struct http_server_ssl *ssl const char *server_name http_logger_t *logger void http_server_stop struct http_server **serverp int http_server_register_servlet struct http_server *serv struct http_servlet *servlet const char *vhost const char *urlpat int order void http_server_destroy_servlet struct http_servlet **servletp void http_server_set_proxy_handler struct http_server *serv http_proxy_t *handler void *arg

DESCRIPTION

These functions implement a threaded HTTP server supporting SSL and user-definable "servlets".

http_server_start starts a new server listening on IP address ip and port port. If ip is 0.0.0.0 then the server listens on all configured IP addresses. If port is zero then the default port (either 80 or 443 depending on whether SSL is enabled) is used. SSL is enabled by supplying a non-NULL pointer ssl to this structure:

struct http_server_ssl {
    const char   *cert_path;     /* path to certificate file */
    const char   *pkey_path;     /* path to private key file */
    const char   *pkey_password; /* private key password, if needed */
};

ctx is a pevent(3) event context with which the server registers to accept incoming connections. New connections are allocated individual threads in which to execute. The server enforces a hard limit of at most 1024 simultaneous connections, refusing to accept any new connections until one or more existing connections terminate.

The server_name string is used for the "Server:" HTTP header and typically includes the name and version number of the software, e.g., "MyServer/1.0".

The logger, if not NULL, specifies a callback for logging:

typedef void  http_logger_t(int sev, const char *fmt, ...);

Here sev is a syslog(3) severity level.

http_server_stop stops a server. All registered servlets are destroyed (see http_server_destroy_servlet below). Upon return, all connection threads are guaranteed to have exited and *serverp will be set to NULL. If *serverp is already NULL when http_server_stop is invoked, nothing happens.

Invoking http_server_stop from within a servlet is not supported and will give undefined results.

    Servlets

For anything interesting to happen, one or more servlets must be registered (see http_servlet(3)). Servlets are registered by invoking http_server_register_servlet.

The vhost parameter may be used for virtual hosting. If vhost is not NULL, it defines a virtual host for the server, and the servlet will only be invoked for requests whose Host: header matches vhost. If vhost is NULL, the servlet will only be invoked for requests with no Host: header or whose host does not match any other virtual host defined for the server (i.e., a NULL vhost indicates the default virtual host).

The servlet will be invoked for queries matching urlpat, which is an extended regular expression (see re_format(7)).

The request URI is URL-decoded before matching begins and only the relative part is matched. For example, a servlet registered to match the regular expression "^/foo bar$" would match "http://server/foo%20bar" and "http://server/foo%20bar?field=value" but not "http://server/foo%20bar/".

If two or more servlets match the same request, the servlet that was registered with the lowest order is chosen. If two servlets match and have the same order, the last one registered is chosen.

The order in which servlets are registered is important, especially with authorization servlets, because incoming requests may arrive at any time. I.e., authorization servlets should be registered before the servlet(s) that they protect.

http_server_destroy_servlet destroys a servlet, unregistering it as necessary. If any instances of the servlet are executing, this function will block until they exit. Upon return, *servletp is set to NULL. If *servletp is already NULL when http_server_destroy_servlet is invoked, nothing happens.

    Proxy support

Primitive proxy support is provided by http_server_set_proxy_handler. The handler is a pointer to a function of this type:

typedef void http_proxy_t(void *arg, struct http_request *req,
                 struct http_response *resp);

The handler is invoked with the same arg whenever an HTTP proxy request is received. To disable proxy support, invoke http_server_set_proxy_handler with both arguments equal to NULL.

RETURN VALUES

Upon error, http_server_start and http_server_register_servlet return NULL or -1, respectively, and set errno to an appropriate value.

SEE ALSO

http_client(3), http_mime(3), http_request(3), http_response(3), http_servlet(3), http_xml(3), libpdel(3), pevent(3), syslog(3), re_format(7)
.Rs Hypertext Transfer Protocol -- HTTP/1.1
.Re

HISTORY

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

AUTHORS


.An Archie Cobbs Aq archie@freebsd.org

BUGS

Creating a new thread for each request is somewhat expensive. The server should keep a pool of idle threads for faster dispatch of incoming connections.

The maximum number of connections should be configurable.

The server is probably not fully compliant to the HTTP specification.

Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.