httpd::url(n) 1.2 "Tcl Web Server"
httpd::url - Url dispatching
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
Interface to protocol engines
Database manipulation
Support for domain handlers
SEE ALSO
KEYWORDS
COPYRIGHT
package require httpd::url ?1.2?
The package httpd::url is a companion package to package
httpd and required by it. It provides the database mapping
from urls in http requests to the tcl commands implementing them, and
the commands to manipulate said database.
The main concept of this package is the domain. A domain is
described by an url prefix and handled by single tcl command, the
domain handler. In other words, a domain is an url tree,
i.e. an url directory and all urls inside of that directory
[*]. These urls are handled by the associated tcl command.
[*] There is one exception to this definition. It is possible,
actually allowed, to define a domain whose url prefix is inside of
another domain. All the urls in this sub-domain do not belong
to the enclosing domain anymore.
The commands in this section are called by the package httpd
as part of the url dispatching process. They are public for use in
implementations of the HTTP protocol different from httpd.
- Url_Dispatch sock
-
Dispatches the request currently waiting on the connection sock
to the associated domain handler. The http protocol engine has already
read the HTTP headers and placed into the connection status
array. It may have read all posted data before invoking the domain
handler. This is done if and only if requested by the domain.
Before the domain handler is invoked all registered access control
callbacks are run. If any of them denies the request an http error
reply is sent back and the domain handler is not invoked.
- Url_DeferredDispatch prefix suffix sock varname errmsg
-
Bare bones invocation of the domain handler for the url (prefix
and suffix) in the current request waiting on the connection
sock. Executed after all posted data was read by this
package. If the error message in errmssg is not empty the
request will be aborted, using this message in the generated http
error reply, and the domain handler is not invoked.
This command does not perform access control. It assumes
that this has already been done before.
- Url_PostHook sock length
-
Backdoor hack for Url_DecodeQuery compatibility. Remembers the
current connection sock and length of pending data so that
Url_DecodeQuery can read the post data if it has not already
been read by the time it is called. Setting a length of 0
deactivates the remembered information.
The commands in this section are for use by domain implementations, to
manage their presence in the dispatcher database.
- Url_PrefixInstall prefix command (option value)...
-
Adds a domain described by the url prefix to the database. After
the call any access to an url in the domain will cause this package to
call the associated domain handler, the command prefix command.
The domain handler is called with one additional argument, the channel
handle sock of the connection which made the request for an url
in the domain. The state data of this connection is available through
as described in httpd.
The allowed options and their meanings are:
- readpost
-
takes a boolean value. If set to true (the default), then this
package will retrieve post data before calling the domain
handler. Else the domain handler is responsible for reading any post
data the browser might have sent.
- callback
-
takes a command prefix. It is invokes whenever a request in the domain
was completed, with or without error. This allows the domain handler
to cleanup any resources it might have allocated for the request at
that time, like aborting a long running server operation.
The callback will be invoked with two additional arguments, sock
and a string, in this order. The string can be empty. If the string is
not empty it will contain an error message.
- thread
-
takes a boolean value. If set to true the domain handler will
run in its own thread. The default is false. In a server which
is not thread-enabled this option will be ignored and the value always
forced to false.
- Url_PrefixRemove prefix
-
Remove the domain described by the url prefix from the
database. After the call all urls in the domain may fall into a
different domain and will be handled by that domain handler. If they
don't fall into a different domain they will cause the generation of
http error replies when accessed from a browser.
- Url_AccessInstall proc
-
Adds the command with name proc at the end of the list of access
control callback managed by the package. After the call the command
will be invoked for all incoming requests. It can grant access, deny
it, or announce that it doesn't care. When calling the command
multiple times for the same proc only the first call will update
the package. All others will be ignored.
The register callback is invoked with two additional arguments, the
channel handle of the connection, and the url which is accessed. It
has to return one of
- ok
-
Access is granted.
- denied
-
Access is denied. It is recommended that the callback generates the
appropriate http error reply. However the system will work even if it
does not, by generating its own reply when it finds that the callback
did not.
- return
-
See denied.
- skip
-
The callback does not care about this url.
The package invokes the callbacks from first registered to last and
will not stop as long as the callbacks return skip. Any tcl
error thrown by a callback wil cause url processing to abort.
- Url_AccessInstallPrepend proc
-
See Url_AccessInstall, except that the command prefix is added
at the front of the list, causing it to be called before anything else
registered before.
- Url_AccessUnInstall proc
-
Removes the command prefix proc from the list of access control
callbacks managed y the package. If the command prefix could not be
found this command will do nothing.
- Url_PrefixMatch url prefixVar suffixVar
-
Finds the best-matching domain for the url and stores the url
prefix of the domain into the variable prefixVar, and the
remainder of the url (i.e. everything after the prefix) into the
variable suffixVar.
The best-matching domain is the domain with the longest prefix which
still matches the specified url, path-component wise. In other words,
the prefix /tcl will not match the url /tclhttpd/foo.
- Url_PrefixExists prefix
-
Checks if a domain was registerd for prefix. The result is a
boolean value where true signals that a domain was registered
indeed.
- Url_Handle cmd sock
-
This used to cache the domain handler command cmd for the url on
the connection sock before invoking it. Nowadays it only invokes
the command.
- Url_UnCache sock ?force?
-
Removes the domain handler command for the url on the connection
sock from the domain handler cache. If the argument force
is present and set then there will be no special case for the internal
redirect hack.
The commands of this section are for use by domain implementations, to
aid the tasks of url and request processing.
- Url_Unwind sock ei ec
-
Performs common error handling after the current request on the
connection sock was aborted with a tcl error. The two arguments
ei and ec contain the errorInfo and errorCode information
from the interpreter.
- Url_PathCheck urlsuffix
-
Validates the pathname urlsuffix and makes sure that it doesn't
sneak out of its domain via ..-trickery. Either raises an
error, or returns a list of components in the pathname.
- Url_DecodeQuery query (option value)...
-
A small wrapper around Url_DecodeQueryOnly. Ensures that the
POST data on the connection set via Url_PostHook is read before
handing over to the decoder. query is the name of the internal
variable the data is stored into. The options coming after this
information are simply handed over to the actual decoder, i.e.
Url_DecodeQueryOnly.
Accepted options:
- type
-
Forces a specific type for the query data. Defaults to
application/x-www-urlencoded. If no decoder for that type is
present the system is forced back to the default.
- qualifiers
-
Empty by default. Transformed into the second argument of the type
specific decoders, see below.
- Url_DecodeQueryOnly query (option value)...
-
Decodes the POST data stored in the variable query. It does
this by dispatching to the appropriate type-specific decoder command
(see below). See Url_DecodeQuery for the accepted options.
- Url_DecodeQuery_multipart/form-data query qualifiers
-
Decoder for query data of type multipart/form-data.
Essentially has to parse the MIME document in query, with
guidance by the dictionary qualifiers.
Used keys are
- boundary
-
The boundary line used to separate the MIME parts. Required.
Returns a dictionary mapping from the names of the uploaded files
to their contents.
- Url_DecodeQuery_application/x-www-urlencoded query qualifiers
-
Decoder for application/x-www-urlencoded query data.
The argument qualifiers is not used. Returns a dictionary
mapping from the query keys to the query values.
- Url_DecodeQuery_application/x-www-form-urlencoded query qualifiers
-
Decoder for application/x-www-form-urlencoded query
data. An alias of Url_DecodeQuery_application/x-www-urlencoded.
- Url_QuerySetup sock
-
Reads the POST data on the connection sock and initializes the
ncgi package with it, for convenient access by URL
implementations later on.
- Url_ReadPost sock varname
-
Synchronously reads the POST data on the connection sock and
stores it into the variable varname.
- Url_DecodeMIMEField type
-
Decodes a mime type. Returns a list containing 3 elements, the major
and minor type, and its qualifiers, a dictionary, in this order.
- Url_Decode data
-
Decodes a single string in x-www-urlencoded form.
The decoded string is returned as the result of the command.
- Url_Encode string
-
Encodes a string for use in x-www-urlencoded query data. The
encoded string is returned as the result of the command.
- Url_IsLinkToSelf url
-
Compares the url to the url of the current page.
The result of the comparison is a boolean flag.
If they seem to be the same true will be returned, else
false.
httpd, httpd::counter, httpd::doc_error, httpd::threadmgr, httpd::utils
domain, url, url dispatch, web server
Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>