JavaScript Functions > Alphabetical Listing of Web Functions > web.customRequest

web.customRequest

Allows you to create a custom HTTP request with any method supported by HTTP.

Syntax

web.customRequest( {object} );

JavaScript Object

{  
   stepName:"<string>",
   url:"<string>",
   method:"<string>",
   targetFrame:"<string>",
   encType:"<string>",
   recContentType:"<string>",
   referer:"<string>",
   bodyUnicode:"<string>",
   bodyBinary:"<string>",
   body:"<string>",
   bodyFilePath:"<string>",
   resource:"<string>",
   resourceByteLimit:"<string>",
   snapshot:"<string>",
   mode:"<string>",
   extraResBaseDir:"<string>",
   userAgent:"<string>",
   contentEncoding:"<string>",
   rawBody:{  
      content:"<string>",
      length:"<string>"
   },
   "extraRes":[{  
      url:"<string>",
      referer:"<string>"
   }]
}
Property Name
Description
stepName The step name.
url The address of the Web page to load. The URL may be any of the following protocols: HTTP, HTTPS, or FTP. For authentication purposes, include both the user name and the password in the URL attribute using the following format: ftp://username:password@server/dir/path.
method Any HTTP method.
targetFrame The name of the frame containing the current link or resource. See targetframe for more information.
encType The encoding method. See details below.
recContentType The "Content–Type" RESPONSE header value as recorded, for example, text/html, application/x–javascript. The recContentType value is used when the resource attribute is not specified for determining whether the target URL is a resource or not. For details, see reccontentType and resource
referer The Web page that referred to the current page. If the location was explicitly expressed, this attribute is omitted.
bodyUnicode The body is in Latin1 UTF–16LE (little–endian) Unicode. See "Body" below.
bodyBinary The body is in binary code. See "Body" below.
body The request body. See "Body" below.
bodyFilePath The path to a file to be passed as the body of the request. bodyFilepath cannot be used together with any other body attribute.
resource One of:
  • 0 - Not a resource. Download failure is an error.
  • 1 - Resource. Downloaded only if Run–Time setting "Download non–HTML resources" is set. Download failure is a warning. Not parsed as HTML.
resourceByteLimit See resourceByteLimit.
snapshot The file name of the snapshot file.
mode The Recording Level: HTML or HTTP. See Recording Level / mode (Web).
extraResBaseDir The base URL for resolving relative URLs within the extraRes group. For more information, see below.
userAgent The HTTP header identifying the application that represents the user in the interaction with the server. For more information, see below.
contentEncoding Encoding for request body. For example, gzip or deflate.
rawBody The body of the request is passed as a pointer to the data.
extraRes Resources generated by non–HTML mechanisms in the Web page.

Return Values

Not applicable

Parameterization

All properties can be parameterized using standard parameterization except the stepName.

General Information

The web.customRequest function is an action function that allows you to create a custom HTTP request using any method or body. (Each Web action Function in a script causes the browser to display a new Web page or frame. All Web action functions can be recorded by VuGen.) By default, VuGen generates this function only for requests that could not be interpreted with other web functions.

To insert this function manually, use the Add Step dialog box. To specify an HTTP header to be sent before the custom request, add a web.addHeader or web.addAutoHeader function.

The HTTP header can be modified to pass additional information about the request to the server. Using HTTP headers you can, for example, allow other content types in the response such as compressed files, or you can request a Web page only on certain conditions. To modify the HTTP header in the request, see web.addHeader. To modify all subsequent requests, see web.addAutoHeader.

Body

The body of a request is passed as the value of one of the arguments body, bodyBinary, or bodyUnicode, depending on the content. You can only pass one body* argument.

Examples of body specifications:

        bodyUnicode:"REPRICE"
        bodyBinary:"\x08\\x00\\xCC\\x02\\x00\\x00"
        body:".\r\n–dxjjtbw/(.tp?eg:ch/6––\r\n" 

All body values are ASCII, null–terminated strings.

body – indicates regular, printable text. Null bytes cannot be represented. All characters are specified with a backslash.

bodyBinary – indicates binary code. Non–printable characters are encoded in hexadecimal in the form \\xHH, where HH specifies the hexadecimal value. NULL bytes are specified by "\\00"

bodyUnicode – US–English, specifically Latin1 UTF–16LE (little–endian) Unicode only. The actual parameter is stripped of the extra zero byte appending each character to enable easier reading of the text. It is re–appended by web.customRequest before sending to the Web server.
For non–printable characters use a single backslash. Null bytes cannot be represented.

For a body whose length is over 100K, a variable name appears instead of the attribute. The variable is defined in lrw_custom_body.h.

encType

encType specifies a Content–Type, such as "text/html", to be specified as the value of the "Content–Type" REQUEST header for the current replay. web.customRequest performs no body encoding. The body argument specifies the body to be used as is (or after applying "binary" processing), with any encoding having already been applied. Therefore, specifying an encType that does not match the body may cause a server–side error. In general, it is recommended that you do not edit the encType as recorded.

Any encType specification silently overrides any web_add_[auto_]header for Content–Type. If "encType=" (empty value) is specified, no "Content–Type" request header is generated. If "encType" is omitted, any applicable web_add_[auto_]header is used. If there is no header and "method=POST", "application/x–www–form–urlencoded" is used as a default. Otherwise, no Content–Type request header is generated.

extraRes

The Extra Resource Attributes are only inserted when performing HTML-based recording and the "Non HTML-generated elements" advanced recording option is set to Record within the current script step. This is the default setting. For more information, refer to the Virtual User Generator User Guide.

The extraResBaseDir is the base URL for resolving relative URLs within the extraRes group. URLs can be absolute (like "http://weather.abc.com/weather/forecast.jsp?loccode=LFPO") or relative (like "forecast.jsp?loccode=LFPO"). The actual downloading of URLs is always performed using absolute URLs, so that relative URLs must be resolved using another (absolute) URL as a "base". For example, resolving the relative "forecast.jsp?loccode=LFPO" using "http://weather.abc.com/weather/" as a base will yield "http://weather.abc.com/weather/forecast.jsp?loccode=LFPO". By default, when "extraResBaseDir" is not specified, the primary URL of the function is used.

userAgent

The userAgent is the HTTP header identifying the application, usually a browser, which represents the user in the interaction with the server.

For example, the header "User–Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)" identifies Microsoft Internet Explorer 6.0 for Windows NT. Other User–Agent strings are used for different browsers and for other, non–browser applications. Usually, all requests from an application use the same User–Agent value, which the recorder specifies as a Run–Time Setting. However, even within a regular browser session, there may be non–browser components (for example, Active–X) that interact with a server directly, and usually have a different User–Agent string than the browser.

Specifying a userAgent indicates that this is such a non–browser request. The specified string is used in the "User–Agent:" HTTP header, and affects the Replay's behavior in some points, for example, by not using the browser cache, assuming the specified URLs are resources, etc. No check is made to verify that the specified value is different than that of the browser.

Using binary code

You can use the following format to include binary code in the body parameter of a web.customRequest function:

\x[char1][char2]

This represents the hexadecimal value that is represented by [char1][char2].

For example: \x24 is 16*2+4=36, which is a $ sign; \x2B is + sign.

Sequences that do not represent valid 2–character hexadecimal sequences are treated by VuGen as ASCII text. Do not use 1–character hexadecimal sequences. For example, "\x2" is not a valid 2–character hexadecimal sequence. Use "\x02", instead.

Note that binary values appear in a script as \\x, i.e., the "x" is preceded by two backslashes. However, when generating a web.customRequest function by using VuGen, you need to type only one backslash.

If you use parameterization within a web.customRequest function, include only one backslash within the definition of the parameter.

Example

web.customRequest(
 {
  name : 'click_for_next.gif', 
  url : 'http://kalimanjaro/Correlation_ASP_Project/click_for_next.gif', 
  method : 'GET', 
  resource : 1, 
  recContentType : 'image/gif', 
  referer : 'http://kalimanjaro/Correlation_ASP_Project/Correlation_ASP_business_process.asp?first_field_is=param1&change_first_sessionid_each=three_times&links_forms_usage=links_only&step=1&form_method=GET&sessionid_in_cookie=&use_frameset=&frame_target_is=mainframe&first_sessionid_is_large=&type_of_frame=use_frameset&second_field_is=praram2&change_second_sessionid_each=three_times&second_sessionid_is_large=', 
  snapshot : 't9.inf'
 }
);