classes.en.rd

# mod_ruby Class Reference Manual

[Index |RD format]

- Apache
- Apache::Request
- Apache::Cookie
- Apache::MultiVal
- Apache::Upload
- Apache::Table
- Apache::ParamTable
- Apache::Server
- Apache::Connection

## Apache

A module to provide Apache functions.

### Module Functions

`add_version_component`
  Add a token to Apache's version string.
`chdir_file(str)`
  Change the server's current working directory to the directory part of the specified filename.
`request`
  Returns the current Apache::Request object.
`server_root`
  Returns the server's root directory (ie., the one set by the ServerRoot directive).
`server_built`
  Returns the server built date string.
`server_version`
  Returns the server version string.
`unescape_url(str)`
  Decodes a URL-encoded string.

### Constants

`Handler status return codes`
  OK, DECLINED, DONE
`HTTP response codes`
  AUTH_REQUIRED, BAD_GATEWAY, BAD_REQUEST, DOCUMENT_FOLLOWS, FORBIDDEN, HTTP_ACCEPTED, HTTP_BAD_GATEWAY, HTTP_BAD_REQUEST, HTTP_CONFLICT, HTTP_CONTINUE, HTTP_CREATED, HTTP_EXPECTATION_FAILED, HTTP_FAILED_DEPENDENCY*1, HTTP_FORBIDDEN, HTTP_GATEWAY_TIME_OUT, HTTP_GONE, HTTP_INSUFFICIENT_STORAGE*2, HTTP_INTERNAL_SERVER_ERROR, HTTP_LENGTH_REQUIRED, HTTP_LOCKED, HTTP_METHOD_NOT_ALLOWED, HTTP_MOVED_PERMANENTLY, HTTP_MOVED_TEMPORARILY, HTTP_MULTIPLE_CHOICES, HTTP_MULTI_STATUS, HTTP_NON_AUTHORITATIVE, HTTP_NOT_ACCEPTABLE, HTTP_NOT_EXTENDED, HTTP_NOT_FOUND, HTTP_NOT_IMPLEMENTED, HTTP_NOT_MODIFIED, HTTP_NO_CONTENT, HTTP_OK, HTTP_PARTIAL_CONTENT, HTTP_PAYMENT_REQUIRED, HTTP_PRECONDITION_FAILED, HTTP_PROCESSING, HTTP_PROXY_AUTHENTICATION_REQUIRED, HTTP_RANGE_NOT_SATISFIABLE, HTTP_REQUEST_ENTITY_TOO_LARGE, HTTP_REQUEST_TIME_OUT, HTTP_REQUEST_URI_TOO_LARGE, HTTP_RESET_CONTENT, HTTP_SEE_OTHER, HTTP_SERVICE_UNAVAILABLE, HTTP_SWITCHING_PROTOCOLS, HTTP_TEMPORARY_REDIRECT, HTTP_UNAUTHORIZED, HTTP_UNPROCESSABLE_ENTITY, HTTP_UNSUPPORTED_MEDIA_TYPE, HTTP_USE_PROXY, HTTP_VARIANT_ALSO_VARIES, HTTP_VERSION_NOT_SUPPORTED, LENGTH_REQUIRED, METHOD_NOT_ALLOWED, MOVED, MULTIPLE_CHOICES, NOT_ACCEPTABLE, NOT_FOUND, NOT_IMPLEMENTED, PARTIAL_CONTENT, PRECONDITION_FAILED, REDIRECT, SERVER_ERROR, USE_LOCAL_COPY, VARIANT_ALSO_VARIES
`Request method constants`

  For testing against the return value of Apache::Request#method_number.

  M_CONNECT, M_COPY, M_DELETE, M_GET, M_INVALID, M_LOCK, M_MKCOL, M_MOVE, M_OPTIONS, M_PATCH, M_POST, M_PROPFIND, M_PROPPATCH, M_PUT, M_TRACE, M_UNLOCK, METHODS

`Options bitmask constants`

  Constants for testing for enabled options via Apache::Request#allow_options.

  OPT_ALL, OPT_EXECCGI, OPT_INCLUDES, OPT_INCNOEXEC, OPT_INDEXES, OPT_MULTI, OPT_NONE, OPT_SYM_LINKS, OPT_SYM_OWNER, OPT_UNSET

`Satisfy constants`

  Constants for testing the return value of the Apache::Request#satisfies method.

  SATISFY_ALL, SATISFY_ANY, SATISFY_NOSPEC

`Remotehost constants`

  Constants which can be (optionally) passed to Apache::Request#remote_host to affect what type of lookup is performed.

  REMOTE_DOUBLE_REV, REMOTE_HOST, REMOTE_NAME, REMOTE_NOLOOKUP

`Blocking Policy constants`

  Constants which are used for setting the blocking policy via Apache::Request#setup_client_block.

  REQUEST_NO_BODY, REQUEST_CHUNKED_ERROR, REQUEST_CHUNKED_DECHUNK, REQUEST_CHUNKED_PASS

[Back to Index]

## Apache::Request

A class to wrap `request_rec` data type.

### Superclass

Object

### Included Modules

Enumerable

### Methods

`<< obj`
  String Output---Writes obj to the client output buffer. obj will be converted to a string using `to_s`.
`[] =`
  Sets the value of the specified response header. Deprecated: Use #headers_out instead.
`[str]`
  Returns the value of the specified request header. Deprecated: Use #headers_in instead.
`add_cgi_vars`
  Add the variables required by the CGI/1.1 protocol to the subprocess_env table.
`add_common_vars`
  Add other Apache CGI variables to the subprocess_env table.
`allow_options`

  Returns the bitmap with specifies which options are enabled for the directory to which the request has been mapped. You can use the Apache module's options bitmask constants to test for desired values.

  For example:

      include Apache

      # Make sure that ExecCGI and Indexes are turned on for the Location
      # being served:
      unless req.allow_options & (OPT_EXECCGI|OPT_INDEXES)
          req.log_reason( "ExecCGI and/or Indexes are off in this directory",
                          req.filename )
          return FORBIDDEN
      end

`allow_overrides`
  Returns an Integer (?).
`allowed`
`allowed= int`

  Returns/sets the bitvector (an `Integer`) of the request methods that the handler can accommodate. You can set bits in this field using one or more request method constants.

  Example:

      include Apache
      Apache::request.allowed |= (1 << M_GET)
      Apache::request.allowed |= (1 << M_POST)

`args`
  Returns the quest string for CGI GET requests, and corresponds to the portion of the URI following the `?`.
`auth_name`
`auth_name= str`
  Returns/sets the authentication realm for the receiving request.
`auth_type`
`auth_type= str`
  Returns/sets the authentication type for the receiving request. Usually one of `"Basic"` or `"Digest"`.
`binmode`
  Puts the client input data stream into binary mode. This is useful only in MS-DOS/Windows environments. Once a stream is in binary mode, it cannot be reset to nonbinary mode.
`bytes_sent`
  Returns the number of bytes sent by the server to the client, excluding the HTTP headers. It is only useful after send_http_header has been called.
`cache_resp`
`cache_resp= val`

  Returns/sets the flag that controls whether the response will have cache-control headers put into its response. If `cache_resp` is set to to `true`, the response will have the following headers added:

      Pragma: no-cache
      Cache-control: no-cache

  If set to `false`, the `Pragma` and `Cache-control` headers will be removed completely from the response headers, regardless of their content.

`cancel`
  Clears the output buffer.
`connection`
  Returns the Apache::Connection object associated with the request.
`construct_url(uri)`
  Returns a fully-qualified URI `String` from the path specified by uri using the request object's server name and port.
`content_encoding`
  Returns the MIME encoding type of the response, as set by the MIME-checking phase of the transaction.
`content_encoding= str`
  Set the MIME `Content-Encoding` header of the response.
`content_languages`
  Returns the value of the `Content-Languages` of the response. This is typically set by the MIME-checking phase of the transaction.
`content_languages= str`
  Specifies Content-Languages of the response header.
`content_length`
  Returns the length of the incoming content as specified by the `Content-Length` header. Deprecated: Use `req.headers_in['Content-Length']` instead.
`content_type`
  Returns the MIME content type of the response, as set by the MIME-checking phase of the transaction.
`content_type= str`
  Set the `Content-Type` header of the response.
`custom_response(status,uri)`

  Set the error document for the given status to the given uri. The status is a `Fixnum` status code like those in the Apache module's HTTP response codes.

  Example:

      include Apache

      unless req.notes['username']
        req.custom_response( HTTP_UNAUTHORIZED, "/noauth.html" )
        return HTTP_UNAUTHORIZED
      end

`default_charset`
  Returns the name of the default character set, as defined by the `AddDefaultCharset` directive.
`default_type`
  Returns the value of the `DefaultType` directive, or `"text/plain"` if not configured.
`dispatch_handler`
`dispatch_handler= str`
  Allows one to get/set the Ruby code which returns the dispatch handler for requests. This makes it possible to write your own dispatch handler.
`each([rs]) {|line|...}`
  Executes the block for every line, where lines are separated by the separator string rs (`$/` by default).
`each_byte {|ch|...}`
  Calls the given block once for each byte (0..255) in the input from the client, passing the byte as an argument.
`each_header {|hdr,val|...}`
  Iterates over the headers in the request, calling the specified block with each header name and value. Deprecated: Use #headers_in instead.
`each_key {|hdr|...}`
  Iterates over the names of each header in the request, calling the specified block once with each one. Deprecated: Use #headers_in instead.
`each_line([rs]) {|line|...}`
  Synonym for Apache::Request#each.
`each_value {|val|...}`
  Iterates over the values of each header in the request, calling the specified block once with each one. Deprecated: Use #headers_in instead.
`eof`
  Returns `true` if the client input data stream is at end of file.
`eof?`
  Synonym for Apache::Request#eof.
`err_headers_out`
  Returns the Apache::Table object for the headers which will be sent even when an error occurs, and which persist across internal redirects.
`error_message`
  Returns the error message set by mod_ruby's internal exception-handler, if any.
`escape_html(str)`
  Returns the specified string with any '`&`', '`"`', '`<`', or '`>`' characters escaped to their HTML entity equivalents.
`exception`
  Returns the `Exception` object set by mod_ruby's internal exception-handler, if any.
`filename`
`filename=`
  Returns/sets the translated physical pathname of the document as determined during the URI translation phase.
`finfo`
  Returns the `File::Stat` object associated with the translated filename of the request, if any. If no physical file is associated with the transaction, the File::Stat object will be the same as that returned from testing a non-existant file.
`get_basic_auth_pw`
  Returns the plaintext password entered by the user as a String. If there was any error fetching the password, a `SystemExit` exception is raised with its status code set to the status code returned by the call.
`getc`
  Returns the next 8-bit byte (0..255) from the data from the client. Returns nil if called at end of file.
`gets([rs])`
  Reads the next "line" from the I/O stream; lines are separated by the separator string rs, which is `$/` by default. A separator of nil reads the entire contents, and a zero-length separator reads the input a paragraph at a time (two successive newlines in the input separate paragraphs). The line read in will be returned and also assigned to $_. Returns nil if called at end of file.
`hard_timeout(msg)`
`kill_timeout`
`reset_timeout`
`soft_timeout(msg)`

  Apache timeout interface methods. These methods are only available under Apache 1.x.

  `#hard_timeout` initiates a "hard" timeout. If an IO operation takes longer than the time specified by the `Timeout` directive, the current handler will be aborted and Apache will immediately enter the logging phase.

  `#soft_timeout` does not abort the current handler, but returns control to it when the timer expires after no-oping all input and output methods. After this occurs, Apache::Connection#aborted? will return `true`.

  `#reset_timeout` is used to reset the timer back to zero between reads or writes.

  `#kill_timeout` cancels the timeout currently in effect when the IO operations it governs are finished.

  Example:

      input = ''
      req.hard_timeout( "#{caller(0)[0]}: Reading request." )
      req.each_line {|line|
        input << line
        req.reset_timeout
      }
      req.kill_timeout

      req.sync = true
      req.soft_timeout( "#{caller(0)[0]: Sending response headers." )
      req.send_http_header
      req.kill_timeout

      req.soft_timeout( "#{caller(0)[0]: Sending response data." )
      until output_data.empty?
        bytes = req.write( output_data )
        if bytes.nonzero?
          req.reset_timeout
          output_data.slice!(0,bytes)
        end
      end
      req.kill_timeout

`header_only?`
  Returns `true` if the request is a head-only request (ie., `req.request_method == 'HEAD'`.
`headers_in`
  Returns the Apache::Table object for the request header.
`headers_out`
  Returns the Apache::Table object for the response header.
`hostname`
  Returns the hostname, as set by full URI or Host:.
`initial?`
  Returns `true` if the request is the initial request (ie., not an internal redirect or a subrequest).
`internal_redirect(uri)`

  Redirect the current request internally to the specified (absolute) uri.

  Example:

      if req.headers_in['user-agent'] !~ /mozilla/i
        req.internal_redirect( "/unsupported-browser.html" )
      end

`last`
  Return the final Apache::Request object for the current chain or internal redirects or subrequests.
`log_reason(msg,file)`

  Output a file-processing log message that looks like:

      access to #{file} failed for #{req.get_remote_host},
        reason: #{msg}

`lookup_file(file)`
`lookup_uri(uri)`

  Will perform a sub-request to lookup a given uri or file, respectively. The data will not be strongly verified (won't go through most of the request cycle), but it will return a new request object that you can use to play with and perform operations on.

  For example:

      subr = r.lookup_uri('/non/existent/file.html?asdf=asdf&asdf=asdf')
      subr.status   # ((* => 200 *))
      subr.filename # ((* => '/usr/local/www/data/non' *))
      subr = r.lookup_file('/etc/foo/bar/baz/non/existent/file.html?asdf=asdf&asdf=asdf')
      subr.status   # ((* => 200 *))
      subr.filename # ((* => '/etc/foo/bar/baz/non/existent/file.html' *))

  The moral of the story is that you have to be careful and perform your own data verification with a lookup. If you use `lookup_file()`, then Apache assumes that the filename specified is authoritative.

`main`
  Returns the main Apache::Request object, or `nil` if the receiver is the main request.
`main?`
  Returns `true` if the receiver is the initial request object or an internal redirect (ie., not a subrequest).
`method_number`
  Returns the request method as a `Integer`. You can compare them to the request method constants above.
`next`
  Returns the Apache::Request object for the next (newer) subrequest or internal redirect, if any. Returns `nil` if no such request exists.
`note_auth_failure`
  Set up the current request's response to indicate a failure to authenticate (ie., will send an "Authentication Required" message to the browser). It will call either note_basic_auth_failure or note_digest_auth_failure, depending on which kind of authentication is configured for the current directory.
`note_basic_auth_failure`
  Set up the current request's response to indicate a failure to authenticate via HTTP Basic Authentication.
`note_digest_auth_failure`
  Set up the current request's response to indicate a failure to authenticate via HTTP Digest Authentication.
`notes`
  Returns the Apache::Table object which can be used to pass "notes" from one handler module to another.
`output_buffer`
  Returns the output buffer `String` currently associated with the request.
`path_info`
`path_info= str`
  Returns/sets the additional path information that remains after the URI has been translated into a file path.
`pos`
  Returns the current offset (in bytes) of the client input data stream.
`pos= n`
  Seeks to the given position n (in bytes) in the client input data stream.
`prev`
  Returns the Apache::Request object for the previous (older) subrequest or internal redirect.
`print(arg...)`
  Writes the given arg object(s) to the output buffer. If the output record separator ($\) is not nil, it will be appended to the output. If no arguments are given, prints $_. Objects that aren't strings will be converted by calling their `to_s` method. Returns `nil`.
`printf(fmt, arg...)`
  Formats and writes to the output buffer, converting parameters under control of the fmt string.
`protocol`
  Returns the name and version number of the protocol requested by the browser (eg., `"HTTP/1.1"`).
`proxy?`
  Returns `true` if the request is for a proxy URI.
`proxy_pass?`
  Returns `true` if the request is for a pass-through-proxied URL.
`putc(ch)`
  Writes the given character ch (taken from a String or a Fixnum) to the output buffer.
`puts(arg...)`
  Writes the given arg objects to the output buffer as with Apache::Request#print . Writes a record separator (typically a newline) after any that do not already end with a newline sequence. If called with an array argument, writes each element on a new line. If called without arguments, outputs a single record separator.
`read([len])`
  Read len bytes from the client.
`readchar`
  Reads a character as with Apache::Request#getc , but raises an `EOFError` on end of file.
`readline([rs])`
  Reads a line as with Apache::Request#gets , but raises an `EOFError` on end of file.
`readlines([rs])`
  Reads all of the lines from the client, and returns them in an `Array`. Lines are separated by the optional separator string rs.
`register_cleanup {...}`
`register_cleanup( plain, [child] )`
  Register a cleanup handler for the request (plain) and/or any child processes forked by the current child (child). Either handler may be any object which responds to the `#call` method (eg., a `Proc`, a `Method`, etc.). The plain cleanup handler may also be given in the form of a block.
`remote_host([type])`
  Returns the remote client's DNS hostname, or its IP address if the hostname cannot be looked up. The optional argument specifies what type of lookup should be performed. The remotehost constants can be used for the type argument.
`remote_logname`
  Returns the login name of the remote user if the host is running the identd service (RFC 1413), or `nil` if the name could not be looked up. This method also depends on the server having the `IdentityCheck` configuration directive turned on, which it is not by default.
`replace(str)`
  Replaces the output buffer with str.
`request_method`
  Returns the request method as a string (eg., "GET", "HEAD", "POST").
`request_time`
  Returns the time when the request started.
`requires`

  Returns an associative `Array` of the `require` directives that apply to the current request. Each entry is of the form:

      [ method_mask, requirement ]

  where method_mask is a bitmap of the HTTP request methods that the requirement applies to, and requirement is the contents of the `require` directive (ie., everything after the space).

  For example, given a config section like this:

      <Limit GET POST>
        require valid-user
      </Limit>
      <Limit PUT DELETE>
        require group Admin
      </Limit>

  the `requires` method would return something like:

      [
        [ 5, "valid-user" ],
        [ 10, "group Admin" ]
      ]

  The bitmask can be tested by left-shifting the mask by the method number, eg.,

      get_mask  = 1 << Apache::M_GET
      post_mask = 1 << Apache::M_POST

`rewind`
  Positions the client data stream to the beginning of input, resetting `lineno` to zero.
`satisfies`
  Returns an `Integer` that can be compared with one of the Apache module's satisfy constants to test the type of access control that applies to the request.
`seek(offset, [whence])`
  Seeks to a given offset offset in the stream according to the value of whence:
  `IO::SEEK_CUR`
    Seeks to offset plus current position.
  `IO::SEEK_END`
    Seeks to anInteger plus end of stream (you probably want a negative value for offset).
  `IO::SEEK_SET` (the default)
    Seeks to the absolute location given by offset.
`send_fd(io)`

  Send the contents of the specified `IO` object to the client. Eg.,

      BannerFile = "/www/htdocs/banner.html"

      begin
        File::open( BannerFile, File::O_RDONLY ) {|ofh|
          req.send_fd(ofh)
        }
      rescue IOError => err
        req.log_reason( err.message, BannerFile )
        return Apache::NOT_FOUND
      end

`send_http_header`
  Sends the HTTP response header. If you call this method more than once, only the first call will actually send it.
`sent_http_header?`
  Returns `true` if the header has been sent already.
`server`
  Returns the Apache::Server object associated with the request.
`server_name`
  Returns the server's public name as a `String` suitable for inclusion in self-referential URLs.
`server_port`
  Returns the port the request was sent to as an `Integer` suitable for inclusion in self-referential URLs.
`setup_cgi_env`
  Clear the current environment and add CGI and common variables to the subprocess_env table. Then export the subprocess_env table, the variables defined in the server and directory configurations for the current request, and the `MOD_RUBY` and `GATEWAY_INTERFACE` variables into the environment shared with subprocesses.
`get_client_block(bufsiz)`
`setup_client_block([policy])`
`should_client_block`
`should_client_block?`
  Interface to Apache's internal request-reading functions. The policy argument accepts one of the blocking policy constants.
`signature`
  Returns the server's signature footer line if the server's `ServerSignature` has been turned on.
`status`
`status=`
  Returns/sets the numeric status code of the transaction.
`status_line`
`status_line= str`
  Returns/sets the full text of the status line returned from Apache to the remote browser (eg., `200 OK`).
`subprocess_env`
  Returns the Apache::Table object containing environment variables which should be passed to subprocesses.
`sync=`
  Set the synchronization of both headers and response body IO.
`sync_header`
`sync_header=`
  Returns/sets the status of header IO synchronization. If `sync_header` is `true`, headers will be sent immediately as they are written, and remaining content will be buffered until the end of the request.
`sync_output`
`sync_output=`
  Returns/sets the status of the synchronization of IO for the response body. If `sync_output` is `true`, all output will be sent immediately instead of buffering it until the end of the request.
`tell`
  Synonym for Apache::Request#pos.
`the_request`
  Returns the first line of the request as a `String`, for logging purposes.
`ungetc(ch)`
  Pushes back one character onto the date stream from the client, such that a subsequent buffered read will return it. Only one character may be pushed back before a subsequent read operation (that is, you will be able to read only the last of several characters that have been pushed back).
`unparsed_uri`
  Returns the uri without any parsing performed.
`uri`
`uri= str`
  Returns/sets the path portion of the URI.
`user`
`user= str`
  Portably set the authenticated username for the current request. For Apache 1.x, calling either of these methods just calls the equivalent method of the connection object, but since Apache 2.x moved the username into the main request object, this way of setting the username will work for either version.
`write(str)`
  Writes the given string str to the output buffer. If the argument is not a string, it will be converted to a string using `to_s`. Returns the number of bytes written.

#### Libapreq Support

If mod_ruby has been compiled with support for the Generic Apache Request library (libapreq), then the following methods will also be available.

`cookies`
`cookies=`
  Get/set the HTTP cookies (RFC 2109) associated with the request as a hash of Apache::Cookie objects keyed by cookie name. Note that setting the cookies hash does not automatically add them to the response. You must call Apache::Cookie#bake on each one to add it to the response. *3
`disable_uploads=`
  Turns uploads on/off; If set to a `true` value, Apache::Request#parse will raise an Apache::RequestError if a file upload is attempted.
`disable_uploads?`
`uploads_disabled?`
  Returns `true` if uploads are disabled.
`param(name)`
  Returns a single parameter by String.
`params(name)`
  Returns multiple parameters by Array.
`paramtable`
  Returns an Apache::ParamTable object which contains the request's parsed parameters. Each parameter will be contained in an Apache::MultiVal object, which allows it to be treated either like a `String` or an `Array`.
`parse( [options] )`
  If the request method is `GET` or `POST`, the query string arguments and the client form data will be read, parsed and saved. In addition, if the request method is `POST` and the `Content-type` is `multipart/form-data`, any uploaded files will be written to temporary files which can be accessed with the corresponding parameters. The return value is `OK` on success; on an error, an error code is returned. The optional options hash sets options for the parsed request:
  `:post_max`
    Specifies the limit for the size of POST data (in bytes). An `Apache::RequestError` is raised if the specified size is exceeded.
  `:disable_uploads`
    If set to a `true` value, an `Apache::RequestError` will be raised if a file upload is attempted.
  `:temp_dir`
    Specifies the directory where upload files are spooled. See Apache::Request#temp_dir.
  `:upload_hook`
    Specifies a `Proc` or `Method` to use as a callback that is run whenever file upload data is read. See Apache::Request#upload_hook.
  `:hook_data`
    Set the third argument passed to every call to the `:upload_hook`, if any.
`post_max`
`post_max=( bytes )`
  Get/set the limit for the size of `POST` data (in bytes). Apache::Request#parse will raise an Apache::RequestError if the size is exceeded.
`temp_dir`
`temp_dir=`
  Get/set the directory where upload files are spooled. On a system that supports `link(2)`, the specified direction should be located on the same file system as the final destination file.
`upload_hook`
`upload_hook=`

  Specifies a `Proc` or `Method` to use as a callback that is run whenever file upload data is read. This can be used to write data to database instead of file, or to provide an upload progress meter during file uploads. Apache doesn't write the original data to the upload filehandle, so you have to write it yourself if needed. The buffer argument contains a copy of the input buffer read for this chunk of the upload, the upload argument is the Apache::Upload object associated with the file being uploaded, and arg is whatever was set as the upload hook user argument via Apache::Request#upload_hook_data or the `:hook_data` attribute of the configuration hash passed to Apache::Request#parse.

  Example:

      hook = Proc::new {|buffer,upload,arg|
          request.server.log_debug( "Read %d bytes from upload '%s'",
                                    buffer.length, upload.filename )
          upload.io.write(buffer)
      }
      request.parse( :upload_hook => hook )

`upload_hook_data`
`upload_hook_data=`
  Get/set the object that is passed as the third argument every time the Apache::Request#upload_hook is called.
`uploads`
  Returns a hash of any uploaded files as Apache::Upload objects. The hash will only be filled if the request method was `POST` and the request's '`Content-type`' was `multipart/form-data`.

[Back to Index]

## Apache::Cookie

A class for manipulating a request's HTTP cookies. This functionality is only available if mod_ruby is compiled with Generic Apache Request library (libapreq) support. A hash of the cookies associated with a request can be fetched by calling Apache::Request#cookies.

### Superclass

Object

### Constants

DateFormat
  The `strftime`-compatible date format used in the #expires attribute for absolute expirations.

### Class Methods

`new( request, [options] )`
  Returns a new `Apache::Cookie` for the specified request (an Apache::Request object). The optional options Hash may be used to initialize the cookie's attributes. The following keys are supported:
  `:name`
    Sets the `name` field to the given value.
  `:value`
    Adds the value to the `values` field.
  `:expires`
    Sets the `expires` field to the calculated date `String` or `Time` object. See Apache::Cookie#expires for a listing of format options. The default is `nil`.
  `:domain`
    Sets the `domain` field to the given value. The default is `nil`.
  `:path`
    Sets the `path` field to the given value. The default path is derived from the requested uri.
  `:secure`
    Sets the `secure` field to `true` or `false`.

### Methods

`bake`
  Add the cookie to the output headers of the request to which it belongs.
`domain`
`domain=`

  Get/set the `domain` attribute of the cookie. From the Netscape spec:

      When searching the cookie list for valid cookies, a comparison of the
      (({domain})) attributes of the cookie is made with the Internet domain
      name of the host from which the URL will be fetched. If there is a tail
      match, then the cookie will go through path matching to see if it should
      be sent. "Tail matching" means that (({domain})) attribute is matched
      against the tail of the fully qualified domain name of the host. A
      (({domain})) attribute of "acme.com" would match host names
      "anvil.acme.com" as well as "shipping.crate.acme.com".

      Only hosts within the specified domain can set a cookie for a domain and
      domains must have at least two (2) or three (3) periods in them to
      prevent domains of the form: ".com", ".edu", and "va.us". Any domain
      that fails within one of the seven special top level domains listed
      below only require two periods. Any other domain requires at least
      three. The seven special top level domains are: "COM", "EDU", "NET",
      "ORG", "GOV", "MIL", and "INT".

      The default value of (({domain})) is the host name of the server which
      generated the cookie response.

`expires`
`expires=`
  Sets the `expires` field. The value can be either a `Time` object or a `String` in any of the following formats:
  `+30s`
    30 seconds from now
  `+10m`
    ten minutes from now
  `+1h`
    one hour from now
  `-1d`
    yesterday (i.e. "ASAP!")
  `now`
    immediately
  `+3M`
    in three months
  `+10y`
    in ten years time
  `Thursday, 25-Apr-1999 00:40:33 GMT`
    at the indicated time & date
`name`
`name=`
  Get/set the name associated with the cookie.
`path`
`path=`

  Get/set the cookie's `path` attribute. From the Netscape spec:

      The (({path})) attribute is used to specify the subset of URLs in a
      domain for which the cookie is valid. If a cookie has already passed
      (({domain})) matching, then the pathname component of the URL is
      compared with the path attribute, and if there is a match, the cookie is
      considered valid and is sent along with the URL request. The path "/foo"
      would match "/foobar" and "/foo/bar.html". The path "/" is the most
      general path.

      If the (({path})) is not specified, it as assumed to be the same path as
      the document being described by the header which contains the cookie.

`secure=`
  Set the cookie's `secure` flag to the given value.
`secure?`
  Returns `true` if the cookie's `secure` flag is set.
`to_s`
  Returns the cookie as a `String`.
`value`
  Get the first value stored in the cookie as a `String`.
`values`
  Get all the values stored in the cookie as an `Array`.
`value=`

  Set the value of the cookie. If the new value responds to `#each`, `#each` will be called, and the result of calling `#to_s` on each iterated value will be added to the cookie's value. If the new value doesn't respond to `#each`, the result of calling `#to_s` on the value itself is added.

  For example:

      svarcookie = Apache::Cookie::new( req, :name => 'sessionvars' )
      svarcookie.value = [ Time::now, req.headers_in['host'] ]
      svarcookie.bake

[Back to Index]

## Apache::MultiVal

`Apache::MultiVal` is a multi-valued datatype for Apache request parameters. Instances of it are used to represent request parameters in a parameter table in an Apache mod_ruby application. Apache::MultiVal makes each parameter in the table capable of being treated like both a String and an Array by delegating String and Array instance methods to either the first value or the Array of values, respectively. The instance methods which String and Array share in common are delegated to the String, except #each, #[], and #[]=, which are sent to the Array. This allows the code to be kept simple: if you only ever expect a parameter to have a single value, you can treat it as if it is a String:

    foo = request.paramtable['foo'].downcase

and treat parameters which can have multiple values (mostly) as an Array:

    bars = request.paramtable['bar'].collect {|val| val.downcase}

For the methods that Array and String share in common, you can cast the parameter to the object you wish with the normal #to_a and #to_s methods:

    foo = request.paramtable['foo']
    if foo.to_a.length > 1
      request.log_warn( "Request had more than one 'foo' parameter: %s",
                           foo.to_a.inspect )

Of course, the Array's length could be obtained with foo.nitems, too, since Array#nitems isn't obscured by String's instance methods.

### Obscured Array methods

As indicated above, some of Array's methods are obscured by those of String, so you should take special note when using them to be sure you know what you'll be getting. For the version of Ruby that was most recent as of this writing (ruby 1.8.0 (2003-06-27)), these are:

"*", "+", "<<", "<=>", "==", "concat", "delete", "empty?", "eql?", "hash", "include?", "index", "insert", "inspect", "length", "replace", "reverse", "reverse!", "rindex", "size", "slice", "slice!", "to_s"

## Apache::Upload

A class that provides an interface for accessing files uploaded by the client. This class is only available when mod_ruby is compiled with the Generic Apache Request Library (libapreq).

### Superclass

Object

### Methods

`filename`
  Returns the name of the uploaded file as reported by the client.
`info`
  Returns the header information for the uploaded file as an Apache::Table object.
`io`

  Returns a new IO object opened (readonly) to the temporary file associated with the upload. Alias: `fp`.

  Example:

      upload = req.uploads['the-file']
      tempfile = upload.io
      destfile = File::open( "/some/where/thefile.txt", File::WRONLY ) {|safefile|
        tempfile.each {|line| safefile.print(line) }
      }

`name`
  Returns the name of the upload field.
`size`
  Returns the size of the uploaded file in bytes.
`tempname`
  Returns the name of the spool file containing the uploaded data on the server.
`type`

  Returns the file's MIME content type. This is a shortcut for accessing the uploaded file's 'Content-Type' header:

      upload = req.uploads['the-file']
      upload.info['content-type'] == upload.type

## Apache::Table

A class to wrap `table` data type.

### Superclass

Object

### Included Classes

Enumerable

### Methods

`clear`
  Clears contents of the table.
`self[name]`
`get(name)`
  Returns the value of name.
`self[name]= val`
`set(name, val)`
`setn(name, val)`
`merge(name, val)`
`mergen(name, val)`
`add(name, val)`
`addn(name, val)`
  Sets the value of name to val.
`unset(name)`
  Unsets the value of name.
`each {|key,val|...}`
`each_key {|key|...}`
`each_value {|val|...}`
  Iterates over each element.

[Back to Index]

## Apache::ParamTable

A derivative of Apache::Table that returns Apache::MultiVal objects for values instead of Strings.

### Superclass

Apache::Table

[Back to Index]

## Apache::Server

A class to wrap global and virtual server configuration and utility methods. Can be fetched via Apache::Request#server.

### Superclass

Object

### Methods

`access_confname`
  Returns the full location of the access.conf configuration file (if any). Not implemented
`admin`
  Returns the email address of the server's administrator as set by the ServerAdmin directive.
`defn_line_number`
  Returns the line number of the file that the configuration came from.
`defn_name`
  Returns a description of where the configuration came from.
`document_root`
  Returns the server's document root, as configured with the `DocumentRoot` directive.
`error_fname`
  Return the name of the server's error log, either absolute or server-root relative.
`gid`
  Returns the effective server gid.
`hostname`
  Returns the (virtual) name of the server host.
`is_virtual`
`virtual?`
  Returns `true` if the server is a virtual host.
`limit_req_fields`
  Returns the limit on the number of request header fields.
`limit_req_fieldsize`
  Returns the limit on the size of any request header field.
`limit_req_line`
  Returns the limit on the number of characters that may be in an HTTP request line.
`log_alert(fmt,*args)`
`log_crit(fmt,*args)`
`log_debug(fmt,*args)`
`log_emerg(fmt,*args)`
`log_error(fmt,*args)`
`log_info(fmt,*args)`
`log_notice(fmt,*args)`
`log_warn(fmt,*args)`
  Write a message to the server's log if the server's `LogLevel` is the specified level or above. The fmt and args are used the same way as the arguments to `printf`.
`loglevel`
  Returns the log level of the server as an `Integer` between 1 and 8; 1 being the least verbose (emerg) and 8 being the most verbose (debug).
`names`
  Returns an Array of server names for the host, starting with the canonical name, plus any aliases set with the `ServerAlias` directive.
`path`
  Returns the legacy URL pathname for a host, for use with name-based virtual hosts. Set with the `ServerPath` directive.
`port`
  Return the port number that the (virtual) server is listening on.
`send_buffer_size`
  Returns the size of the TCP send buffer in bytes.
`srm_confname`
  Returns the full location of the srm.conf configuration file (if any). Not implemented
`keep_alive`
`keep_alive?`
`keep_alive_max`
`keep_alive_timeout`
`timeout`
  Returns the values corresponding to the `Timeout`, `KeepAliveTimeout`, `MaxKeepAliveRequests`, and the `KeepAlive` directives.
`uid`
  Returns the effective server uid.
`wild_names`
  Returns an Array of server names for the host that contain wildcards.

## Apache::Connection

A class to wrap client socket connection records; may be fetched via Apache::Request#connection.

### Superclass

Object

### Methods

`aborted?`
  Returns `true` if a timeout set by Apache::Request#soft_timeout occurs while reading or writing to the client.
`auth_type`
`auth_type= str`
  Returns/sets the type of authentication used, if any, as a `String`. These methods are only implemented when running under Apache 1.x.
`local_host`
  Returns the DNS name of the IP address of the local side of the socket connection.
`local_ip`
  Returns the dotted Internet address of the local side of the socket connection.
`local_port`
  Returns the port number of the local side of the socket connection.
`remote_host`
  Returns the DNS name of the client, if it is set, else the IP address.
`remote_ip`
  Returns the dotted Internet address of the client as a `String`.
`remote_logname`
  Returns the username obtained via RFC 1413 lookup if the server is doing them.
`remote_port`
  Returns the port number of the socket on the client side of the connection.
`user`
`user= str`
  Returns/sets the name of the authenticated user, if any. These methods are only implemented when running under Apache 1.x, so if you wish to write code that works under either version, you should use the equivalent methods in the Apache::Request object.

*1 if implemented
*2 if implemented
*3 This may change in the future