Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 745 lines (573 sloc) 20.772 kb
108bbc9 @klacke ""
authored
1 .TH YAWS_API "5" "" "" "User API"
abc3a43 @klacke documented yaws_api
authored
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
8
abc3a43 @klacke documented yaws_api
authored
9 .PP
e263363 @klacke speling
authored
10 This is the api available to yaws web server programmers. The Erlang
abc3a43 @klacke documented yaws_api
authored
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
16 being delivered from the server. We give a very simple example here
e263363 @klacke speling
authored
17 to show the basic idea. Imagine the following HTML code:
abc3a43 @klacke documented yaws_api
authored
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
46 clisock, %% the socket leading to the peer client
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
47 client_ip_port, %% {ClientIp, ClientPort} tuple
0be3c7e @klacke untabified all of yaws
authored
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
62 %% http://some.host/a/b/c.yaws/d/e
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
63 }).
abc3a43 @klacke documented yaws_api
authored
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
70
abc3a43 @klacke documented yaws_api
authored
71 -record(headers, {
8d5aa60 @klacke ""
authored
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
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
110 htmlized.
abc3a43 @klacke documented yaws_api
authored
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
123 \fBhtmlize(Binary | List | Char)\fR
124 Htmlize an IO list object.
abc3a43 @klacke documented yaws_api
authored
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
135 from the browser we can call:
abc3a43 @klacke documented yaws_api
authored
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
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
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
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
166 a URL to ourselves.
883fa5a @klacke added redirect_self to yaws_api
authored
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 }).
178 .nf
179
180
181 .TP
abc3a43 @klacke documented yaws_api
authored
182 \fBget_line(String)\fR
d02b965 @klacke qnx port + docs overhaul by cschatz@networkadvantage.biz
authored
183 This function is convenient when getting \\r\\n terminated lines
abc3a43 @klacke documented yaws_api
authored
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
196 When a yaws function needs to deliver chunks of data which it gets
abc3a43 @klacke documented yaws_api
authored
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
200 YawsPid is the process identifier of the yaws process delivering the original
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
201 .yaws file. That is self() in the yaws code.
ebb94d8 @klacke 1.54
authored
202 The Pid must typically be passed (somehow) to the producer of the stream.
abc3a43 @klacke documented yaws_api
authored
203
a39fab8 @klacke added example docs on how to stream data
authored
204 .TP
205 \fBstream_chunk_deliver_blocking(YawsPid, Data)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
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
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
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
250 data delivery.
251
252 .TP
abc3a43 @klacke documented yaws_api
authored
253 \fBparse_query(Arg)\fR
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
254 This function will parse the query part of the URL.
abc3a43 @klacke documented yaws_api
authored
255 It will return a {Key, Value} list of the items supplied in the query
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
256 part of the URL.
257
258 .TP
259 \fBqueryvar(Arg, VarName)\fR
260 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
261 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
262 querypart of the url. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/ya...
authored
263 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
264 return \fI{Val1, ....}\fR.
abc3a43 @klacke documented yaws_api
authored
265
266
267 .TP
c4523b3 @klacke ""
authored
268 \fBparse_post(Arg)\fR
abc3a43 @klacke documented yaws_api
authored
269 This function will parse the POST data as supplied from the browser.
270 It will return a {Key, Value} list of the items set by the browser.
271
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
272 .TP
273 \fBpostvar(Arg, VarName)\fR
274 This function is automatically included from yaws_api in all
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
275 .yaws pages. It is used to search for a variable in the
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
276 POSTed data from the client. Returns {ok, Val} or undefined.
54eff96 @klacke git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/ya...
authored
277 If a variable is defined multiple times, the function may also
b732bd1 @klacke doc patch from kevingrimes
authored
278 return \fI{Val1, ....}\fR.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
279
c9778e0 @klacke added support for 2 additional configure
authored
280 .TP
281 \fBgetvar(Arg, VarName)\fR
282 This function looks at the HTTP request method from the
283 client and invokes postvar/2 if it is a POST from the client
284 and queryvar/2 if it is a GET request from the client.
285
c4523b3 @klacke ""
authored
286
287 .TP
288 \fBparse_multipart_post(Arg)\fR
289
abc3a43 @klacke documented yaws_api
authored
290 If the browser has set the Content-Type header to the value
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
291 "multipart/form-data", which is the case when the browser
abc3a43 @klacke documented yaws_api
authored
292 wants to upload a file to the server the following happens:
293
294
295 If the function returns \fB{result, Res}\fR no more data
296 will come from the browser.
297
298 If the function returns \fB{cont, Cont, Res}\fR the browser
299 will supply more data. (The file was to big to come in one read)
300
301 This indicates that there is more data to come and the out/1 function
302 should return {get_more, Cont, User_state} where User_state might
303 usefully be a File Descriptor.
304
305
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
306 The Res value is a list of either:
abc3a43 @klacke documented yaws_api
authored
307 \fB{header, Header}\fR | \fB{part_body, Binary}\fR | \fB{body, Binary}\fR
308
309
310 Example usage could be:
311 \fI
312 .nf
313 <erl>
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
314
abc3a43 @klacke documented yaws_api
authored
315 out(A) ->
c4523b3 @klacke ""
authored
316 case yaws_api:parse_multipart_post(A) of
abc3a43 @klacke documented yaws_api
authored
317 {cont, Cont, Res} ->
318 St = handle_res(A, Res),
319 {get_more, Cont, St};
320 {result, Res} ->
321 handle_res(A, Res),
322 {html, f("<pre>Done </pre>",[])}
323 end.
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
324
abc3a43 @klacke documented yaws_api
authored
325 handle_res(A, [{head, Name}|T]) ->
326 io:format("head:~p~n",[Name]),
327 handle_res(A, T);
328 handle_res(A, [{part_body, Data}|T]) ->
329 io:format("part_body:~p~n",[Data]),
330 handle_res(A, T);
331 handle_res(A, [{body, Data}|T]) ->
332 io:format("body:~p~n",[Data]),
333 handle_res(A, T);
334 handle_res(A, []) ->
335 io:format("End_res~n").
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
336
abc3a43 @klacke documented yaws_api
authored
337 </erl>
338 .fi
339 \fR
340
341
342
343 .TP
87b1456 @klacke wrote the shopppingcart example
authored
344 \fBnew_cookie_session(Opaque)\fR
abc3a43 @klacke documented yaws_api
authored
345 Create a new cookie based session, the yaws system will set the
e263363 @klacke speling
authored
346 cookie. The new random generated cookie is returned from this
87b1456 @klacke wrote the shopppingcart example
authored
347 function. The Opaque argument will typically contain user data
e263363 @klacke speling
authored
348 such as user name and password
abc3a43 @klacke documented yaws_api
authored
349
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
350 .TP
351 \fBnew_cookie_session(Opaque, TTL)\fR
352 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 when...
authored
353 overriding the system specified time-out value.
354
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
355 .TP
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
356 \fBnew_cookie_session(Opaque, TTL, CleanupPid)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
357 As above, but also sends a message
6964fff @klacke modified patch by Robert David to add a hook to yaws session server when...
authored
358 \fI{yaws_session_end, Reason, Cookie, Opaque}\fR to the provided CleanuPid where
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
359 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 when...
authored
360 is the HTTP cookie as returned by \fInew_session()\fR and the Opaque
361 is the user provided Opaque parameter to \fInew_session()\fR.
362 The purpose of the feature is to cleanup resources assigned to the session.
363
13b21a9 @klacke yaws_session_server ttl patch from Rob.Schmersel
authored
364
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
365 .TP
87b1456 @klacke wrote the shopppingcart example
authored
366 \fBcookieval_to_opaque(CookieVal)\fR
abc3a43 @klacke documented yaws_api
authored
367
368 .TP
369 \fBprint_cookie_sessions() \fR
370
87b1456 @klacke wrote the shopppingcart example
authored
371
372 .TP
373 \fBreplace_cookie_session(Cookie, NewOpaque)\fR
374
abc3a43 @klacke documented yaws_api
authored
375 .TP
87b1456 @klacke wrote the shopppingcart example
authored
376 \fBdelete_cookie_session(Cookie)\fR
abc3a43 @klacke documented yaws_api
authored
377
378
50a7ab2 @klacke added support/docs for embedded mode
authored
379 .TP
380 \fBsetconf(Gconf, Groups)\fR
381 This function is intended for embedded mode in yaws. It makes it possible
382 to load a yaws configuration from another data source than /etc/yaws.conf, such
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
383 as a database.
50a7ab2 @klacke added support/docs for embedded mode
authored
384 If yaws is started with the environment \fI{embedded, true}\fR, yaws will
385 start with an empty default configuration, and wait for some other
386 program to execute a \fIsetconf/2\fR
387 The Gconf is a \fI#gconf{}\fR record and the Group variable is
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
388 a list of lists of \fI#sconf{}\fR records. Each sublist must
50a7ab2 @klacke added support/docs for embedded mode
authored
389 contain \fI#sconf{}\fR records with the same IP/Port listen address.
e263363 @klacke speling
authored
390 To create a suitable initial #gconf{} record see the code in
391 yaws_config:make_default_gconf/2. Especially the \fIyaws_dir\fR parameter
392 is important to get right.
abc3a43 @klacke documented yaws_api
authored
393
2b9f008 @klacke ""
authored
394
395 .TP
396 \fBurl_decode(Str)\fR
e263363 @klacke speling
authored
397 Decode url-encoded string. A URL encoded string is a string where
2b9f008 @klacke ""
authored
398 all alfa numeric characters and the the character _ are preserved
399 and all other characters are encode as "%XY" where X and Y are the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
400 hex values of the least respective most significant 4 bits in the 8 bit
2b9f008 @klacke ""
authored
401 character.
402
403 .TP
404 \fBurl_encode(Str)\fR
405 Url-encodes a string. All URLs in HTML documents must be URL encoded.
406
407
814eb04 @klacke ""
authored
408 .TP
8d5aa60 @klacke ""
authored
409 \fBreformat_header(H)\fR
e263363 @klacke speling
authored
410 Returns a list of reformatted header values from a #header{}
814eb04 @klacke ""
authored
411 record. The return list is suitable for retransmit.
412
dc00e52 @klacke postvar bug by hal snyder, added yaws_api:query_url/1 added the id suppo...
authored
413 .TP
414 \fBrequest_url(ARG)\fR
415 Return the url as requested by the client. Return value
416 is a #url{} record as defined in yaws_api.hrl
417
2b9f008 @klacke ""
authored
418
8da2b3a @klacke parse_url
authored
419 .TP
420 \fBparse_url(Str)\fR
421 Parse URL in a string, returns a #url record
422
423 .TP
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
424 \fBformat_url(UrlRecord)\fR
8da2b3a @klacke parse_url
authored
425 Takes a #url record a formats the Url as a string
426
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
427 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
428 \fBcall_cgi(Arg, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
429 Calls an executable CGI script,
430 given by its full path. Used to make `.yaws' wrappers for CGI
431 programs. This function usually returns \fIstreamcontent\fR.
432
433 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
434 \fBcall_cgi(Arg, Exefilename, Scriptfilename)\fR
42ab990 @carsten3347 Make call_cgi available in yaws_api.
carsten3347 authored
435 Like before, but
436 calls \fIExefilename\fR to handle the script. The file name of the
437 script is handed to the executable via a CGI meta variable.
8da2b3a @klacke parse_url
authored
438
f3deff2 @klacke added a dir_listing function in yaws_api
authored
439 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
440 \fBcall_fcgi_responder(Arg)\fR
2fa66b0 @klacke cgi support
authored
441 Calls a FastCGI responder.
442 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
443 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored
444 Used to make `.yaws' wrappers for FastCGI responders.
445 Returns the same return values as out/1 (see below).
446
447 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
448 \fBcall_fcgi_responder(Arg, Options)\fR
2fa66b0 @klacke cgi support
authored
449 Same as above, but Options overrides the defaults from the server
450 configuration:
451
452 \fI
453 .nf
454 Options = [Option]
455 Option -- one of the following:
456 .fi
457 \fR
458
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
459 \fB{app_server_host, string() | ip_address()}\fR
2fa66b0 @klacke cgi support
authored
460 The hostname or the IP address of the FastCGI application server.
461
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
462 \fB{app_server_port, 0..65535}\fR
2fa66b0 @klacke cgi support
authored
463 The TCP port number of the FastCGI application server.
464
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
465 \fB{path_info, string()}\fR
2fa66b0 @klacke cgi support
authored
466 Override default pathinfo in Arg#arg.pathinfo.
467
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
468 \fB{extra_env, ExtraEnv}\fR
2fa66b0 @klacke cgi support
authored
469 Override default pathinfo in Arg#arg.pathinfo.
470
471 \fI
472 .nf
473 ExtraEnv = [Var]
474 Var = {Name, Value}
475 Name = string()
476 Value = string()
477 .fi
478 \fR
479
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
480 \fB{trace_protocol, boolean()}\fR
2fa66b0 @klacke cgi support
authored
481 Enable or disable tracing of FastCGI protocol messages as info
482 log messages.
483
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
484 \fB{log_app_error, boolean()}\fR
2fa66b0 @klacke cgi support
authored
485 Enable or disable logging of application error messages: output
486 to stderr and non-zero exit value.
487
488 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
489 \fBcall_fcgi_authorizer(Arg) -> {allowed, Variables} | {denied, Out}\fR
2fa66b0 @klacke cgi support
authored
490 Calls a FastCGI authorizer.
491 The address and port of the FastCGI application server are taken
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
492 from the server configuration (see yaws.conf).
2fa66b0 @klacke cgi support
authored
493 Used to make `.yaws' wrappers for FastCGI authorizers.
494 Variables contains the values of the variables returned by the FastCGI
495 application server in the "Variable-XXX: YYY" headers.
496
497 \fI
498 .nf
499 Out -- See return values for out/1 below
500 Variables = {Name, Value}
501 Name = string()
502 Value = string()
503 .fi
504 \fR
505
506 .TP
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
507 \fBcall_fcgi_authorizer(Arg, Options)\fR
2fa66b0 @klacke cgi support
authored
508 Same as above, but Options overrides the defaults from the server
509 configuration. See call_fcgi_responder/2 above for a description
510 of Options.
511
512 .TP
f3deff2 @klacke added a dir_listing function in yaws_api
authored
513 \fBdir_listing(Arg)\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
514 Perform a directory listing. Can be used in special directories
f3deff2 @klacke added a dir_listing function in yaws_api
authored
515 when we don't want to turn on dir listings for the entire server.
516 Always returns ok.
8da2b3a @klacke parse_url
authored
517
abc3a43 @klacke documented yaws_api
authored
518 .SH RETURN VALUES from out/1
519 .PP
520 The out/1 function can return different values to control the behavior
521 of the server.
522
523 .TP
524 \fB{html, DeepList}\fB
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
525 This assumes that DeepList is formatted HTML code.
abc3a43 @klacke documented yaws_api
authored
526 The code will be inserted in the page.
527
528 .TP
529 \fB{ehtml, Term}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
530 This will transform the erlang term Term into a
abc3a43 @klacke documented yaws_api
authored
531 stream of HTML content. The basic syntax of Term
532 is
533
534 \fI
535 .nf
536 EHTML = [EHTML] | {Tag, Attrs, Body} | {Tag, Attrs} | {Tag} |
537 binary() | character()
8d5aa60 @klacke ""
authored
538 Tag = atom()
abc3a43 @klacke documented yaws_api
authored
539 Attrs = [{Key, Value}] or {EventTag, {jscall, FunName, [Args]}}
8d5aa60 @klacke ""
authored
540 Key = atom()
abc3a43 @klacke documented yaws_api
authored
541 Value = string()
542 Body = EHTML
543 .fi
544 \fR
545
546
ebb94d8 @klacke 1.54
authored
547 For example, \fI{p, [], "Howdy"}\fR expands into
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
548 "<p>Howdy</p> and
abc3a43 @klacke documented yaws_api
authored
549
550 \fI
551 .nf
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
552 {form, [{action, "a.yaws"}],
abc3a43 @klacke documented yaws_api
authored
553 {input, [{type,text}]}}
554
555 .fi
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
556 \fR
abc3a43 @klacke documented yaws_api
authored
557
558 expands into
559
560 \fI
561 .nf
562 <form action="a.yaws"
df99ebe @klacke *** empty log message ***
authored
563 <input type="text">
564 </form>
abc3a43 @klacke documented yaws_api
authored
565 .fi
566 \fR
567
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
568 It may be more convenient to generate erlang tuples
abc3a43 @klacke documented yaws_api
authored
569 than plain html code.
570
571 .TP
572 \fB{content, MimeType, Content}\fR
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
573 This function will make the web server generate
abc3a43 @klacke documented yaws_api
authored
574 different content than HTML. This return value is only allowed
575 in a yaws file which has only one <erl> </erl> part and no
576 html parts at all.
577
578
579 .TP
580 \fB{streamcontent, MimeType, FirstChunk}\fR
581 This return value plays the same role as the \fIcontent\fR return
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
582 value above.
e2f272a @klacke explicit support for content_length
authored
583
abc3a43 @klacke documented yaws_api
authored
584 However it makes it possible to stream data to the client
585 if the yaws code doesn't have access to all the data in one go. (Typically
586 if a file is very large or if data arrives from back end servers on the network.
587
588 .TP
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
589 \fB{streamcontent_with_timeout, MimeType, FirstChunk, Timeout}\fR
590 Similar to above, but with an explicit timeout. The deafult timeout
591 is 30 secs. I.e if the application fails to deliver data to the
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
592 Yaws process, the streaming will stop. This is often not the
3f6194f @klacke stream content with a timeout patch from Davide Marques
authored
593 desired behaviour in Comet/Ajax applications. It's possible to
594 provide 'infinity' as timeout.
595
596 .TP
abc3a43 @klacke documented yaws_api
authored
597 \fB{header, H}\fR
e2f272a @klacke explicit support for content_length
authored
598 Accumulates a HTTP header. The trailing CRNL which is supposed
ebb94d8 @klacke 1.54
authored
599 to end all HTTP headers must NOT be added. It is added by the server.
e2f272a @klacke explicit support for content_length
authored
600 The following list of headers are given special treatment.
601
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
602 \fI{connection, What}\fR
e2f272a @klacke explicit support for content_length
authored
603
604 This sets the connection header. If \fIWhat\fR is the special value
605 \fI"close"\fR, the connection will be closed once the yaws page is delivered
606 to the client.
607
608 \fI{location, Url}\fR
609
610 Sets the Location: header. This header is typically combined with
611 the \fI{status, 302}\fR return value.
612
613 \fI{cache_control, What}\fR
614
615 Sets the Cache-Control: header.
616
617 \fI{set_cookie, Cookie}\fR
618
e263363 @klacke speling
authored
619 Prepends a a Set-Cookie: header to the list of previously
e2f272a @klacke explicit support for content_length
authored
620 set Set-Cookie: headers.
621
622 \fI{content_type, MimeType}\fR
623
624 Sets the Content-Type header.
625
626 \fI{content_length, Len}\fR
627
628 Normally yaws will ship Yaws pages using Transfer-Encoding: chunked. This
629 is because we generally can't know how long a yaws page will be. If we for
630 some reason want to force a Content-Length: header (and we actually do
631 know the length of the content, we can force yaws to not ship the
632 page chunked.
633
634
635 All other headers must be added using the normal HTTP syntax.
636 Example:
637
638 {header, "My-X-Header: gadong"}
639
640
641
abc3a43 @klacke documented yaws_api
authored
642
643 .TP
644 \fB{allheaders, HeaderList}\fB
645 Will clear all previously accumulated headers and replace them.
646
647
648 .TP
649 \fB{status, Code}\fR
650 Will set another HTTP status code than 200.
651
652
653 .TP
654 \fBbreak\fR
655 Will stop processing of any consecutive chunks of erl or html code
656 in the yaws file.
657
658 .TP
659 \fBok\fR
660 Do nothing.
661
662
663 .TP
664 \fB{redirect, Url}\fR
665 Erase all previous headers and accumulate a single
666 Location header. Set the status code.
667
668 .TP
669 \fB{redirect_local, Path}\fR
670 Does a redirect to the same Scheme://Host:Port/Path as we
671 currently are executing in.
672
673 .TP
674 \fB{get_more, Cont, State}\fR
675 When we are receiving large POSTs we can return this value
676 and be invoked again when more Data arrives.
677
678
679 .TP
c837288 @klacke page retval
authored
680 \fB{page, Page}\fR
681 Make Yaws return a different page than the one being
682 requested.
683
684
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
685 .TP
686 \fB{page, {Options, Page}}\fR
687 Like the above, but supplying an additional deep list of options. For
688 now, the only type of option is \fI{header, H}\fR with the effect of
689 accumulating the HTTP header \fIH\fR for page \fIPage\fR.
690
c837288 @klacke page retval
authored
691
692 .TP
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
693 \fB{ssi, File, Delimiter, Bindings}\fR
694 Server side include File and macro expansion in File.
e263363 @klacke speling
authored
695 Each occurrence of a string, say "xyz", inside File which
696 is inside Delimiters is replaced with the corresponding
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
697 value in Bindings.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
698
699 Example:
700 Delimiter = %%
701
702 File contains the string .... %%xyz%% .....
703
704 Bindings contain the tuple {"xyz", "Dingbat"}
705
e263363 @klacke speling
authored
706 The occurrence of %%xyz%% in File will be replaced with "Dingbat"
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
707 in the Server side included output.
708
709 The {ssi, File, Delimiter, Bindings} statement can also
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
710 occur inside a deep ehtml structure.
b2d5a00 @klacke postvar(), queryvar(), ssi docs
authored
711
712
713 .TP
379666b @klacke documented jockes new bindings feature
authored
714 \fB{bindings, [{Key1, Value2}, {Key2, Value2} .....]}\fR
715 Establish variable bindings that can be used in the page.
716
aa32fa0 @vinoski document streamcontent process delivery functions
vinoski authored
717 All bindings can then be used in the rest of yaws code
718 (in HTML source and within erl tags).
719 In HTML source %%Key%% is expanded to Value and within erl
ab5edc6 @klacke *** empty log message ***
authored
720 tags \fIyaws_api:binding(Key)\fR can be used to extract Value
721 and \fIyaws_api:binding_exists(Key)\fR can be used to check for
e263363 @klacke speling
authored
722 the existence of a binding.
df96b15 @klacke New feature yssi, yaws include
authored
723
724 .TP
725 \fB{yssi, YawsFile}\fR
726 Include a yaws file. Compile it and expand as if it had
727 occured inline.
728
379666b @klacke documented jockes new bindings feature
authored
729 .TP
abc3a43 @klacke documented yaws_api
authored
730 \fB[ListOfValues]\fR
0d99c12 @carsten3347 Changes to arg record, {page, {Options, Page}}, comment on returning a
carsten3347 authored
731 It is possible to return a deep list of the above defined
732 return values. Any occurrence of \fIstream_content\fR, \fIget_more\fR
733 or \fIpage\fR in this list is legal only if it is the last position of
734 the list.
abc3a43 @klacke documented yaws_api
authored
735
736
737
738
739 .SH AUTHOR
740 Written by Claes Wikstrom
741 .SH "SEE ALSO"
742 .BR yaws.conf (5)
743 .BR erl (1)
744
Something went wrong with that request. Please try again.