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
35enum lws_enum_stdinouterr {
36 LWS_STDIN = 0,
37 LWS_STDOUT = 1,
38 LWS_STDERR = 2,
39};
40
41enum lws_cgi_hdr_state {
42 LCHS_HEADER,
43 LCHS_CR1,
44 LCHS_LF1,
45 LCHS_CR2,
46 LCHS_LF2,
47 LHCS_RESPONSE,
48 LHCS_DUMP_HEADERS,
49 LHCS_PAYLOAD,
50 LCHS_SINGLE_0A,
51};
52
53struct 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 */
72LWS_VISIBLE LWS_EXTERN int
73lws_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 */
82LWS_VISIBLE LWS_EXTERN int
83lws_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 */
90LWS_VISIBLE LWS_EXTERN int
91lws_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 */
99LWS_VISIBLE LWS_EXTERN struct lws *
100lws_cgi_get_stdwsi(struct lws *wsi, enum lws_enum_stdinouterr ch);
101
102#endif
103///@}
104
105