Main web server interface object.
Object Request
Object Request contains the informations that are retreived from the web server, and allows to exchange data with that.
In forms and gets, If the field name in the request ends with "[]", then the entry in the gets dictionary is an array containing all the values posted under the same field name
| Properties | |
| ap_auth_type | If an apache authentication check was made, this gets set to the auth type. |
| args | The QUERY_ARGS extracted from this request. |
| autoSession | Set to true (default) to have the request ID field automatically written in the cookies of the reply when getSession() is invoked. |
| bytes_sent | Body byte count, for easy access. |
| content_encoding | Encoding through which the data was received. |
| content_length | Full length of uploaded data, including MIME multipart headers. |
| content_type | The Content-Type for the current request. |
| cookies | Dictionary containing the cookies set in the request. |
| filename | The filename on disk corresponding to this response. |
| gets | Fields received in the GET request method. |
| headers | Original request headers (in a dictionary). |
| location | The portion of the URI indicating the "location" of the desired file or directory. |
| method | Original request method. |
| parsed_uri | The uri, already stored in a URI class instance. |
| path_info | The PATH_INFO extracted from this request. |
| posts | Fields received in the POST method. |
| provider | Name of the subsystem that is providing this WOPI interface. |
| remote_ip | The IP address where the request has originated. |
| request_time | Number of microseconds since 00:00:00 january 1, 1970 UTC. |
| sidField | The name of the field used to carry the Session ID. |
| startedAt | Thehe value of seconds() when the script was started. |
| uri | The complete URI as it was sent in the request (including the query elements). |
| user | If an apache authentication check was made, this gets set to the user name. |
| Methods | |
| closeSession | Closes a currently open session. |
| fwdGet | Forwards the request, creating a suitable query string for a target URI. |
| fwdPost | Forwards the request, creating a set of hidden input fields. |
| getField | Retreives a query field from either Request.gets or Request.posts. |
| getSession | Create a new session or returns the session data associated with this session. |
| hasSession | Checks if the current script is hosting an open session. |
| startSession | Create a new session. |
| tempFile | Creates a temporary file. |
If an apache authentication check was made, this gets set to the auth type.
If an apache authentication check was made, this gets set to the auth type.
The QUERY_ARGS extracted from this request.
The QUERY_ARGS extracted from this request.
Set to true (default) to have the request ID field automatically written in the cookies of the reply when getSession() is invoked.
Set to true (default) to have the request ID field automatically written in the cookies of the reply when getSession() is invoked. To manage manually the session cookie (or send the SID field via post/get forwarding) set this to false.
Body byte count, for easy access.
Body byte count, for easy access. Format int64
Encoding through which the data was received.
Encoding through which the data was received.
Full length of uploaded data, including MIME multipart headers.
Full length of uploaded data, including MIME multipart headers. Will be -1 if unknown, and 0 if the request has only an HTTP request header and no body data.
The Content-Type for the current request.
The Content-Type for the current request.
Dictionary containing the cookies set in the request.
Dictionary containing the cookies set in the request.
The filename on disk corresponding to this response.
The filename on disk corresponding to this response.
Fields received in the GET request method.
If the current script is invoked by a query containing query fields in the URI, this property contains the a dictionary with the paris of key/values contained in the query. Fields whose name end with "[]" are translated into arrays and their values is stored in the order tey are found in the query.
In example, if the page is loaded through a form containing the following fields:
<form action="myscript.fal" method="GET">
<br/>User id: <input type="text" name="id"/>
<br/>Hobby: <input type="text" name="hobbies[ ]"/>
<br/>Hobby: <input type="text" name="hobbies[]"/>
<br/>Hobby: <input type="text" name="hobbies[]"/>
</form>
myscript.fal will receive the following fields in gets:
> Request.gets["id"] // will be the user id
inspect( Request.gets["hobbies"] ) // will be an array
Get fields can be generated directly through a query. A link to a falcon script followed by "?" and an URL encode query will be translated into a GET request, and Request.gets fields will receive the specified values.
If a web page contains the following code:
<a href="myscript.fal?id=my_user_id&hobbies[]=diving&hobbies[]=collections">
then, myscript.fal will receive the "id" value and the array specified by hobbies in the "hobbies" key of the Request.gets property.
Original request headers (in a dictionary).
Original request headers (in a dictionary).
The portion of the URI indicating the "location" of the desired file or directory.
The portion of the URI indicating the "location" of the desired file or directory.
Original request method.
Original request method. Can be "GET", "POST", or HTTP methods.
The uri, already stored in a URI class instance.
The uri, already stored in a URI class instance.
The PATH_INFO extracted from this request.
The PATH_INFO extracted from this request.
Fields received in the POST method.
If the current script is invoked through a form declared as having a post method, it will receive the values of the form fields. Fields whose name end with "[]" are translated into arrays and their values is stored in the order tey are found in the query.
In example, if the page is loaded through a form containing the following fields:
<form action="myscript.fal" method="POST">
<br/>User id: <input type="text" name="id"/>
<br/>Hobby: <input type="text" name="hobbies[]"/>
<br/>Hobby: <input type="text" name="hobbies[]"/>
<br/>Hobby: <input type="text" name="hobbies[]"/>
</form>
myscript.fal will receive the following fields in gets:
> Request.posts["id"] // will be the user id
inspect( Request.posts["hobbies"] ) // will be an array
A script may receive both gets and posts fields if the
Name of the subsystem that is providing this WOPI interface.
Name of the subsystem that is providing this WOPI interface.
The IP address where the request has originated.
The IP address where the request has originated.
Number of microseconds since 00:00:00 january 1, 1970 UTC.
Number of microseconds since 00:00:00 january 1, 1970 UTC. Format int64.
The name of the field used to carry the Session ID.
The name of the field used to carry the Session ID.
Thehe value of seconds() when the script was started.
This method returns a relative time taken when the web server integration system gives control to Falcon, before that the script is actually loaded and started.
This formula:
elapsed = seconds() - Request.startedAt
gives the time elapsed in processing the script up to that line, including the time to setup the VM and start the execution.
The complete URI as it was sent in the request (including the query elements).
The complete URI as it was sent in the request (including the query elements).
If an apache authentication check was made, this gets set to the user name.
If an apache authentication check was made, this gets set to the user name.
Closes a currently open session.
Request.closeSession( [sid] )
| sid | Optional explicit SID to be closed |
If the current script is associated with an open session, the active session is closed. In case the session control keeps track of the session ID using a cookie, this cookie is automatically removed.
In case the current script is not associated with a session, this method does nothing.
Forwards the request, creating a suitable query string for a target URI.
Request.fwdGet( [all] )
| all | If true, add also the POST fields. |
| Return | An URI encoded string that can be directly used in further get requests. |
This method simplifies the task to create callback to the page that is being processed when it's necessary to forward all the fields received to the new request.
If the all parameter is true, also the fields passed as POST fields will be forwared through this method.
Note: As the get and post fields are not read-only, it is possible to change their contents in this object and then call this method to introduce exceptions in forwarding the request.
Forwards the request, creating a set of hidden input fields.
Request.fwdPost( [all] )
| all | If true, add also the GET fields. |
| Return | A string containing pre-encoded http hidden input fields. |
This method simplifies the task to create callback to the page that is being processed when it's necessary to forward all the fields received to the new request.
If the all parameter is true, also the fields passed as GET fields will be forwared through this method.
Note: As the get and post fields are not read-only, it is possible to change their contents in this object and then call this method to introduce exceptions in forwarding the request.
Retreives a query field from either Request.gets or Request.posts.
Request.getField( field, [defval] )
| field | The field name to be found. | ||
| defval | Default value to be returned if the field is not found. | ||
| Return | A cookie, POST or GET field value (as a string). | ||
| Raise |
|
In certain cases, it is useful to retreive a query field no matter if it comes from a cookie, the POST part or the GET part of the query. This method searches first the Request.gets, then Request.posts fields and finally the Request.cookies. If the field is not found, the given default value is returned; if that parameter is not specified and the field is not found, an AccessError is raised.
Create a new session or returns the session data associated with this session.
Request.getSession( [sid] )
| sid | Explicit session ID synthesized by the script. | ||
| Return | A blessed dictionary that can be used to store session data. | ||
| Raise |
|
This method creates a new session, eventually using an externally provided session ID. If not provided, the session ID is found in cookies or other sources as indicated by the auto-session settings.
If a sid is provided, the owner is responsible for its creation and maintenance.
Possible errors that can be thrown are:
Checks if the current script is hosting an open session.
Request.hasSession()
| Return | True if this script supposes that it has an open session. |
This function checks this script has been provided with a seemingly valid session id; in other words, it checks if Request.getSession() will try to open an existing session or if it will create a new session.
Request.getSession() may fail even if this function returns true, in case the session ID that this script is provided with is invalid or expired, or if an I/O error occurs during session restore.
Create a new session.
Request.startSession( [sid] )
| sid | Explicit session ID synthesized by the script. | ||
| Return | A blessed dictionary that can be used to store session data. | ||
| Raise |
|
This method creates a new session, using an explicit session ID. The session ID is not automatically saved in cookies nor propagated by any other means.
Possible errors that can be thrown are:
Creates a temporary file.
Request.tempFile( [name] )
| name | If given and passed by reference, it will receive the complete file name. | ||
| Return | A Falcon stream. | ||
| Raise |
|
Temporary streams are automatically deleted when the the script terminates.
In case the script want to get the name of the file where the temporary data is stored (i.e. to copy or move it elsewhere after having completed the updates), the parameter name needs to be passed by reference, and it will receive the filename.
Note: The temporary files are stored in the directory specified by the parameter UploadDir in the falcon.ini file.