The Request object retrieves the values that the client browser passed to the server during an HTTP request.
Syntax
Request[.collection|property|method](variable)
Variable parameters are strings that specify the item to be retrieved from a collection or to be used as input for a method or property. For more information about the variable parameter, see the individual collection descriptions.
Remarks
If the specified variable is not in one of the preceding five collections, the Request object returns EMPTY.
All variables can be accessed directly by calling Request(variable) without the collection name. In this case, the Web server searches the collections in the following order.
QueryString
Form
Cookies
ClientCertificate
ServerVariables
If a variable with the same name exists in more than one collection, the Request object returns the first instance that the object encounters.
It is strongly recommended that when referring to members of the ServerVariables collection the full name be used. For example, rather than Request.(AUTH_USER) use Request.ServerVariables(AUTH_USER).
Request Collections
ClientCertificate
The ClientCertificate collection retrieves the certification fields (specified in the X.509 standard) from a request issued by the Web browser.
If a Web browser uses the SSL3.0/PCT1 protocol (in other words, it uses a URL starting with https:// instead of http://) to connect to a server and the server requests certification, the browser sends the certification fields.
If no certificate is sent, the ClientCertificate collection returns EMPTY.
Before you can use the ClientCertificate collection, you must configure your Web server to request client certificates.
Syntax
Request.ClientCertificate( Key[SubField] )
Parameters
Key
Specifies the name of the certification field to retrieve. A client certificate consists of the following fields. Value Meaning
Certificate A string containing the binary stream of the entire certificate content in ASN.1 format.
Flags A set of flags that provide additional client certificate information. The following flags may be set:
ceCertPresent - A client certificate is present.
ceUnrecognizedIssuer - The last certification in this chain is from an unknown issuer.
Note To use the preceding flags you must include the client-certificate include file in your ASP page. If you are using VBScript, include cervbs.inc. If you are using JScript, include cerjavas.inc. These files are installed in the \Inetpub\ASPSamp\Samples directory.
Issuer A string that contains a list of subfield values containing information about the issuer of the certificate. If this value is specified without a SubField, the ClientCertificate collection returns a comma-separated list of subfields. For example, C=US, O=Verisign, and so on.
SerialNumber A string that contains the certification serial number as an ASCII representation of hexidecimal bytes separated by hyphens (-). For example, 04-67-F3-02.
Subject A string that contains a list of subfield values that themselves contain information about the subject of the certificate. If this value is specified without a SubField, the ClientCertificate collection returns a comma-separated list of subfields. For example, C=US, O=Msft, and so on.
ValidFrom A date specifying when the certificate becomes valid. This date follows VBScript format and varies with international settings. For example, in the U.S. 9/26/96 11:59:59 pm.
ValidUntil A date specifying when the certificate expires.
SubField
An optional parameter you can use to a retrieve an individual field in either the Subject or Issuer keys. This parameter is added to the Key parameter as a suffix. For example, IssuerO or SubjectCN. The following table lists some common SubField values. Value Meaning
C Specifies the name of the country of origin.
CN Specifies the common name of the user. (This subfield is only used with the Subject key.)
GN Specifies a given name.
I Specifies a set of initials.
L Specifies a locality.
O Specifies the company or organization name.
OU Specifies the name of the organizational unit.
S Specifies a state or province.
T Specifies the title of the person or organization.
SubField values other than those listed in the preceding table can be identified by their ASN.1 identifier. The format of the ASN.1 identifier is a list of numbers separated by a period (.). For example,: 3.56.7886.34.
Remarks
You can use an iterator to loop through the keys of the ClientCertificate collection. This is demonstrated in the following example.
<%
For Each key in Request.ClientCertificate
Response.Write( key & ": " & Request.ClientCertificate(key) & "<BR>")
Next
%>
Examples
The following example uses the Subject key to test whether a client certificate has been presented.
<%
If Len(Request.ClientCertificate("Subject")) = 0
Response.Write("No client certificate was presented")
End if
%>
The following example retrieves the common name of the company that issued the client certificate.
<%= Request.ClientCertificate("IssuerCN") %>
The following example checks the organization name of the subject of the client certification.
<%
If (Request.ClientCertificate("Subject")="Msft")
Response.Write("Good Choice!")
End if
%>
The following example displays the expiration date of the client certificate.
This certification will expire on
<%= Request.ClientCertificate("ValidUntil") %>
The following example uses the Flags key to test whether the issuer of the certificate is known. The include statement in the first line enables this script to use the named flag ceUnrecognizedIssuer.
<!--#include file="cervbs.inc" -->
<%
If Request.ClientCertificate("Flags") and ceUnrecognizedIssuer then
Response.Write "Unrecognized issuer"
End If
%>
Cookies
The Cookies collection enables you to retrieve the values of the cookies sent in an HTTP request.
Syntax
Request.Cookies(cookie)[(key)|.attribute]
Parameters
cookie
Specifies the cookie whose value should be retrieved.
key
An optional parameter used to retrieve subkey values from cookie dictionaries.
attribute
Specifies information about the cookie itself. The attribute parameter can be the following. Name Description
HasKeys Read-only. Specifies whether the cookie contains keys.
Remarks
You can access the subkeys of a cookie dictionary by including a value for key. If a cookie dictionary is accessed without specifying key, all of the keys are returned as a single query string. For example, if MyCookie has two keys, First and Second, and you do not specify either of these keys in a call to Request.Cookies, the following string is returned.
First=firstkeyvalue&Second=secondkeyvalue
If two cookies with the same name are sent by the client browser, Request.Cookies returns the one with the deeper path structure. For example, if two cookies had the same name but one had a path attribute of /www/ and the other of /www/home/, the client browser would send both cookies to the /www/home/ directory, but Request.Cookies would only return the second cookie.
To determine whether a cookie is a cookie dictionary (whether the cookie has keys), use the following script.
<%= Request.Cookies("myCookie").HasKeys %>
If myCookie is a cookie dictionary, the preceding value evaluates to TRUE. Otherwise, it evaluates to FALSE.
You can use an iterator to cycle through all the cookies in the Cookie collection, or all the keys in a cookie. However, iterating through keys on a cookie that does not have keys will not produce any output. You can avoid this situation by first checking to see whether a cookie has keys by using the .HasKeys syntax. This is demonstrated in the following example.
<%
'Print out the entire cookie collection.
For Each cookie in Request.Cookies
If Not cookie.HasKeys Then
'Print out the cookie string
%>
<%= cookie %> = <%= Request.Cookies(cookie)%>
<%
Else
'Print out the cookie collection
For Each key in Request.Cookies(cookie)
%>
<%= cookie %> (<%= key %>) = <%= Request.Cookies(cookie)(key)%>
<%
Next
End If
Next
%>
Examples
The following example prints the value of myCookie in a Web page.
Here is the value of the cookie named myCookie:
<%= Request.Cookies("myCookie") %>
Form
The Form collection retrieves the values of form elements posted to the HTTP request body by a form using the POST method.
Syntax
Request.Form(element)[(index)|.Count]
Parameters
element
Specifies the name of the form element from which the collection is to retrieve values.
index
An optional parameter that enables you to access one of multiple values for a parameter. It can be any integer in the range 1 to Request.Form(parameter).Count.
Remarks
The Form collection is indexed by the names of the parameters in the request body. The value of Request.Form(element) is an array of all of the values of element that occur in the request body. You can determine the number of values of a parameter by calling Request.Form(element).Count. If a parameter does not have multiple values associated with it, the count is 1. If the parameter is not found, the count is 0.
To reference a single value of a form element that has multiple values, you must specify a value for index. The index parameter may be any number between 1 and Request.Form(element).Count. If you reference one of multiple form parameters without specifying a value for index, the data is returned as a comma-delimited string.
When you use parameters with Request.Form, the Web server parses the HTTP request body and returns the specified data. If your application requires unparsed data from the form, you can access it by calling Request.Form without any parameters.
You can use an iterator to loop through all the data values in a form request. For example, if a user filled out a form by specifying two values, Chocolate and Butterscotch, for the FavoriteFlavor parameter, you could retrieve those values by using the following script.
<%
For Each item In Request.Form("FavoriteFlavor")
Response.Write item & "<BR>"
Next
%>
The preceding script would display the following.
Chocolate
Butterscotch
The same output can be generated with a For...Next loop, as shown in the following script.
<%
For i = 1 To Request.Form("FavoriteFlavor").Count
Response.Write Request.Form("FavoriteFlavor")(i) & "<BR>"
Next
%>
You can use this iterator to display the parameter name, as shown in the following script.
<% For Each x In Request.Form %>
Request.Form( <%= x %> ) = <%= Request.Form(x) %> <BR>
<% Next %>
This script displays the following on the browser.
FavoriteFlavor = Chocolate
FavoriteFlavor = Butterscotch
Example
Consider the following form.
<FORM ACTION = "/scripts/submit.asp" METHOD = "post">
<P>Your first name: <INPUT NAME = "firstname" SIZE = 48>
<P>What is your favorite ice cream flavor: <SELECT NAME = "flavor">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION>Chocolate
<OPTION>Rocky Road</SELECT>
<p><INPUT TYPE = SUBMIT>
</FORM>
From that form, the following request body might be sent.
firstname=James&flavor=Rocky+Road
The following script can then be used.
Welcome, <%= Request.Form("firstname") %>.
Your favorite flavor is <%= Request.Form("flavor") %>.
The following output is the result.
Welcome, James. Your favorite flavor is Rocky Road.
If the following script is used
The unparsed form data is: <%= Request.Form %>
the output would be
The unparsed form data is: firstname=James&flavor=Rocky+Road
QueryString
The QueryString collection retrieves the values of the variables in the HTTP query string. The HTTP query string is specified by the values following the question mark (?). Several different processes can generate a query string. For example, the anchor tag
<A HREF= "example?string=this is a sample">string sample</A>
generates a variable named string with the value "this is a sample". Query strings are also generated by sending a form, or by a user typing a query into the address box of their browser.
Syntax
Request.QueryString(variable)[(index)|.Count]
Parameters
variable
Specifies the name of the variable in the HTTP query string to retrieve.
index
An optional parameter that enables you to retrieve one of multiple values for variable. It can be any integer value in the range 1 to Request.QueryString(variable).Count.
Remarks
The QueryString collection is a parsed version of the QUERY_STRING variable in the ServerVariables collection. It enables you to retrieve the QUERY_STRING variables by name. The value of Request.QueryString(parameter) is an array of all of the values of parameter that occur in QUERY_STRING. You can determine the number of values of a parameter by calling Request.QueryString(parameter).Count. If a variable does not have multiple data sets associated with it, the count is 1. If the variable is not found, the count is 0.
To reference a QueryString variable in one of multiple data sets, you specify a value for index. The index parameter may be any value between 1 and Request.QueryString(variable).Count. If you reference one of multiple QueryString variables without specifying a value for index, the data is returned as a comma-delimited string.
When you use parameters with Request.QueryString, the server parses the parameters sent to the request and returns the specified data. If your application requires unparsed QueryString data, you can retrieve it by calling Request.QueryString without any parameters.
You can use an iterator to loop through all the data values in a query string. For example, if the following request is sent
http://NAMES.ASP?Q=Fred&Q=Sally
and Names.asp contained the following script,
---NAMES.ASP---
<%
For Each item In Request.QueryString("Q")
Response.Write item & "<BR>"
Next
%>
Names.asp would display the following.
Fred
Sally
The preceding script could also have been written using Count.
<%
For I = 1 To Request.QueryString("Q").Count
Response.Write Request.QueryString("Q")(I) & "<BR>"
Next
%>
Example
The client request
/scripts/directory-lookup.asp?name=fred&age=22
results in the following QUERY_STRING value.
name=fred&age=22.
The QueryString collection would then contain two members, name and age. You can then use the following script.
Welcome, <%= Request.QueryString("name") %>.
Your age is <%= Request.QueryString("age") %>.
The output would be
Welcome, Fred. Your age is 22.
If the following script is used
The unparsed query string is: <%=Request.QueryString %>
The output would be
The unparsed query string is: name=fred&age=22
