Roxen.git/
server/
modules/
examples/
location.pike
Branch:
Tag:
Non-build tags
All tags
No tags
2000-07-19
2000-07-19 16:21:23 by Johan Sundström <oyasumi@gmail.com>
eef125b7f6852b6796ae0d6ae753455c3c8b07c2 (
156
lines) (+
156
/-
0
)
[
Show
|
Annotate
]
Branch:
5.2
MODULE_LOCATION refdoc.
Rev: server/modules/examples/location.pike:1.1
1:
+
inherit "module";
+
// All roxen modules must inherit module.pike
-
+
constant cvs_version = "$Id: location.pike,v 1.1 2000/07/19 16:21:23 jhs Exp $";
+
constant module_type = MODULE_LOCATION;
+
constant module_name = "RefDoc for MODULE_LOCATION";
+
constant module_doc = "This module does nothing, but its inlined "
+
"documentation gets imported into the roxen "
+
"programmer manual. You really don't want to "
+
"add this module to your virtual server, promise!";
+
+
// see common_api.pike for further explanations of the above constants
+
+
void create()
+
{
+
defvar("mountpoint",
+
Variable.Location("/dev/urandom/sort/of/", 0,
+
"Mount point",
+
"This is where the module will be inserted "
+
"in the namespace of your server."));
+
}
+
+
mapping|Stdio.File|void find_file( string path, RequestID id )
+
//! The return value is either a <ref>result mapping</ref>, an
+
//! open file descriptor or 0, signifying that your module did not
+
//! handle the request.
+
//!
+
//! This is the fundamental method of all location modules and is, as
+
//! such, required. It will be called to handle all accesses below the
+
//! module's mount point. The path argument contains the path to the
+
//! resource, in the module's own name space, and the id argument
+
//! contains the request information object.
+
//!
+
//! That the path is in the modules name space means that the path
+
//! will only contain the part of the URL after the module's mount
+
//! point. If a module is mounted on <tt>/here/</tt> and a user
+
//! requests <tt>/here/it/is.jpg</tt>, the module will be called with
+
//! a path of <tt>it/is.jpg</tt>. That way, the administrator can set
+
//! the mount point to anything she wants, and the module will keep
+
//! working. Note that changing the mount point to <tt>/here</tt>
+
//! would give the module the path <tt>/it/is.jpg</tt> for that
+
//! request.
+
//!
+
//! A zero return value means that the module could not find the
+
//! requested resource. In that case roxen will move on and try to
+
//! find the resource in in other location modules. Returning -1 means
+
//! that the requested resource is a directory, in which case the
+
//! request will be handled by a directory type module.
+
//!
+
//! If the module could handle the request, the return value is either
+
//! a <ref>response mapping</ref> or a Stdio.File object containing
+
//! the requested file.
+
{
+
return Roxen.http_string_answer(make_random_string( 17, 17 ));
+
}
+
+
string make_random_string(int min_len, int|void max_len)
+
{
+
int length = min_len + (max_len ? random(max_len - min_len)
+
: random(17));
+
return (string)allocate(length, lambda(){ return random(256); })();
+
}
+
+
string query_location()
+
//! Returns the location in the virtual server's where your location
+
//! module is mounted. If you make a location module and leave out
+
//! this method, the default behaviour inherited from module.pike
+
//! will return the value of the module variable 'location'.
+
{
+
return query( "mountpoint" );
+
}
+
+
array(int) stat_file( string path, RequestID id )
+
//! The stat_file() method emulates Pike's <pi>file_stat()</pi>
+
//! method, returning information about a file or directory. path
+
//! is the path to the file or directory in the module's name space,
+
//! id is the request information object.
+
//!
+
//! stat_file() is most commonly used by directory type modules to
+
//! provide informative directory listings, or by the ftp protocol
+
//! module to create directory listings.
+
//!
+
//! The return value it is expected to be an array of integers in the
+
//! following format:
+
//!
+
//! ({ mode, size, atime, mtime, ctime, uid, gid })
+
//!
+
//! <tt>mode</tt> is an integer containing the unix file permissions
+
//! of the file. It can be ignored.
+
//!
+
//! <tt>size</tt> is an integer containing the size of the file, or a
+
//! special value in case the object is not actually a file. Minus two
+
//! means that it is a directory, minus three that it is a symbolic
+
//! link and minus four that it is a device special file. This value
+
//! must be given.
+
//!
+
//! <tt>atime</tt> is a unixtime integer containing the last time the
+
//! file was accessed (seconds since 1970). It can be ignored.
+
//!
+
//! <tt>mtime</tt> is a unixtime integer containing the last time the
+
//! file was modified (seconds since 1970). It will be used to handle
+
//! Last-Modified-Since requests and should be supplied if possible.
+
//!
+
//! <tt>ctime</tt> is a unixtime integer containing the time the file
+
//! was created (seconds since 1970). It can be ignored.
+
//!
+
//! <tt>uid</tt> is an integer containing the user id of this file. It
+
//! will be correlated with the information from the current
+
//! authentification type module, and used by the CGI executable
+
//! support module to start CGI scripts as the correct user. It is
+
//! only necessary for location modules that provide access to a real
+
//! file system and that implement the <ref>real_file()</ref> method.
+
//!
+
//! <tt>gid</tt> is an integer containing the group id of the file. It
+
//! is needed when uid is needed.
+
{
+
return ({ 0775, // mode
+
({ 17, -2 })[random(2)], // size/special
+
963331858, // atime
+
963331858, // mtime
+
963331858, // ctime
+
0, // uid
+
0 /* gid */ });
+
} // Of course, it's typically silly to return something like this.
+
+
string|void real_file( string path, RequestID id )
+
//! This method translates the path of a file in the module's name
+
//! space to the path to the file in the real file system. path
+
//! is the path to the file in the module's name space, id is the
+
//! request information object.
+
//!
+
//! If the file could not be found, or the file doesn't exist on a
+
//! real file system, zero should be returned. Only location modules
+
//! that access server files from a real file system need implement
+
//! this method. See also the <ref>stat_file()</ref> method.
+
{}
+
+
array(string)|void find_dir( string path, RequestID id )
+
//! The find_dir() returns a directory listing; an array of strings
+
//! containing the names of all files and directories in this
+
//! directory. The path parameter is the path to the directory, in the
+
//! module's name space, id is the request information object.
+
//!
+
//! This method is usually called because a previous call to
+
//! find_file() returned that this path contained a directory and a
+
//! directory type module is right now trying to create a directory
+
//! listing of this directory. Note that it is possible that the
+
//! find_dir() is called in several location modules, and that the
+
//! actual directory listing shown to the user will be the
+
//! concatenated result of all those calls.
+
//!
+
//! To find information about each entry in the returned array the
+
//! <ref>stat_file()</ref> is used.
+
{
+
return allocate(random(47)+11, make_random_string)(4, 71);
+
}
Newline at end of file added.