web_custom_request

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

C Language

int web_custom_request( const char *RequestName, <List of Attributes>, [EXTRARES, <List of Resource Attributes>,] LAST);

JavaScript

int object.custom_request( const char *RequestName, <List of Attributes>,[EXTRARES, <List of Resource Attributes>,] LAST);

Return Values

This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure.

Parameterization

All attributes from the List of Attributes and the List of Resource Attributes can be parameterized using standard parameterization.

General Information

The web_custom_request function is an action function that allows you to create a custom HTTP request using any method or body. This function is only generated for requests that cannot 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_add_header or web_add_auto_header function.

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 Help Center (select the relevant version).

This function is supported for all web scripts.

Attributes

• URL – the location of the web page to load. The URL can be any of the following protocols: HTTP, HTTPS, or FTP. For authentication, include both the user name and the password in the URL attribute using the following format: ftp://username:password@server/dir/path.
• Method – any method supported by the HTTP protocol.

• TargetFrame – the name of the frame containing the current link or resource. SeeTargetFrame for more information.

• EncType – the encoding method used.

• 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_custom_request performs no body encoding.

• 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.

  The Body argument specifies the body to be used as is. If body encoding is required, it should be applied already to the Body argument as entered in the script. 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.

• RecContentType specifies 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 below and see RecContentType and Resource.

• Referer – the referring web page. The page that referred to the current page. If the location was explicitly expressed, this attribute is omitted.

• Body, BodyBinary, BodyUnicode, or RAW_BODY_START - one or more of these attributes contains the body of the request. See Body Attribute.

• Raw Body – a pointer to the request body is passed to the function. See Raw Body Attribute.

• BodyFilePath – The pathname of the file to be passed as the body of the request. Either specify a full pathname or a pathname relative to the script folder.

  BodyFilePath cannot be used together with Body, or any Body Attribute or Raw Body Attribute: BodyBinary, BodyUnicode, or RAW_BODY_START.

• Resource – "Resource=1" indicates that the URL is a resource. Failures in downloading resources are reported as warnings rather than errors. Whether to download resources or not is controlled by the "Download non–HTML resources" runtime setting. The response is not parsed as HTML.

  "Resource=0" indicates that the URL is not a resource. If required, the response is 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. 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 – "User–Agent" is the name of an 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 runtime 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.

• ContentEncoding – Requests that the request body by encoded (e.g., compressed) using the specified method (for example, gzip or deflate), and that the corresponding "Content–Encoding:" HTTP header be sent along with the request.

Body Attribute

The body of a request is passed as the value of the attribute arguments Body, BodyBinary, or BodyUnicode, depending on the content. The body can be a single argument, or partitioned into multiple body segments,that is, a series of arguments. For example, the following call to web_custom_request partitions the body into three segments: a unicode section, followed by a binary section, followed by regular text. The final body is the result of all three sections concatenated together in the same order as they are passed to the function.

web_custom_request(

                    ...
                    "BodyUnicode=REPRICE"
                    "BodyBinary=\\x08\\x00\\xCC\\x02\\x00\\x00"
                    "Body=.\r\n"
                   "–dxjjtbw/(.tp?eg:ch/6––\r\n",
                   LAST);

All body values are ASCII, null–terminated strings.

Body – Any data can be sent to the server using Body, including binary 0 (null) and other non-printable characters. For information about using binary code in the Body attribute, see Using Binary Code.

BodyBinary – The Binary content to be sent. Non–printable characters are encoded before sending to the web server at runtime. The encoding is hexadecimal in the form \\xHH, where HH specifies the hexadecimal value. NULL bytes are specified by "\\00". See also, Raw Body Attribute.

Caution: If binary data contains a string that can be interpreted as a "\x" and you use BodyBinary, the string is escaped at runtime. For example, if your string contains a literal '\' followed by a literal 'n', it will be converted to a newline code '\n'. That is, 5C 6E is converted to 0A. Such strings can be passed correctly using Body.

BodyUnicode – US–English represented in Latin1 UTF–16LE Unicode. The actual parameter is stripped of the extra zero byte appending each character to make it easier to read the script. The extra zero is re–appended by web_custom_request before sending to the web server.
For non–printable characters use a single backslash. Null bytes cannot be represented.

Note: 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.

BODY handling in C scripts

If the data being sent is very large, VuGen splits the body attribute into multiple strings containing about 1000 characters per line.

Tip: You can break long lines recorded by VuGen into smaller portions to make it clearer what you are correlating or parameterizing.

For example, if this is recorded: 

    "Body=ExampleText=A really long set of information that remains
     the same &ExampleText2=More constant data &INCIDENT={incidentToLookup}&VIEWSTATE={ViewStateCorrelation}",
    LAST);

You can split the Body string into multiple strings to see what is being correlated or parameterized more clearly:

    "Body=ExampleText=A really long set of information that remains the same &ExampleText2=More constant data"     

    "&INCIDENT={incidentToLookup}"

    "&VIEWSTATE={ViewStateCorrelation}", LAST);

Using Binary Code

You can use the following format to include binary code in the Body parameter of a web_custom_request function:

\x[char1][char2]

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

For example: \x24 is a $ sign; \x2B is a + 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.

Binary values appear in a script as \\x, i.e., the "x" is preceded by two backslashes. This is due to C language escaping laws. However, when generating a web_custom_request function by using VuGen, you need to type only one backslash.

If you use parameterization within a web_custom_request function, include only one backslash within the definition of the parameter. This is because parameter substitution does not perform any C escaping conversion.

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_add_header. To modify all subsequent requests, see web_add_auto_header.

Examples

In this example, we submit a form.

web_url("file.html", "URL=http://lazarus/html/forms/file.html",;"TargetFrame=_TOP", LAST );

web_add_header("Content–Type", "multipart/form–data; boundary=–––––––––––––––––––––––––––292742461228954");

web_custom_request("post_query.exe", "Method=POST",

    "URL=http://lazarus/cgi–bin/post_query.exe",

    "Body=–––––––––––––––––––––––––––––292742461228954\r\nContent–Disp"

    "position: form–data; name=\"entry\"\r\n\r\nText\r\n––––––––––"

    "–––––––––––––––––––292742461228954\r\nContent–Disposition: f"

    "–––––––––––292742461228954––\r\n",

    "TargetFrame=",

    LAST );

In this example, we read a file into a parameter, then upload it.

int imageSize;

imageSize = lr_read_file( "image.tiff", "myImage", 0);

if (imageSize == -1) lr_abort();

web_custom_request("postImage.jsp", "Method=POST",

    "URL=http://lazarus/cgi–bin/postImage.jsp",

    "Body={myImage}",

    LAST );

In this example, we upload an image using a pointer and the length.

char* imageBuffer ; // Points to buffer of binary image data, possibly including null bytes

int imageLen;       // The length of the image

// Populate the image buffer and length.

...

web_custom_request("StepName",

    "URL=http://some.url ",

    "Method=POST",

    RAW_BODY_START,

    imageBuffer,

    imageLen,

    RAW_BODY_END,

    LAST);

In this example, we upload a file using the BodyFilePath.

web_custom_request("ABC",

    "URL=http://myserver/files",

    "Method=PUT",

    "Resource=1",

    "RecContentType=text/plain",

    "Referer=",

    "BodyFilePath=c:\\temp\\upload.txt",

    LAST);