See
PublishedAPI for packages intended to be used by Plugin and Contrib authors, or
browse all packages.
See also
Developing plugins,
Developer's Bible,
Technical Overview
internal package
Foswiki::Engine
The engine class is a singleton that implements details about Foswiki's
execution mode. This is the base class and implements basic behavior.
Each engine should inherits from this and overload methods necessary
to achieve correct behavior.
ClassMethod
new() → $engine
Constructs an engine object.
ObjectMethod
run()
Start point to Runtime Engines.
ObjectMethod
prepare() → $req
Initialize a
Foswiki::Request object by calling many preparation methods
and returns it, or a status code in case of error.
ObjectMethod
prepareConnection( $req )
Abstract method, must be defined by inherited classes.
Should fill remoteAddr, method and secure fields of
$req
object.
ObjectMethod
prepareQueryParameters( $req, $queryString )
Populates $req with parameters extracted by parsing a
byte string (which may include url-encoded characters, which may
in turn be parts of utf8-encoded characters).
Note that parameter names and values are decoded to unicode.
Abstract method, must be defined by inherited classes.
Should fill $req's headers and remoteUser fields.
ObjectMethod
preparePath( $req )
Abstract method, must be defined by inherited classes.
Should fill $req's uri and pathInfo fields.
ObjectMethod
prepareCookies( $req )
Should fill $req's cookie field. This method take cookie data from
previously populated headers field and initializes from it. Maybe
doesn't need to overload in children classes.
ObjectMethod
prepareBody( $req )
Abstract method, must be defined by inherited classes.
Should perform any initialization tasks related to body processing.
ObjectMethod
prepareBodyParameters( $req )
Abstract method, must be defined by inherited classes.
Should fill $req's body parameters (parameters that are set in the
request body, as against the query string). Implementations must
convert parameter values to unicode.
ObjectMethod
prepareUploads( $req )
Abstract method, must be defined by inherited classes.
Should fill $req's {uploads} field. This is a hashref whose keys are
upload names and values
Foswiki::Request::Upload objects.
Implementations must convert upload names to unicode.
ObjectMethod
finalize($res, $req)
Finalizes the request by calling many methods to send response to client and
take any appropriate finalize actions, such as delete temporary files.
ObjectMethod
finalizeUploads( $res, $req )
Abstract method, must be defined by inherited classes.
Should delete any temp files created in preparation phase.
ObjectMethod
finalizeError( $res, $req )
Called if some engine especific error happens.
Base method, must be redefined by inherited classes. For convenience
this method deals with HEAD requests related stuff. Children classes
should call SUPER.
Should call finalizeCookies and then send $res' headers to client.
ObjectMethod
finalizeCookies( $res )
Should populate $res' headers field with cookies, if any.
ObjectMethod
finalizeBody( $res, $req )
Should send $res' body to client. This method calls
write()
as needed, so engines should redefine that method insted of this one.
flush($res, $req)
Forces the response headers to be emitted if they haven't already been sent
(note that this may in some circumstances result in cookies being missed)
before flushing what is in the body so far.
Before headers are sent, any Content-length is removed, as a call to
flush is a statement that there's more to follow, but we don't know
how much at this point.
This function should be used with great care! It requires that the output
headers are fully complete before it is first called. Once it
has been
called, the response object will refuse any modifications that would alter
the header.
ObjectMethod
prepareWrite( $res )
Abstract method, may be defined by inherited classes.
Should perform any task needed before writing.
That's ok if none needed
ObjectMethod
write( $buffer )
Abstract method, must be defined by inherited classes.
-
$buffer
- chunk of data to be sent
Should send $buffer to client.
_getConnectionData($detectProxy) = ( $client, $proto, $host, $port, $proxy )
Utility routine obtains the connection information from the headers.
If $Foswiki::cfg{PROXY}{UseForwardedHeaders} is true, or if the $detectProxy flag is set
this routine will return the connection data from the X-Forwarded-* or Forwarded: headers.
Headers:
- HTTP_X_FORWARDED_HOST
- HTTP_X_FORWARDED_PORT
- HTTP_X_FORWARDED_FOR
- HTTP_X_FORWARDED_PROTO