IDevResource.com - ASP Articles: ASP in a Nutshell : A Desktop Quick Reference , Chapter 6, Request Object, page 3

The Developer's Resource & Community Site

COM	XML	ASP	Java & Misc.	NEW: VS.NET
International	This Week	Forums	Author Central	Find a Job

ASP in a Nutshell (Chapter 6) : The Request Object, page 3
Author: A. Keyton Weissinger
Reproduced with kind permision of O'Reilly & Associates: www.oreilly.com

Example


<% 
' This code iterates through the QueryString collection
' and fills an array with the values retrieved.
Dim item
Dim aryQueryValues()
Dim intItemCount
 
intItemCount = 0
 
For Each item In Request.QueryString
   ReDim Preserve aryQueryValues(intItemCount + 1)
   aryQueryValues(intItemCount) = _ 
                  Request.QueryString(item)
   intItemCount = intItemCount + 1
Next
 
%>

Notes

Like the elements of the Form collection, elements of the QueryString collection can represent multiple values. For example, suppose your ASP file receives a submission from the following HTML form:


<FORM NAME = "frmInfo" ACTION="UserInfo2.ASP" METHOD = "GET">
Below, select all the peripherals you have: 
<INPUT TYPE = "checkbox" NAME = "chkPeriph" VALUE = "Joystick">Joystick<BR>
<INPUT TYPE = "checkbox" NAME = "chkPeriph" VALUE= "GraphicsAccel">3D Graphics Card<BR>
</FORM>

Assume the user checks both checkboxes. The resulting information would be interpreted in the ASP exactly as if the ASP had been requested using the following URL:


UserInfo2.ASP?chkPeriph=Joystick&chkPeriph=GraphicsAccel

To refer to the first element, you could use the following code (note that like other ASP collections, the elements start at 1):


strFirstOption = Request.QueryString("chkPeriph")(1)

If you do not specify a subkey, as in:


strOptions = Request.QueryString("chkPeriph")

then strOptions would have the following value:


Joystick, GraphicsAccel

Also like the Form collection, the QueryString collection contains information sent from the client to the web server. This information can be in the form of parameter/value pairs appended to the end of the requested URL in the HTTP request header, appended to the URL in the address field of the browser, or from an HTML form whose action is set to the HTTP Get method.

There are some limitations to the use of the QueryString collection, the most important of which is its limited length. Although this length varies with varying amounts of client and web server available memory, you should not count on being able to send more than ~1800 characters from the client to the server using the QueryString collection. This ~1800-character "limit" is counted from the end of the script name being called to the end of the parameter list appended to the requested URL, including the names, not just the values, of the parameters sent.

Like elements of the Form collection, elements of the QueryString collection can contain multiple values. To determine the number of values available for a specific element of the collection, use the Count property of the element in question. The value of the Count property is equal to the number of values contained in the element and is zero (0) if the element is not in the collection.

You can retrieve all the values for a given multiple-value element by leaving off the index parameter for the specific element. The values are returned as a comma-delimited string containing only the values from the element being addressed.

Also like the Form collection, you are able to retrieve unparsed data in the QueryString collection. To retrieve the raw, unparsed QueryString collection data, use the syntax Request.QueryString without any element parameter.

The data in the QueryString collection is also accessible from the ServerVariables collection of the Request object, using the HTTP_QUERYSTRING parameter. This is covered in more depth in the section on the ServerVariables collection.

Finally, note that you must encode several special characters when used in the QueryString:

&: The ampersand is used by ASP to delineate separate parameter/value pairs that have been added to the QueryString collection.
?: The question mark delineates the beginning of the QueryString that is added after the filename extension in the filename requested in the URL from the client.
%: The percentage symbol is used in the encoding of other special characters.
+: The plus sign is recognized in the QueryString as representing a space.

These characters can be encoded automatically using the URLEncode and HTMLEncode methods of the Server object on the server side and custom script on the client side.

ServerVariables

Var = Request.ServerVariables(key)

The ServerVariables collection contains several predefined environment variables in the context of the client's specific HTTP request of the web server.

The ServerVariables collection, like the other ASP collections, has the following properties:

Item: The value of a specific element in the collection. To specify an item, you can use an index number or a key.
Key: Returns the name of a specific element in the ServerVariables collection. Just as each element's value is represented by the Item property, each element's name is represented by its Key property.; If you do not know the name of a specific key, you can obtain it using its ordinal reference. For example, assume that you want to learn the key name for the third element in the collection and, subsequently, that element's value. You could use the following code:; If, on the other hand, you know that the third element's key name is "QUERY_STRING," you could simply use the following code to retrieve the value of that element:; Or, simply
Count: The number of elements in the collection.

As with other ASP collections, you can retrieve the value of any field of the ServerVariables collection through the use of the Item property. Note that in the following examples and explanations below (and in nearly all examples from other sources), the syntax has been abbreviated so that it does not explicitly show the use of the Item property. For example:


strFirstName = Request.ServerVariables("REMOTE_ADDR")

is only an abbreviated form of:


strFirstName = Request.ServerVariables.Item("REMOTE_ADDR")

The possible values for Key are in the following list. Although they typically appear in uppercase, Key is actually case insensitive. Note that like elements from other ASP collections, the element values from the ServerVariables collection also can be retrieved using an index number. However, it is important to realize that the following list is in alphabetical order, not in the order in which the elements exist in the ServerVariables collection.

ALL_HTTP: One long string containing all the HTTP headers sent by the client's browser. Each of the following elements can be parsed from this element.
ALL_RAW: One long string containing all the HTTP headers in their original state as sent by the client browser. The primary difference between the ALL_RAW and the ALL_HTTP values is that the values of the ALL_HTTP element are all prefixed with HTTP_ and the header name is always capitalized. Each of the following elements can be parsed from this element.
APPL_MD_PATH: Internally, the IIS metabase holds all the settings of the server. It is similar in function to the registry except for the fact that the metabase holds only information about those items added (as snap-ins) into the Microsoft Management Console. This can include Internet Information Server, Index Server, and SQL Server 7.0, among others. The information in the metabase almost exclusively represents installation and configuration information.; The APPL_MD_PATH element of the ServerVariables collection represents the metabase-specific path for the ISAPI DLL. This is the metabase path from which the ISAPI DLL is called, not its physical location on the server. For example, on my Windows 95 machine (running Personal Web Server) the value of this element is the following:
APPL_PHYSICAL_PATH: The physical path of the APPL_MD_PATH element. This value is retrieved from the conversion of APPL_MD_PATH by IIS. For example, on my system this translates to C:\Inetpub\wwwroot\.
AUTH_PASSWORD: If IIS security is set to Basic Authentication, AUTH_PASSWORD represents the password entered in the authentication box when the client logs into the web server. If a password is not supplied, its value is a null string.
AUTH_TYPE: The method of authentication set on the web server. This authentication method is used to validate all users requesting scripts on the server protected by Windows NT security.
AUTH_USER: The raw username entered upon authentication of the client by the web server.
CERT_COOKIE: A unique ID for the client's digital certificate. The value for this element can be used as a signature for the entire certificate. This element has a value only for clients using the HTTPS protocol. Note that the ClientCertificate collection contains all client-related digital certificate information. The ClientCertificate collection is easier to use than the HTTP header information. Note also that if the client does not send a digital certificate, these CERT_ elements still exist in the ServerVariables collection, but they are empty (i.e., they have no value).
CERT_FLAGS: CERT_FLAGS represents a two-bit value. Bit #0 is set to 1 if the client certificate is present. Bit #1 is set to 1 if the client certificate's certifying authority is invalid (i.e., the issuer is not found in the list of verified certificate issuers that resides on the web server). Note that these values correspond to the ceCertPresent and ceUnrecognizedIssuer constants for the Flags element of the ClientCertificate collection.
CERT_ISSUER: The issuer of the client certificate, if one exists. The value of this element is a comma-delimited string that contains the subfields for each of the possible subelements described in the Issuer element section of the ClientCertificate collection explanation earlier in this chapter.
CERT_KEYSIZE: The number of bits used in the Secure Sockets Layer connection key size (for example, 64 or 128).
CERT_SECRETKEYSIZE: The number of bits in the secret server certificate private key (for example, 1024).
CERT_SERIALNUMBER: The value of the client's certificate serial number.
CERT_SERVER_ISSUER: The issuer of the server certificate.
CERT_SERVER_SUBJECT: The subject field of the server certificate. Like the Subject field of the client certificate, this element's value is a comma-delimited string containing the subfields described in the Subject element section of the ClientCertificate collection description.
CERT_SUBJECT: The subject field of the client certificate. This element's value is a comma-delimited string containing the subfields described in the Subject element section of the ClientCertificate collection description.
CONTENT_LENGTH: The total length of the body of the HTTP request body sent by the client. You can use this value to determine the length of the raw HTTP content in the client's HTTP request. This value does not include the length of any data presented through the request header (i.e., information sent with a GET method), only that information in the request body.
CONTENT_TYPE: This is the MIME type of the content sent by the client. When used with HTTP queries that contain attached information (such as HTTP GET, POST, and PUT actions), this can allow you to determine the data type of the client's HTTP request content data. The most common value for this element is application/x-www-form-urlencoded. If you were to include a file element in your HTML form, you would set the ENCTYPE parameter (and thus the CONTENT_TYPE header in your request) to multipart/form-data.
GATEWAY_INTERFACE: The revision of the Common Gateway Interface that is used by the web server. This string value is in the format CGI/revision #. For example, if you were connected to an IIS 4.0 web server, the value of this item would be CGI/1.1.
HTTP_ [HeaderName]: The value sent in the HTTP header called headername. To retrieve the value of any HTTP header not mentioned in this list (including custom headers), you must prefix the header name with HTTP_. Note that if you specify an HTTP_CUSTOM_SELECTION header, IIS will actually look for an HTTP header labeled as Custom-Header by the client in its HTTP request. In other words, when looking for an HTTP header with hyphens in the name in the ServerVariables collection, use underscores instead. Note that attempting to retrieve a nonexistent header returns an empty string, not an error. For example, each of the following:

HTTP_ACCEPT_LANGUAGE

HTTP_CONNECTION

HTTP_HOST

HTTP_AUTHORIZATION (same as the AUTH_TYPE element)

HTTP_USER-AGENT

requires code resembling the following to receive its value:
HTTPS: This element's value is the string "ON" if the client's HTTP request was sent using SSL. It is "OFF" otherwise.
HTTPS_KEYSIZE: The same as CERT_KEYSIZE described earlier.
HTTPS_SECRETKEYSIZE: The same as CERT_SECRETKEYSIZE described earlier.
HTTPS_SERVER_ISSUER: The same as CERT_SERVER_ISSUER described earlier.
HTTPS_SERVER_SUBJECT: The same as CERT_SERVER_SUBJECT described earlier.
INSTANCE_ID: The ID of the current IIS instance specified in textual format. If this element evaluates to 1, then the value is a string. The INSTANCE_ID represents the number of the instance of the web server to which this request belongs. This is useful only if there is more than one instance of the web server running on your server. Otherwise, this value is always 1, representing the first (and only) instance of the web server on the machine.
INSTANCE_META_PATH: The path in the metabase for the instance of IIS to which the client's HTTP request is sent. As discussed in the earlier section on the APPL_MD_PATH element of the ServerVariables collection, the metabase holds information specific to the installation and configuration of your web server. For my machine running Personal Web Server, the value of this element is /LM/W3SVC/1.
LOCAL_ADDR: The TCP/IP address of the web server that is accepting the client HTTP request. This element of the ServerVariables collection is especially important when your web server resides in a server farm of several machines with distinct IP addresses, all answering requests to the same domain name. If the server is accessed as localhost, its value is 127.0.0.1.
LOGON_USER: The Windows NT user account with which the user has logged onto the system. This is true regardless of the security type you have set for your web server (i.e., anonymous, basic, or Windows NT challenge/response).
PATH_INFO: The virtual path of the web page from which the client makes its HTTP request. If this information evaluates to a virtual directory, the virtual directory is mapped to a physical directory before it is sent to the CGI filter.
PATH_TRANSLATED: The virtual-to-physical mapping of the value of the PATH_INFO element of the ServerVariables collection.
QUERY_STRING: The values sent by the client after the question mark (?) at the end of the HTTP request URL. This element also contains the information sent to the web server using the HTTP GET method. All the information in this element is also available via the QueryString collection (which is easier to utilize, as it does not require parsing).
REMOTE_ADDR: The TCP/IP address of the client.
REMOTE_HOST: The IP address from which the web server receives the client's HTTP request. If the HTTP request does not include this information, the REMOTE_ADDR element's value will be set and this value will be empty.
REQUEST_METHOD: The method by which the client made the HTTP request (GET, POST, HEAD, etc.).
SCRIPT_NAME: The entire virtual path to the current script. It does not include the base portion of the URL, which is represented by the URL element of the ServerVariables collection. It is used (largely internally) for self-referencing URLs. This is equivalent to the value of the PATH_INFO element.
SERVER_NAME: The web server's TCP/IP address, its DNS or hostname as it would appear in a self-referencing URL.
SERVER_PORT: The server port to which the client's HTTP request is sent. This is typically 80 or 8080 for most web servers.
SERVER_PORT_SECURE: If the HTTP request is being managed by the web server on a secure port, this value evaluates to 1. If the port is not secure, this value is 0.
SERVER_PROTOCOL: The name and version of the protocol used by the web server to handle the client request. For example, if the client is using Microsoft Internet Explorer 4.01 and the web server is IIS 4.0, this value is the string "HTTP/1.1."
SERVER_SOFTWARE: The name and version of the web server software handling the client HTTP request. For example, again using Microsoft IIS 4.0, an example value for this element of the ServerVariables collection is Microsoft-IIS/4.0.
URL: The base URL requested by the client in its HTTP request.

Example


<% 
 
' The following code determines the value of the 
' LOGON_USER item of the ServerVariables collection. This 
' code can be used to determine the identity of the 
' client. 
Dim strUserName
 
strUserName = Request.ServerVariables("LOGON_USER")
 
%>

Notes

As the list earlier in this section illustrates, the ServerVariables collection contains many very useful pieces of information regarding the client's HTTP request. Perhaps the most important elements allow you to determine the identity and address of the user. These elements allow you to customize your security efforts.

Also, many of the Request object's other collections' data can be obtained through the ServerVariables collection (usually with more effort, however).

Methods Reference

BinaryRead


MySafeArray = Request.BinaryRead(ByteCount)

The BinaryRead method reads a number of bytes directly from the HTTP request body sent by the client as part of an HTTP Post. The data read from an HTTP request using the BinaryRead method is returned into a SafeArray. A SafeArray is a special variant array that contains, in addition to its items, the number of dimensions in the array and the upper bounds of the array.

NOTE:

In actuality, a SafeArray is not an array at all. It's a special type of structure used internally to maintain information held in its array portion. The dimensions and upper bounds values are available only from C/C++ as elements of the structure. You cannot manipulate these values (or even retrieve them) through script.

Parameters

MySafeArray: The name of a SafeArray used to store the information returned from a BinaryRead.
ByteCount: The number of bytes read using the BinaryRead method. Typically, this variable's value evaluates to the number of bytes returned using the TotalBytes property of the Request object described previously.

Example


<% 
 
' The following code determines the total number of bytes 
' sent in the client's HTTP request. It then reads the 
' bytes, checks for errors, and if there are none, 
' reports to the client that the read was successful.
Dim lngTotalByteCount
Dim vntRequestData
 
On Error Resume Next
 
lngTotalByteCount = Request.TotalBytes
 
vntRequestData = Request.BinaryRead(lngTotalByteCount)
If Err = 0 Then
   ' For details about the Response object, see Chapter 7.
   ' For now, suffice it to say the following code sends
   ' information to the client.
   Response.Clear
   Response.Write lngTotalByteCount & _
                  " bytes successfully read.
"
   Response.End
End If 
 
%>

Notes

If your web application's client piece could control exactly what was sent in the HTTP request body, this method would be invaluable, since it would enable your client to upload information on a byte level (or upload files). However, controlling the information sent in a Post request at byte level is difficult. There are, however, several file-transfer controls available via third parties that allow you to add file-transfer functionality to your application more efficiently and with less difficulty.

It is important to note that if you have previously retrieved information from the Form collection of the Request object, subsequent calls to the BinaryRead method will cause an error. Likewise, if you have previously called the BinaryRead method of the Request object and subsequently attempt to retrieve information from the Form collection, your script will result in an error.

Contribute to IDR:

To contribute an article to IDR, a click here.

To contact us at IDevResource.com, use our feedback form, or email us.

To comment on the site contact our webmaster.