Skip to content
Newer
Older
100644 797 lines (615 sloc) 22.7 KB
108bbc9 @klacke ""
authored May 23, 2005
1 .TH YAWS_API "5" "" "" "User API"
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
2 .SH NAME
3 yaws_api \- api available to yaws web server programmers
4 .SH SYNOPSIS
5 .B yaws_api:Function(...)
6
7 .SH DESCRIPTION
e2f272a @klacke explicit support for content_length
authored Mar 11, 2004
8
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
9 .PP
e263363 @klacke speling
authored Jul 1, 2008
10 This is the api available to yaws web server programmers. The Erlang
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
11 module yaws_api contains a wide variety of functions that can
12 be used inside yaws pages.
13
14 .PP
15 Each chunk of yaws code is executed while the yaws page is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
16 being delivered from the server. We give a very simple example here
e263363 @klacke speling
authored Jul 1, 2008
17 to show the basic idea. Imagine the following HTML code:
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
18
19 \fI
20 .nf
21 <html>
22 <body>
23
24 <h1> Header 1</h1>
25
26 <erl>
27 out(Arg) ->
28 {html, "<p> Insert this text into the document"}.
29 </erl>
30
31 </body>
32 </html>
33
34 .fi
35 \fR
36
37
38 .PP
39 The \fBout(Arg)\fR function is supplied one argument, an #arg{} structure.
40 We have the following relevant record definitions:
41
42 \fI
43 .nf
44
45 -record(arg, {
0be3c7e @klacke untabified all of yaws
authored Feb 14, 2008
46 clisock, %% the socket leading to the peer client
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
47 client_ip_port, %% {ClientIp, ClientPort} tuple
0be3c7e @klacke untabified all of yaws
authored Feb 14, 2008
48 headers, %% headers
49 req, %% request
50 clidata, %% The client data (as a binary in POST requests)
51 server_path, %% The normalized server path
52 querydata, %% Was the URL on the form of ...?query (GET reqs)
53 appmoddata, %% the remainder of the path up to the query
54 docroot, %% where's the data
55 fullpath, %% full path to yaws file
56 cont, %% Continuation for chunked multipart uploads
57 state, %% State for use by users of the out/1 callback
58 pid, %% pid of the yaws worker process
59 opaque, %% useful to pass static data
60 appmod_prepath, %% path in front of: <appmod><appmoddata>
61 pathinfo %% Set to 'd/e' when calling c.yaws for the request
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored Aug 24, 2003
62 %% http://some.host/a/b/c.yaws/d/e
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
63 }).
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
64 .fi
65 \fR
66
67 The headers argument is also a record:
68 \fI
69 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
70
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
71 -record(headers, {
8d5aa60 @klacke ""
authored Nov 10, 2002
72 connection,
73 accept,
74 host,
75 if_modified_since,
76 if_match,
77 if_none_match,
78 if_range,
79 if_unmodified_since,
80 range,
81 referer,
82 user_agent,
83 accept_ranges,
84 cookie = [],
85 keep_alive,
86 content_length,
87 authorization,
88 other = [] %% misc other headers
89 }).
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
90
91 .fi
92 \fR
93
94 .PP The \fBout/1\fR function can use the Arg to generate any content
95 it likes. We have the following functions to aid that generation.
96
97
98 .SH API
99
100 .TP
101 \fBssi(DocRoot, ListOfFiles)\fR
102 Server side include. Just include the files as is in the document. The files
103 will \fBnot\fR be parsed and searched for <erl> tags.
104
105
106 .TP
107 \fBpre_ssi_files(DocRoot, ListOfFiles) ->
108 Server side include of pre indented code. The data in Files
109 will be included but contained in a <pre> tag. The data will be
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
110 htmlized.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
111
112 .TP
113 \fBpre_ssi_string(String)\fR
114 Include htmlized content from String.
115
116
117 .TP
118 \fBf(Fmt, Args)\fR
119 The equivalent of io_lib:format/2. This function is automatically
120 -included in all erlang code which is a part of a yaws page.
121
122 .TP
c5ebd38 @klacke added pam support + prepare for 1.58
authored Feb 1, 2006
123 \fBhtmlize(Binary | List | Char)\fR
124 Htmlize an IO list object.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
125
126 .TP
127 \fBsetcookie(Name, Value, [Path, [ Expire, [Domain , [Secure]]]])\fR
128 Sets a cookie to the browser.
129
130 .TP
131 \fBfind_cookie_val(Cookie, Header)\fR
132 This function can be used to search for a cookie that was previously
133 set by \fBsetcookie/2-6\fR. For example if we set a cookie
134 as \fByaws_api:setcookie("sid",SomeRandomSid) \fR, then on subsequent requests
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
135 from the browser we can call:
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
136 \fBfind_cookie("sid",(Arg#arg.headers)#headers.cookie)\fR
137
138 The function returns [] if no cookie was found, otherwise the actual cookie
139 is returned as a string.
140
141
142 .TP
143 \fBredirect(Url\fR
144 This function generates a redirect to the browser.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
145 It will clear any previously set headers. So to generate
146 a redirect \fBand\fR set a cookie, we need to set the cookie after
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
147 the redirect as in:
148 \fI
149 .nf
150 out(Arg) ->
151 ... do some stuff
152
153 Ret = [{redirect, "http://www.somewhere.com"},
154 setcookie("sid", Random)
155 ].
156
157 .fi
158 \fR
159
160
161 .TP
883fa5a @klacke added redirect_self to yaws_api
authored Sep 12, 2008
162 \fBredirect_self(Arg)\fR
163 If we want to issue a redirect to ourselves, this function
164 is useful. It returns a record \fI#redir_self{}\fR defined in
165 \fIyaws_api.hrl\fR. The record contains fields to construct
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
166 a URL to ourselves.
883fa5a @klacke added redirect_self to yaws_api
authored Sep 12, 2008
167 \fI
168 .nf
169
170 -record(redir_self, {
171 host, %% string() - our own host
172 scheme, %% http | https
173 scheme_str, %% "https://" | "http://"
174 port, %% integer() - our own port
175 port_str %% "" | ":<int>" - the optional port part
176 %% to append to the url
177 }).
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored Jan 6, 2012
178 .fi
883fa5a @klacke added redirect_self to yaws_api
authored Sep 12, 2008
179
180
181 .TP
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
182 \fBget_line(String)\fR
d02b965 @klacke qnx port + docs overhaul by cschatz@networkadvantage.biz
authored Feb 13, 2004
183 This function is convenient when getting \\r\\n terminated lines
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
184 from a stream of data. It returns:
185
186 \fB{line, Line, Tail}\fR or \fB{lastline, Line, Tail}\fR
187
188 The function handles multilines as defined in e.g. SMTP or HTTP
189
190 .TP
191 \fBmime_type(FileName)\fR
192 Returns the mime type as defined by the extension of FileName
193
194 .TP
195 \fBstream_chunk_deliver(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
196 When a yaws function needs to deliver chunks of data which it gets
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
197 from a process. The other process can call this function to deliver
198 these chunks. It requires the \fBout/1\fR function to return the
199 value \fB{streamcontent, MimeType, FirstChunk}\fR to work.
a39fab8 @klacke added example docs on how to stream data
authored Sep 13, 2004
200 YawsPid is the process identifier of the yaws process delivering the original
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
201 .yaws file. That is self() in the yaws code.
ebb94d8 @klacke 1.54
authored Apr 12, 2005
202 The Pid must typically be passed (somehow) to the producer of the stream.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
203
a39fab8 @klacke added example docs on how to stream data
authored Sep 13, 2004
204 .TP
205 \fBstream_chunk_deliver_blocking(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
206 A synchronous version of the above function. This synchronous version
207 must always be used when the producer of the stream is faster than the
208 consumer. This is usually the case since the client is the WWW browser.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
209
210 .TP
211 \fBstream_chunk_end(YawsPid)\fR
212 When the process discussed above is done delivering data, it must call
213 this function to let the yaws content delivering process finish up
214 the HTTP transaction.
215
216 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
217 \fBstream_process_deliver(Socket, IoList)\fR
218 Yaws allows application processes to deliver data directly to the
219 client. The application tells yaws about such a process by returning
220 \fB{streamcontent_from_pid, MimeType, Pid}\fR from its \fBout/1\fR
221 function. In this case, \fIPid\fR uses the
222 \fBstream_process_deliver/2\fR function to deliver data to the
223 client. The application gets \fISocket\fR from \fIArg#arg.clisock\fR,
224 and \fIIoList\fR is the data to be sent to the client.
225
226 .TP
227 \fBstream_process_deliver_chunk(Socket, IoList)\fR
228 Same as above but delivers \fIIoList\fR using HTTP chunked transfer
229 format. \fIIoList\fR must have a size greater than zero. The
230 application process delivering the data will have had to have make
231 sure that the HTTP headers of the response indicate chunked transfer
232 mode, either by ensuring no Content-Length header is set or by
233 specifically setting the Transfer-Encoding header to chunked.
234
235 .TP
236 \fBstream_process_deliver_final_chunk(Socket, IoList)\fR
237 If the application process delivering data to the client uses chunked
238 transfer mode, it must call this to deliver the final chunk of the
239 transfer. This tells yaws to create a special final chunk in the
240 format required by the HTTP specification (RFC 2616). \fIIoList\fR may
241 be empty, but if its size is greater than zero, that data will be
242 sent as a separate chunk before the final chunk.
243
244 .TP
245 \fBstream_process_end(Socket, YawsPid)\fR
246 Application processes delivering data directly to clients must call
247 this function to inform yaws that they've finished using
248 \fISocket\fR. The \fIYawsPid\fR argument will have been passed to the
249 process earlier when yaws sent it a message telling it to proceed with
5da72a3 @vinoski Allow "stream processes" to close the client socket
vinoski authored May 12, 2010
250 data delivery. Yaws expects \fISocket\fR to be open.
251
252 .TP
253 \fBstream_process_end(closed, YawsPid)\fR
254 Same as the previous function but the application calls this if it
255 closes the client socket as part of its data delivery process. This
256 allows yaws to continue without assuming the socket is still open and
257 encountering errors due to that assumption. The \fIYawsPid\fR argument
258 will have been passed to the application process earlier when yaws
259 sent it a message telling it to proceed with data delivery.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
260
261 .TP
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
262 \fBparse_query(Arg)\fR
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
263 This function will parse the query part of the URL.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
264 It will return a {Key, Value} list of the items supplied in the query
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
265 part of the URL.
266
267 .TP
268 \fBqueryvar(Arg, VarName)\fR
269 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
270 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
271 querypart of the url. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk…
authored Nov 10, 2007
272 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored Apr 27, 2009
273 return \fI{Val1, ....}\fR.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
274
275
276 .TP
c4523b3 @klacke ""
authored Oct 18, 2002
277 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
278 This function will parse the POST data as supplied from the browser.
279 It will return a {Key, Value} list of the items set by the browser.
280
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
281 .TP
282 \fBpostvar(Arg, VarName)\fR
283 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
284 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
285 POSTed data from the client. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk…
authored Nov 10, 2007
286 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored Apr 27, 2009
287 return \fI{Val1, ....}\fR.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
288
c9778e0 @klacke added support for 2 additional configure
authored Apr 27, 2006
289 .TP
290 \fBgetvar(Arg, VarName)\fR
291 This function looks at the HTTP request method from the
292 client and invokes postvar/2 if it is a POST from the client
293 and queryvar/2 if it is a GET request from the client.
294
c4523b3 @klacke ""
authored Oct 18, 2002
295
296 .TP
297 \fBparse_multipart_post(Arg)\fR
298
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
299 If the browser has set the Content-Type header to the value
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
300 "multipart/form-data", which is the case when the browser
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
301 wants to upload a file to the server the following happens:
302
303
304 If the function returns \fB{result, Res}\fR no more data
305 will come from the browser.
306
307 If the function returns \fB{cont, Cont, Res}\fR the browser
308 will supply more data. (The file was to big to come in one read)
309
310 This indicates that there is more data to come and the out/1 function
311 should return {get_more, Cont, User_state} where User_state might
312 usefully be a File Descriptor.
313
314
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
315 The Res value is a list of either:
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
316 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
317
318
319 Example usage could be:
320 \fI
321 .nf
322 <erl>
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
323
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
324 out(A) ->
c4523b3 @klacke ""
authored Oct 18, 2002
325 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
326 {cont, Cont, Res} ->
327 St = handle_res(A, Res),
328 {get_more, Cont, St};
329 {result, Res} ->
330 handle_res(A, Res),
331 {html, f("<pre>Done </pre>",[])}
332 end.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
333
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
334 handle_res(A, [{head, Name}|T]) ->
335 io:format("head:~p~n",[Name]),
336 handle_res(A, T);
337 handle_res(A, [{part_body, Data}|T]) ->
338 io:format("part_body:~p~n",[Data]),
339 handle_res(A, T);
340 handle_res(A, [{body, Data}|T]) ->
341 io:format("body:~p~n",[Data]),
342 handle_res(A, T);
343 handle_res(A, []) ->
344 io:format("End_res~n").
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
345
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
346 </erl>
347 .fi
348 \fR
349
350
351
352 .TP
87b1456 @klacke wrote the shopppingcart example
authored Oct 6, 2002
353 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
354 Create a new cookie based session, the yaws system will set the
e263363 @klacke speling
authored Jul 1, 2008
355 cookie. The new random generated cookie is returned from this
87b1456 @klacke wrote the shopppingcart example
authored Oct 6, 2002
356 function. The Opaque argument will typically contain user data
e263363 @klacke speling
authored Jul 1, 2008
357 such as user name and password
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
358
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored May 28, 2004
359 .TP
360 \fBnew_cookie_session(Opaque, TTL)\fR
361 As above, but allows to set a session specific time-out value,
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored Jul 1, 2008
362 overriding the system specified time-out value.
363
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
364 .TP
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored Jul 1, 2008
365 \fBnew_cookie_session(Opaque, TTL, CleanupPid)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
366 As above, but also sends a message
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored Jul 1, 2008
367 \fI{yaws_session_end, Reason, Cookie, Opaque}\fR to the provided CleanuPid where
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
368 Reason can be either of \fItimeout\fR or \fInormal\fR. The \fICookie\fR
6964fff @klacke modified patch by Robert David to add a hook to yaws session server w…
authored Jul 1, 2008
369 is the HTTP cookie as returned by \fInew_session()\fR and the Opaque
370 is the user provided Opaque parameter to \fInew_session()\fR.
371 The purpose of the feature is to cleanup resources assigned to the session.
372
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored May 28, 2004
373
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
374 .TP
87b1456 @klacke wrote the shopppingcart example
authored Oct 6, 2002
375 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
376
377 .TP
378 \fBprint_cookie_sessions() \fR
379
87b1456 @klacke wrote the shopppingcart example
authored Oct 6, 2002
380
381 .TP
382 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
383
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
384 .TP
87b1456 @klacke wrote the shopppingcart example
authored Oct 6, 2002
385 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
386
387
50a7ab2 @klacke added support/docs for embedded mode
authored Sep 27, 2002
388 .TP
389 \fBsetconf(Gconf, Groups)\fR
390 This function is intended for embedded mode in yaws. It makes it possible
391 to load a yaws configuration from another data source than /etc/yaws.conf, such
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
392 as a database.
50a7ab2 @klacke added support/docs for embedded mode
authored Sep 27, 2002
393 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
394 start with an empty default configuration, and wait for some other
395 program to execute a \fIsetconf/2\fR
396 The Gconf is a \fI#gconf{}\fR record and the Group variable is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
397 a list of lists of \fI#sconf{}\fR records. Each sublist must
50a7ab2 @klacke added support/docs for embedded mode
authored Sep 27, 2002
398 contain \fI#sconf{}\fR records with the same IP/Port listen address.
e263363 @klacke speling
authored Jul 1, 2008
399 To create a suitable initial #gconf{} record see the code in
400 yaws_config:make_default_gconf/2. Especially the \fIyaws_dir\fR parameter
401 is important to get right.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
402
2b9f008 @klacke ""
authored Nov 5, 2002
403
404 .TP
405 \fBurl_decode(Str)\fR
e263363 @klacke speling
authored Jul 1, 2008
406 Decode url-encoded string. A URL encoded string is a string where
2b9f008 @klacke ""
authored Nov 5, 2002
407 all alfa numeric characters and the the character _ are preserved
408 and all other characters are encode as "%XY" where X and Y are the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
409 hex values of the least respective most significant 4 bits in the 8 bit
2b9f008 @klacke ""
authored Nov 5, 2002
410 character.
411
412 .TP
413 \fBurl_encode(Str)\fR
414 Url-encodes a string. All URLs in HTML documents must be URL encoded.
415
416
814eb04 @klacke ""
authored Nov 7, 2002
417 .TP
8d5aa60 @klacke ""
authored Nov 10, 2002
418 \fBreformat_header(H)\fR
e263363 @klacke speling
authored Jul 1, 2008
419 Returns a list of reformatted header values from a #header{}
814eb04 @klacke ""
authored Nov 7, 2002
420 record. The return list is suitable for retransmit.
421
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id su…
authored Mar 10, 2004
422 .TP
423 \fBrequest_url(ARG)\fR
424 Return the url as requested by the client. Return value
425 is a #url{} record as defined in yaws_api.hrl
426
2b9f008 @klacke ""
authored Nov 5, 2002
427
8da2b3a @klacke parse_url
authored Nov 20, 2002
428 .TP
429 \fBparse_url(Str)\fR
430 Parse URL in a string, returns a #url record
431
432 .TP
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored Aug 25, 2003
433 \fBformat_url(UrlRecord)\fR
8da2b3a @klacke parse_url
authored Nov 20, 2002
434 Takes a #url record a formats the Url as a string
435
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored Aug 25, 2003
436 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
437 \fBcall_cgi(Arg, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored Aug 25, 2003
438 Calls an executable CGI script,
439 given by its full path. Used to make `.yaws' wrappers for CGI
440 programs. This function usually returns \fIstreamcontent\fR.
441
442 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
443 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored Aug 25, 2003
444 Like before, but
445 calls \fIExefilename\fR to handle the script. The file name of the
446 script is handed to the executable via a CGI meta variable.
8da2b3a @klacke parse_url
authored Nov 20, 2002
447
f3deff2 @klacke added a dir_listing function in yaws_api
authored May 24, 2007
448 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
449 \fBcall_fcgi_responder(Arg)\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
450 Calls a FastCGI responder.
451 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
452 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored Jul 10, 2009
453 Used to make `.yaws' wrappers for FastCGI responders.
454 Returns the same return values as out/1 (see below).
455
456 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
457 \fBcall_fcgi_responder(Arg, Options)\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
458 Same as above, but Options overrides the defaults from the server
459 configuration:
460
461 \fI
462 .nf
463 Options = [Option]
464 Option -- one of the following:
465 .fi
466 \fR
467
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
468 \fB{app_server_host, string() | ip_address()}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
469 The hostname or the IP address of the FastCGI application server.
470
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
471 \fB{app_server_port, 0..65535}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
472 The TCP port number of the FastCGI application server.
473
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
474 \fB{path_info, string()}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
475 Override default pathinfo in Arg#arg.pathinfo.
476
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
477 \fB{extra_env, ExtraEnv}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
478 Override default pathinfo in Arg#arg.pathinfo.
479
480 \fI
481 .nf
482 ExtraEnv = [Var]
483 Var = {Name, Value}
484 Name = string()
485 Value = string()
486 .fi
487 \fR
488
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
489 \fB{trace_protocol, boolean()}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
490 Enable or disable tracing of FastCGI protocol messages as info
491 log messages.
492
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
493 \fB{log_app_error, boolean()}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
494 Enable or disable logging of application error messages: output
495 to stderr and non-zero exit value.
496
497 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored Oct 17, 2009
498 \fBcall_fcgi_authorizer(Arg) -> {allowed, Out} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
499 Calls a FastCGI authorizer.
500 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
501 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored Jul 10, 2009
502 Used to make `.yaws' wrappers for FastCGI authorizers.
503 Variables contains the values of the variables returned by the FastCGI
504 application server in the "Variable-XXX: YYY" headers.
505
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored Oct 17, 2009
506 If access is denied, Out contains the complete response returned by
507 the FastCGI application server. This response is typically returned
508 as-is to the HTTP client.
509
510 If access is allowed, Out contains the response returned by the
511 FastCGI application server minus the body (i.e. minus the content)
512 which should be ignored per the FastCGI specification. This response
513 is typically not returned to the HTTP client. The calling application
514 module may wish to inspect the response, for example by extracting
515 variables (see fcgi_extract_variables below) or by inspecting the
516 headers returned by the FastCGI application server.
517
2fa66b0 @klacke cgi support
authored Jul 10, 2009
518 \fI
519 .nf
520 Out -- See return values for out/1 below
521 .fi
522 \fR
523
524 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored Oct 17, 2009
525 \fBcall_fcgi_authorizer(Arg, Options) -> {allowed, Out} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored Jul 10, 2009
526 Same as above, but Options overrides the defaults from the server
527 configuration. See call_fcgi_responder/2 above for a description
528 of Options.
529
530 .TP
18cec55 @vinoski fixes for FCGI authorization (Bruno Rijsman), plus I cleaned up inden…
vinoski authored Oct 17, 2009
531 \fBfcgi_extract_variables(Out) -> [{Name, Value}]\fR
532 Extracts the environment variables from a FastCGI authorizer response
533 by looking for headers of the form "Variable-Name: Value".
534
535 \fI
536 .nf
537 Name = string() -- The name of the variable (the "Variable-" prefix
538 has already been removed).
539 Value = string() -- The value of the variable.
540 .fi
541 \fR
542
543 .TP
f3deff2 @klacke added a dir_listing function in yaws_api
authored May 24, 2007
544 \fBdir_listing(Arg)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
545 Perform a directory listing. Can be used in special directories
f3deff2 @klacke added a dir_listing function in yaws_api
authored May 24, 2007
546 when we don't want to turn on dir listings for the entire server.
547 Always returns ok.
8da2b3a @klacke parse_url
authored Nov 20, 2002
548
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
549 .SH RETURN VALUES from out/1
550 .PP
551 The out/1 function can return different values to control the behavior
552 of the server.
553
554 .TP
555 \fB{html, DeepList}\fB
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
556 This assumes that DeepList is formatted HTML code.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
557 The code will be inserted in the page.
558
559 .TP
04970fa exhtml cleanup
Claes Wikstrom authored Dec 25, 2011
560 \fB{ehtml|exhtml, Term}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
561 This will transform the erlang term Term into a
04970fa exhtml cleanup
Claes Wikstrom authored Dec 25, 2011
562 stream of HTML content. The exhtml variant transforms into
563 strict XHTML code. The basic syntax of Term
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
564 is
565
566 \fI
567 .nf
568 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
569 binary() | character()
8d5aa60 @klacke ""
authored Nov 10, 2002
570 Tag = atom()
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
571 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored Nov 10, 2002
572 Key = atom()
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
573 Value = string()
574 Body = EHTML
575 .fi
576 \fR
577
578
ebb94d8 @klacke 1.54
authored Apr 12, 2005
579 For example, \fI{p, [], "Howdy"}\fR expands into
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored Jan 6, 2012
580 "<p>Howdy</p>" and
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
581
582 \fI
583 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
584 {form, [{action, "a.yaws"}],
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
585 {input, [{type,text}]}}
586
587 .fi
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
588 \fR
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
589
590 expands into
591
592 \fI
593 .nf
594 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored Sep 27, 2002
595 <input type="text">
596 </form>
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
597 .fi
598 \fR
599
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
600 It may be more convenient to generate erlang tuples
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
601 than plain html code.
602
603 .TP
604 \fB{content, MimeType, Content}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
605 This function will make the web server generate
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
606 different content than HTML. This return value is only allowed
607 in a yaws file which has only one <erl> </erl> part and no
608 html parts at all.
609
610
611 .TP
612 \fB{streamcontent, MimeType, FirstChunk}\fR
613 This return value plays the same role as the \fIcontent\fR return
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
614 value above.
e2f272a @klacke explicit support for content_length
authored Mar 11, 2004
615
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
616 However it makes it possible to stream data to the client
617 if the yaws code doesn't have access to all the data in one go. (Typically
618 if a file is very large or if data arrives from back end servers on the network.
619
620 .TP
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored Jan 22, 2009
621 \fB{streamcontent_with_timeout, MimeType, FirstChunk, Timeout}\fR
622 Similar to above, but with an explicit timeout. The deafult timeout
623 is 30 secs. I.e if the application fails to deliver data to the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
624 Yaws process, the streaming will stop. This is often not the
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored Jan 22, 2009
625 desired behaviour in Comet/Ajax applications. It's possible to
626 provide 'infinity' as timeout.
627
628 .TP
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored Jan 6, 2012
629 \fB{streamcontent_from_pid, MimeType, Pid}\fR
630 This return value is similar to the \fIstreamcontent\fR return value above.
631
632 However it makes it possible to stream data to the client directly from an
633 application process to the socket. This approach can be useful for applications
634 that employ long-polling (Comet) techniques, for example, and for applications
635 wanting to avoid buffering data or avoid HTTP chunked mode transfer for streamed
636 data.
637
638 .TP
639 \fB{streamcontent_with_size, Sz, MimeType, FirstChunk}\fR
640 This return value is similar to the \fIstreamcontent\fR return value above.
641
642 However it makes it possible to stream data to the client by setting the content
643 length of the response. As the opposite of other ways to stream data, in this
644 case, the response is not chunked encoded.
645
646
647 .TP
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
648 \fB{header, H}\fR
e2f272a @klacke explicit support for content_length
authored Mar 11, 2004
649 Accumulates a HTTP header. The trailing CRNL which is supposed
ebb94d8 @klacke 1.54
authored Apr 12, 2005
650 to end all HTTP headers must NOT be added. It is added by the server.
e2f272a @klacke explicit support for content_length
authored Mar 11, 2004
651 The following list of headers are given special treatment.
652
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
653 \fI{connection, What}\fR
e2f272a @klacke explicit support for content_length
authored Mar 11, 2004
654
655 This sets the connection header. If \fIWhat\fR is the special value
656 \fI"close"\fR, the connection will be closed once the yaws page is delivered
657 to the client.
658
659 \fI{location, Url}\fR
660
661 Sets the Location: header. This header is typically combined with
662 the \fI{status, 302}\fR return value.
663
664 \fI{cache_control, What}\fR
665
666 Sets the Cache-Control: header.
667
668 \fI{set_cookie, Cookie}\fR
669
e263363 @klacke speling
authored Jul 1, 2008
670 Prepends a a Set-Cookie: header to the list of previously
e2f272a @klacke explicit support for content_length
authored Mar 11, 2004
671 set Set-Cookie: headers.
672
673 \fI{content_type, MimeType}\fR
674
675 Sets the Content-Type header.
676
677 \fI{content_length, Len}\fR
678
679 Normally yaws will ship Yaws pages using Transfer-Encoding: chunked. This
680 is because we generally can't know how long a yaws page will be. If we for
681 some reason want to force a Content-Length: header (and we actually do
682 know the length of the content, we can force yaws to not ship the
683 page chunked.
684
685
686 All other headers must be added using the normal HTTP syntax.
687 Example:
688
689 {header, "My-X-Header: gadong"}
690
691
692
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
693
694 .TP
695 \fB{allheaders, HeaderList}\fB
696 Will clear all previously accumulated headers and replace them.
697
698
699 .TP
700 \fB{status, Code}\fR
701 Will set another HTTP status code than 200.
702
703
704 .TP
705 \fBbreak\fR
706 Will stop processing of any consecutive chunks of erl or html code
707 in the yaws file.
708
709 .TP
710 \fBok\fR
711 Do nothing.
712
713
714 .TP
715 \fB{redirect, Url}\fR
716 Erase all previous headers and accumulate a single
717 Location header. Set the status code.
718
719 .TP
720 \fB{redirect_local, Path}\fR
721 Does a redirect to the same Scheme://Host:Port/Path as we
722 currently are executing in.
723
724 .TP
725 \fB{get_more, Cont, State}\fR
726 When we are receiving large POSTs we can return this value
727 and be invoked again when more Data arrives.
728
729
730 .TP
c837288 @klacke page retval
authored Nov 12, 2002
731 \fB{page, Page}\fR
732 Make Yaws return a different page than the one being
733 requested.
734
735
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored Aug 24, 2003
736 .TP
737 \fB{page, {Options, Page}}\fR
738 Like the above, but supplying an additional deep list of options. For
739 now, the only type of option is \fI{header, H}\fR with the effect of
740 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
741
c837288 @klacke page retval
authored Nov 12, 2002
742
743 .TP
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
744 \fB{ssi, File, Delimiter, Bindings}\fR
745 Server side include File and macro expansion in File.
e263363 @klacke speling
authored Jul 1, 2008
746 Each occurrence of a string, say "xyz", inside File which
747 is inside Delimiters is replaced with the corresponding
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
748 value in Bindings.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
749
750 Example:
751 Delimiter = %%
752
753 File contains the string .... %%xyz%% .....
754
755 Bindings contain the tuple {"xyz", "Dingbat"}
756
e263363 @klacke speling
authored Jul 1, 2008
757 The occurrence of %%xyz%% in File will be replaced with "Dingbat"
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
758 in the Server side included output.
759
760 The {ssi, File, Delimiter, Bindings} statement can also
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
761 occur inside a deep ehtml structure.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored Dec 17, 2003
762
763
764 .TP
379666b @klacke documented jockes new bindings feature
authored Jan 27, 2004
765 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
766 Establish variable bindings that can be used in the page.
767
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored Sep 21, 2009
768 All bindings can then be used in the rest of yaws code
769 (in HTML source and within erl tags).
770 In HTML source %%Key%% is expanded to Value and within erl
ab5edc6 @klacke *** empty log message ***
authored Sep 20, 2006
771 tags \fIyaws_api:binding(Key)\fR can be used to extract Value
772 and \fIyaws_api:binding_exists(Key)\fR can be used to check for
e263363 @klacke speling
authored Jul 1, 2008
773 the existence of a binding.
df96b15 @klacke New feature yssi, yaws include
authored May 28, 2004
774
775 .TP
776 \fB{yssi, YawsFile}\fR
777 Include a yaws file. Compile it and expand as if it had
778 occured inline.
779
379666b @klacke documented jockes new bindings feature
authored Jan 27, 2004
780 .TP
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
781 \fB[ListOfValues]\fR
3dee1a5 @capflam Update documentation and manpages accordingly
capflam authored Jan 6, 2012
782 It is possible to return a deep list of the above defined return values. Any
783 occurrence of \fIstreamcontent\fR, \fIstreamcontent_with_timeout\fR,
784 \fIstreamcontent_with_size\fR, \fIstreamcontent_from_pid\fR, \fIget_more\fR,
785 \fIpage\fR or \fIbreak\fR in this list is legal only if it is the last position
786 of the list. If not, remaining values in the list are ignored.
abc3a43 @klacke documented yaws_api
authored Sep 17, 2002
787
788
789
790
791 .SH AUTHOR
792 Written by Claes Wikstrom
793 .SH "SEE ALSO"
794 .BR yaws.conf (5)
795 .BR erl (1)
796
Something went wrong with that request. Please try again.