Response data handling

Response data handling
Prev		Next

Websh can send output to any Tcl channel and to global variables (web::put). Optionally, data is scanned for Tcl code before it is output to a channel (web::putx). Websh manages response objects that are related to Tcl channels and are identified using the name of the corresponding Tcl channel. Configuration is achieved with web::response.

web::response

web::response

web::response ?option?

web::response ?subcommand? args

Subcommands are -select, -set, -lappend, -names, -count, -unset, -reset, -resetall, and -flush. Options are -sendheader, -httpresponse, and -bytessent.

Selects the default response object and sets and accesses properties of the response object, and returns the name of the response object.

web::response: Returns the name of the currently selected response object.
web::response -select ?#?channelName: Selects channelName as new response object. If the channelName is prepended by a #, it refers to a global variable named channelName.
web::response -set key ?value?: Sets property key to value, or returns current value if value is omitted. The keys are names of HTTP header fields (do not include ':' at the end of the header field name) and value the corresponding value of the field (like Content-Type) and their values (like text/html).
Example:
web::response -set Content-Type text/plain.
web::response -names: Returns the list of known keys.
web::response -count key: Returns number of items in list of key.
web::response -unset ?key?: Deletes the value of key, if key is given, or all keys.
web::response -sendheader ?boolean?: Sets or gets the sendheader flag which indicates and controls whether the HTTP headers have been or should be sent. It is initially set to 1 and set to 0 after the first call of web::put or web::putx. If boolean is omitted, returns the current value.
web::response -httpresponse ?value?: Sets or gets the HTTP response like "HTTP/1.0 200 OK" for the given (or default) channel. If no value given, returns the the current HTTP response set. In the case of the Apache module mod_websh, Apache replaces the protocol "HTTP/??" in the reponse with "HTTP/1.1".
Note: Depending on the CGI implementation of your web server, this does not always work. A working alternative for newer versions of Apache is to set a Status header in the response as follows:
web::response -set Status "400 Bad Request".
web::response -bytessent: Returns the number of bytes that have already been sent to this channel.
web::response -flush: Flushes the response channel immediately. In CGI mode this flushes the Tcl channel buffer. Under mod_websh it additionally pushes the pending output through Apache's output filter chain to the network (ap_rflush), which makes real-time streaming such as Server-Sent Events possible. See web::sseSend.
web::response -reset: Resets the 'sendheader' flag for the channel to true, the HTTP response to the default "HTTP/?? 200 OK", removes any HTTP headers set, and resets the names of the query string parameters for the timestamp and the command to their default values ("t" and "cmd", respectively).
web::response -resetall: Performs a web::response -reset on all registered channels.

Example 10. web::response

% web::response
stdout
% web::response -select stderr
stdout
% web::response
stderr
% web::response -sendheader
1
% web::response -names
Content-Type Generator
% web::response Content-Type
text/html
% web::response -bytessent
0
% web::response -set Set-Cookie "my cookie that contains data"
% web::put "Hello, world\n"
Content-Type: text/html
Set-Cookie: my cookie that contains data
Generator: websh3.6.0

Hello, world
%

web::put

web::put ? ?#? channel ? text

Sends output to a Tcl channel. No newline is added to output. If ?channel? is ommitted, output is sent to the current default channel. The default channel can be changed with web::response -select ?#?channel. The optional hash ("#") denotes that output should be sent to a global variable named channel instead of a Tcl channel.

web::putx

web::putx ? ?#? channel ? text

Writes text to the specified channel. Code in curly brackets is eval'd, unless the brackets are escaped by "\". These markup characters '{...}' can be changed to '<? ... ?>' with 'web::config putxmarkup tag'. The optional hash ("#") denotes that output should be sent to a global variable named channel instead of a Tcl channel.

web::putxfile

web::putxfile ? ?#? channel ? file ?msg?

Like web::putx, but takes input from a file.

Returns 0 on success, 1 otherwise. If an error occurs, an error message is written to msg. If only two arguments are passed, then channel takes precedence. The optional hash ("#") denotes that output should be sent to a global variable named channel instead of a Tcl channel.

web::sseStart

web::sseStart

Starts a Server-Sent Events (SSE) response. Sets the response headers Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive and X-Accel-Buffering: no, and disables buffering on the response channel. Use web::sseSend to emit events afterwards.

web::sseSend

web::sseSend data ?event? ?id? ?retry?

Sends one SSE event and flushes the response via web::response -flush. Multiline data is split on newlines and emitted as one data: line per segment; the event is terminated with a blank line. The optional arguments emit event:, id: and retry: fields.

For keepalive in long-running connections send an SSE comment (a line starting with ":") followed by web::response -flush; comments are ignored by browsers but prevent proxy timeouts. See examples/sse/ for a complete server/client example.

Prev		Next
Request data handling	Home	Logging