libwebsockets
Lightweight C library for HTML5 websockets
lws-cgi.h
Go to the documentation of this file.
1 /*
2  * libwebsockets - small server side websockets and web server implementation
3  *
4  * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  */
24 
25 /*! \defgroup cgi cgi handling
26  *
27  * ##CGI handling
28  *
29  * These functions allow low-level control over stdin/out/err of the cgi.
30  *
31  * However for most cases, binding the cgi to http in and out, the default
32  * lws implementation already does the right thing.
33  */
34 
36  LWS_STDIN = 0,
39 };
40 
51 };
52 
53 struct lws_cgi_args {
54  struct lws **stdwsi; /**< get fd with lws_get_socket_fd() */
55  enum lws_enum_stdinouterr ch; /**< channel index */
56  unsigned char *data; /**< for messages with payload */
57  enum lws_cgi_hdr_state hdr_state; /**< track where we are in cgi headers */
58  int len; /**< length */
59 };
60 
61 #ifdef LWS_WITH_CGI
62 /**
63  * lws_cgi: spawn network-connected cgi process
64  *
65  * \param wsi: connection to own the process
66  * \param exec_array: array of "exec-name" "arg1" ... "argn" NULL
67  * \param script_uri_path_len: how many chars on the left of the uri are the
68  * path to the cgi, or -1 to spawn without URL-related env vars
69  * \param timeout_secs: seconds script should be allowed to run
70  * \param mp_cgienv: pvo list with per-vhost cgi options to put in env
71  */
72 LWS_VISIBLE LWS_EXTERN int
73 lws_cgi(struct lws *wsi, const char * const *exec_array,
74  int script_uri_path_len, int timeout_secs,
75  const struct lws_protocol_vhost_options *mp_cgienv);
76 
77 /**
78  * lws_cgi_write_split_stdout_headers: write cgi output accounting for header part
79  *
80  * \param wsi: connection to own the process
81  */
82 LWS_VISIBLE LWS_EXTERN int
83 lws_cgi_write_split_stdout_headers(struct lws *wsi);
84 
85 /**
86  * lws_cgi_kill: terminate cgi process associated with wsi
87  *
88  * \param wsi: connection to own the process
89  */
90 LWS_VISIBLE LWS_EXTERN int
91 lws_cgi_kill(struct lws *wsi);
92 
93 /**
94  * lws_cgi_get_stdwsi: get wsi for stdin, stdout, or stderr
95  *
96  * \param wsi: parent wsi that has cgi
97  * \param ch: which of LWS_STDIN, LWS_STDOUT or LWS_STDERR
98  */
99 LWS_VISIBLE LWS_EXTERN struct lws *
100 lws_cgi_get_stdwsi(struct lws *wsi, enum lws_enum_stdinouterr ch);
101 
102 #endif
103 ///@}