Advanced JavaScript support for Application Perspective scripts

The Application Perspective Advanced Scripting support allows JavaScript commands to exist inside Keynote Application Perspective transaction scripts.

These functions give customers and Keynote Support personal additional scripting abilities, including:

  • Programmatic access to the results of a navigation (HTML source, request headers, response headers, etc.)
  • Execution workflow
  • Retry until successfully logged in
  • Always execute a logout page if error is encountered
  • Random link selection
  • Ability to eliminate calls to certain hosts
  • Ability to override errors or generate custom errors.

Adding a script block

To add a Script block to an action, select the action, right click, and select Add Advanced API Script.

Add script block

Add script block

Advanced scripting functionality

The Application Perspective Agent and its associated playback components consist of a number of DLLs and COM objects.

CommonAgent program

This program is the main program that contains all functionality required to obtain a list of transactions to execute and a list of playback engines to perform the work. It also handles failures, concatenation of the resultant for delivery and other monitoring tasks.

HTPlaybackProxy program

This is the ApP engine that can run concurrent executions of different ApP transactions. It handles communications with the CommonAgent and manages the concurrency of executions of the lower-level components.

HTPlayback.dll

This library contains most of the functionality to execute the playing-back of a single transaction.

KNWeb.dll

This is the Application Perspective playback engine COM object that allows access to and control over individual steps, navigations, form submissions, etc.

KNSystem.dll

This is an Application Perspective playback engine COM object that exposes supporting and utility functions that can aid in the development of an Advanced Scripting Support script.

List of scripting functions by category

This Section groups the scripting functions by functional categories.

Temporary and global settings functions

Each browser has a set of temporary and global settings that determine much of its behavior. Global settings are determined when the script is started and cannot be modified during the evaluation of the script. Temporary settings are determined during the evaluation of the script and can be modified as the script runs. The following functions determine whether temporary or global settings are in effect at any point in the script.

Caching functions

Caching functions manipulate the browser’s URL cache. When the browser is retrieving embedded objects on an HTML page, it first checks its URL cache to see if the URL for the object is there. If the URL is found in the cache, the object is not retrieved.

Authentication functions

Authentication functions affect how the browser works through proxies, and how the browser initiates basic, NT, and other HTTP authentication schemes.

Embedded content functions

Embedded content functions affect how embedded URLs are processed after the base page content is retrieved. By using various flags and options, the user can prevent certain types of content from being downloaded during the page retrieval process.

Miscellaneous browser settings functions

Miscellaneous Browser Settings functions affect how the browser behaves in particular situations.

Cookie functions manipulate the browser’s cookie cache. The cookie cache is used to store cookies returned by the web server as a result of HTTP requests. It is also used to retrieve cookies that should be sent with HTTP requests to a particular URL.

Validation functions

The browser performs content validation on all downloaded elements according to validation schemes. Validation schemes are defined using XML documents of type validation. Once a validation scheme has been loaded into the browser, its defined validation will take place for all subsequent requests.

Session functions

Session functions are used to manipulate the browser’s concept of a transaction. If any function in the transaction fails, the browser will ignore other functions until the end of the transaction is reached. Transaction time is reported as the script duration.

Recorder variable functions

Recorder variable functions are used to manipulate variables that have been created using the Keynote Script recorder.

Utility functions

Utility functions perform a variety of tasks.

HTTP functions

HTTP functions allow the user to replace the current HTML contents of a frame by using one of the common HTTP methods to retrieve content from an URL. Form data functions can be called before HTTP functions to modify the form data sent with the request. After any successful HTTP function, the current form data is cleared.

Form and query data functions

Form and query data functions give direct access to the query data and message body that will be used by the next HTTP request. These functions serve as an alternative to manipulating Form objects and then submitting them. In general, HTTP form data is sent as a series of key/value pairs, and the form and query data functions reflect this assumption.

Embedded content functions

Embedded content functions affect how embedded URLs are processed after the base page content is retrieved. Using the following functions, the user can append to the list of embedded URLs normally downloaded during page retrieval.

Link following functions allow the user to traverse text, image or area links that are contained in the frame object’s HTML document. Traversing the link causes the appropriate frame object’s content to be updated. The frame object that will be updated is determined by the link’s TARGET attribute. The following TARGET attribute values are handled specially: _blank, _self, _parent, and _top. If the TARGET attribute is _blank, the content is placed in a new window frame. If the TARGET attribute is _self or does not exist, the content is placed into the current frame object. If the TARGET attribute is _parent, the content is placed into the current frame’s parent, if it exists. If the TARGET attribute value is _top, the content is placed into the “_top” frame, which is default frame object created with the browser.

Form input and submission functions

Form and query data functions give direct access to the query data and message body that will be used by the next HTTP request. These functions serve as an alternative to manipulating EHTMLForm objects and then submitting them. In general, HTTP form data is sent as a series of key/value pairs, and the form and query data functions reflect this assumption.

HTML / XML document functions

HTML document functions give the user access to the XML or HTML document stored as the frame’s contents. They also allow the user to find strings in the current XML or HTML document that fit some given criteria.

Informational functions

Informational functions allow the user to retrieve various attributes of the from the current action.

KNSystem

This class exposes a few functions that might be helpful for developers. These functions are NOT available in release builds.

  • Alert
  • GetConfigEntry
  • PutConfigEntry

Scripter

All script functions

This section lists all of the Application Perspective scripting functions.

 

 

{:#anchor_abort}Abort Method
Syntax HRESULT Abort([out, retval] VARIANT_BOOL* pResult);
Description This function will turn off all data collection activities and will close the active WinHttp handle.
Parameters  
Return value Returns S_OK if successful or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 

{:#anchor_addcontentexclusion}AddContentExclusion Method
Syntax HRESULT AddContentExclusion([in] BSTR value);
Description This function adds a regular expression that specifies URLs that should be excluded from the retrieval process.  Any embedded URL that matched an excluded regular expression will not be downloaded.  No errors will be generated by this exclusion.  base page URLs that match the excluded regular expression will still be downloaded.  This function can be called multiple times to add several sets of excluded URLs.
Parameters
  • value - A regular expression specifying URLs that should be excluded
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_addcustomdetailrecord}AddCustomDetailRecord Method
Syntax HRESULT AddCustomDetailRecord(BSTR errorCode, BSTR recordType, BSTR errorText, BSTR errorPageTitle, BSTR errorHtmlElementText, BSTR errorPageUrl);
Description This function creates is used to create additional data records in the output data stream. This data is not known to MyKeynote and cannot be used to share error information with MyKeynote. It is expected to be used for either future requirements or for Datafeed customers.
Parameters
  • errorCode - The error code to be set
  • recordType - The record type to set (must not be one of the well-known types:
    • “B” (Base page)
    • “R” (Redirect record)
    • “P” (Content element)
    • “E” (standard error record)
  • errorText - The error text (limit 60 characters)
  • errorPageTitle - The page title (limit 255 characters)
  • errorHtmlElementText - The HTML element text (limit 255 characters)
  • errorPageUrl - The error page URL (limit 2048 characters)
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_addelement}AddElement Method
Syntax HRESULT AddElement([in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description This function adds an embedded element URL to the list of URLs downloaded by the browser during the next page download.  Any embedded elements specified through this API will be retrieved after any embedded elements the browser would have retrieved normally, but will be counted as part of the page download.  The URL specified can be partial, in which case it will be resolved using the base page element’s URL.
Parameters
  • value - The embedded element URL
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_addfile2}AddFile2 Method
Syntax HRESULT AddFile2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR key, [in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description This function adds a key/value pair that will be submitted with the next HTTP request.  The difference between Add_File and Add_Form_Data_Encode occurs when next HTTP request is a Post that uses the “multipart/form-data” encoding method.  In this case, the function generates form data whose name attribute is the key and whose filename attribute is the value.  The content type of this form data is “application/octet-stream” and the content of the form data uses either a file off the local disk or a string of “0” characters.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • key - The key
  • value - The value, generally a filename
  • *pResult - The result
Return value This function returns true if the form data was generated successfully; otherwise, it returns false.

 

 

**{:#anchor_addformdataencode2} AddFormDataEncode2** Method
Syntax HRESULT AddFormDataEncode2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR name, [in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description This function allows the user to generate arbitrary key/value pairs to be used as part of the form’s data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • name - The key name
  • value - The value
Return value This function returns true if the key/value pair was added to the form’s data successfully; otherwise, the function returns false.  This function also performs hex encoding of the ‘%’ and ‘+’ characters.

 

 

**{:#anchor_addheader} AddHeader** Method
Syntax HRESULT AddHeader([in] BSTR name, [in] BSTR value, [in] VARIANT_BOOL instrumentation);
Description This function adds an HTTP header that will be submitted with all subsequent HTTP requests.  If the browser would have sent the named header already, the supplied value will overwrite the previous value.  An empty value removes the custom header value and allows the browser to use its default value, if applicable, for the header.
Parameters
  • name - The header name
  • value - The header value
  • instrumentation - A flag indicating whether instrumentation symbolic substitution should be performed on this header
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_addquerydataencode} AddQueryDataEncode** Method
Syntax HRESULT AddQueryDataEncode([in] BSTR name, [out, retval] VARIANT_BOOL* pResult);
Description This function adds a key that will be used to modify the path of the next HTTP request.  All unsafe characters in the key and value are hex encoded before being used to modify the path.
Parameters
  • name - The key
  • *pResult - The result
Return value These functions return true if the key/value pair was added successfully; otherwise, they return false.

 

 

{:#anchor_addquerydataencode2}AddQueryDataEncode2 Method
Syntax HRESULT AddQueryDataEncode2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description Same as AddQueryDataEncode (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • name - The key
  • *pResult - The result
Return value These functions return true if the key/value pair was added successfully; otherwise, they return false.

 

 

{:#anchor_addquerydataencodenamevalue}AddQueryDataEncodeNameValue Method
Syntax HRESULT AddQueryDataEncodeNameValue([in] BSTR name, [in] BSTR data, [out, retval] VARIANT_BOOL* pResult);
Description This function adds a key/value pair that will be used to modify the path of the next HTTP request.  All unsafe characters in the key and value are hex encoded before being used to modify the path.
Parameters
  • name - The key
  • data - The value
Return value This function returns true if the key/value pair was added successfully; otherwise, it returns false.

 

 

{:#anchor_addquerydataencodenamevalue2}AddQueryDataEncodeNameValue2 Method
Syntax HRESULT AddQueryDataEncodeNameValue(([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR name, [in] BSTR data, [out, retval] VARIANT_BOOL* pResult);
Description Same as AddQueryDataEncodeNameValue (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • name - The key
  • data - The value
Return value This function returns true if the key/value pair was added successfully; otherwise, it returns false.

 

 

{:#anchor_addurltocache}AddURLToCache Method
Syntax HRESULT AddURLToCache([in] BSTR value, [in] int type, [out, retval] VARIANT_BOOL* pResult);
Description This function may add the URL to the browser’s cache of loaded objects, depending on the caching level of the browser and the type given.
Parameters
  • value - The URL to add to the cache
  • type - The type of object referenced by the URL - Can be one of the following:
    • TAGTYPE_UNSUPPORTED (0)
    • TAGTYPE_IMAGE (1)
    • TAGTYPE_APPLET (2)
    • TAGTYPE_FRAME (3)
    • TAGTYPE_SCRIPT (6)
Return value Returns S_OK if successful, or an error value otherwise.
Remarks If the caching level of the browser is set to allow the type specified, it will be added to the cache. By adding to this cache, it tells the browser that the particular URL has already been loaded by the browser.

 

 

**{:#anchor_appletsdownloaded} AppletsDownloaded** Property
Syntax HRESULT AppletsDownloaded([out, retval] VARIANT_BOOL *pVal); HRESULT AppletsDownloaded([in] VARIANT_BOOL val);
Description This function determines how the EMBED, APLPET, and OBJECT HTML tags are handled.  If applet loading is enabled, the browser will attempt to retrieve any objects associated with EMBED, APPLET, and OBJECT tags when they are encountered.  For EMBED tags, the SRC attribute is used to find the embedded object’s URL.  For APPLET and OBJECT tags, the CODEBASE and ARCHIVE attributes are used to find the embedded object’s URLs.  If applet loading is disabled, the tags are ignored for the purposes of loading embedding objects.
Parameters (get)
  • *pVal - Returns the current applet loading flag.
Parameters (set)
  • val - Sets (or resets) the applet loading flag.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The applet loading flag defaults to true.

 

 

**{:#anchor_baseutd} BaseUtd** Property
Syntax HRESULT BaseUtd([out,retval] long* pVal);
Description This returns the base UTD of the transaction currently being executed.
Parameters (get)
  • *pVal - This is the base UTD (Keynote time) of the currently executing transaction.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The Base UTDis a long integer that is a second counter with an epoch of 01-JAN-1997, 00:00:00 GMT.

 

 

{:#anchor_checkpagetitle}CheckPageTitle Method
Syntax HRESULT CheckPageTitle([in] BSTR value, [in] VARIANT_BOOL isconst, [in] VARIANT_BOOL exists, [out, retval] VARIANT_BOOL* pResult);
Description This function searches the contents of all frames in the browser for a particular HTML document title.  An HTML document title is defined to be the text that is between the TITLE and /TITLE tags.  Only exact matches will be considered as successful.  If the function returns false, the transaction will be marked as failed.
Parameters
  • Value - The title of the HTML document
  • Isconst - Determines whether the title will be treated as a constant of a variable.
  • Exists - Determines whether the function checks for existence or absence.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_checktext}CheckText Method
Syntax HRESULT CheckText([in] BSTR value, [in] VARIANT_BOOL isconst, [in] VARIANT_BOOL exists, [out, retval] VARIANT_BOOL* pResult);
Description This function searches the contents of all frames in the browser for a particular string. If the function returns false, the transaction will be marked as failed.
Parameters
  • Value - The search text
  • Isconst - Determines whether the text will be treated as a constant or a variable.
  • Exists - Determines whether the function checks for existence or absence.
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_checkurlcache}CheckURLCache Method
Syntax HRESULT CheckURLCache([in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description This function checks the browser’s cache of loaded objects for a particular URL.
Parameters
  • value - The URL to check
  • *pResult - A Boolean flag returning true if the URL is found, otherwise, false
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_clearcookies}ClearCookies Method
Syntax HRESULT ClearCookies([out, retval] VARIANT_BOOL* pResult);
Description This function removes all cookies from the browser’s cookie cache.
Parameters
  • pResult - Returns true if the cookies were removed successfully.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_cleardns}ClearDNS Method
Syntax HRESULT ClearDNS();
Description This function will destroy any internal DNS cache entries that are present for the current transaction.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The ApP agent will locally (internally) cache the DNS entries that it gets resolved during the course of executing a transaction.  At any time, this function may be called to remove all of these entries from the DNS cache.

 

 

{:#anchor_clearsettings}ClearSettings Method
Syntax HRESULT ClearSettings();
Description This function clears all temporary settings (the content exclusion arrays, the validation schemes, and the temporary headers)
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_clickarea}ClickArea Method
Syntax HRESULT ClickArea([in] BSTR coords, [in] int tagid, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function first finds the AREA HTML element referenced by the tagid parameter.  AREA elements are indexed by their location in the document, with 0 being the index of the first AREA element.  If the tagid points to a valid AREA element, the function tries to match either the AREA element’s COORDS or ALT attributes with the given coordinates.   The COORDS value is used to perform the matching if the given coordinates contain the string “Coords:”.  Otherwise, the ALT value is used.  If a match is found, the function performs an HTTP GET to the URL listed in the AREA element’s HREF attribute.  If the element referenced by the tagid is not a match, the function searches through all AREA elements on the page for a match.  This form of the Click_Area function is useful when both the coordinates and the location of the AREA element are known.  By using the index of the AREA element as a hint to finding the link, the function can operate more efficiently than using the coordinates alone.
Parameters
  • coords - The coordinates
  • tagid - The index of the AREA element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching AREA element could be found and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

**{:#anchor_clickarea2} ClickArea2** Method
Syntax HRESULT ClickArea2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR coords, [in] int tagid, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickArea (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • coords - The coordinates
  • tagid - The index of the AREA element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching AREA element could be found and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_clickarea_tagid}ClickArea_Tagid Method
Syntax HRESULT ClickArea_Tagid([in] int tagid, [out, retval] VARIANT_BOOL* pResult);
Description This function finds the AREA HTML element referenced by the tagid parameter.  AREA HTML elements are indexed by their location in the document, with 0 being the index of the first AREA element.  If the tagid points to a valid AREA element, the function performs an HTTP GET to the URL listed in the element’s HREF attribute.  This form of the Click_Area function is useful when the alternate text and coordinates are dynamic, and only the AREA element’s location in the document remains constant.
Parameters
  • tagid - The index of the AREA element
Return value This function returns true if tagid points to a valid AREA HTML element, and the resulting HTTP GET request was performed successfully.  Otherwise, the function returns false.

 

 

{:#anchor_clickarea_tagid2}ClickArea_Tagid2 Method
Syntax HRESULT ClickArea_Tagid2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] int tagid, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickArea_Tagid (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • tagid - The index of the AREA element
Return value This function returns true if tagid points to a valid AREA HTML element, and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_clickarea_text}ClickArea_Text Method
Syntax HRESULT ClickArea_Text([in] BSTR coords, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function searches through all AREA HTML elements in the current document and checks against the COORDS or ALT attributes to see if they match the given coordinates.  The COORDS value is used for matching if the coords parameter contains the text “Coords: “ and the ALT value is used otherwise.  If a matching AREA element is found, the function performs an HTTP GET to the URL listed in the AREA element’s HREF attribute.  This form of the Click_Area function is useful when the alternate text or coordinates for an AREA element are known, but where the element appears in the document is not known.
Parameters
  • coords - The coordinates
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching AREA element could be found and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_clickarea_text2}ClickArea_Text2 Method
Syntax HRESULT ClickArea_Text2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR coords, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickArea_Text (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • coords - The coordinates
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching AREA element could be found and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_clickimage}ClickImage Method
Syntax HRESULT ClickImage([in] BSTR alttext, [in] int tagid, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function first finds the IMG HTML element referenced by the tagid parameter.  IMG elements are indexed by their location in the document, with 0 being the index of the first IMG element.  If the tagid points to a valid IMG element, the function tries to match the IMG element’s ALT and SRC attributes with the given alternate text.  If a match is found, the function checks that the IMG element is surrounded by an A HTML element and performs an HTTP GET to the URL listed in the A element’s HREF attribute.  If the element referenced by the tagid is not a match, the function searches through all IMG elements on the page for a match.  If the matching IMG element contains the ISMAP attribute, the xval and yval input parameters are used to generate additional form data.  This form of the Click_Img function is useful when both the alternate text and the location of the IMG element are known.  By using the index of the IMG element as a hint to finding the link, the function can operate more efficiently than using the alternate text alone.
Parameters
  • alttext - The alternative text
  • tagid - The index of the IMG element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching IMG element could be found which was surrounded by an A HTML element, and the resulting HTTP GET request was performed successfully. Otherwise, the function returns false.

 

 

**{:#anchor_clickimage2} ClickImage2** Method
Syntax HRESULT ClickImage2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR alttext, [in] int tagid, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickImage (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • alttext - The alternative text
  • tagid - The index of the IMG element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching IMG element could be found which was surrounded by an A HTML element, and the resulting HTTP GET request was performed successfully.  Otherwise, the function returns false.

 

 

{:#anchor_clickimage_tagid}ClickImage_Tagid Method
Syntax HRESULT ClickImage_Tagid([in] int tagid, [out, retval] VARIANT_BOOL* pResult);
Description This function finds the IMG HTML element referenced by the tagid parameter.  IMG HTML elements are indexed by their location in the document, with 0 being the index of the first IMG element.  If the tagid points to a valid IMG element and the IMG element is surrounded by an A HTML element, the function performs an HTTP GET to the URL listed in the A element’s HREF attribute.   This form of the Click_Img function is useful when the alternate text and image source are dynamic, and only the image’s location in the document remains constant.
Parameters
  • tagid - The index of the IMG element
Return value This function returns true if tagid points to a valid IMG HTML element that is surrounded by an A element, and the resulting HTTP GET request was performed successfully.  Otherwise, the function returns false.

 

 

**{:#anchor_clickimage_tagid2} ClickImage_Tagid2** Method
Syntax HRESULT ClickImage_Tagid2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] int tagid, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickImage_Tagid (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • tagid - The index of the IMG element
Return value This function returns true if tagid points to a valid IMG HTML element that is surrounded by an A element, and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_clickimage_text}ClickImage_Text Method
Syntax HRESULT ClickImage_Text([in] BSTR alttext, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function searches through all IMG HTML elements in the current document and checks if either their ALT or SRC attributes match the given alternate text.  If a matching IMG element is found, the function looks for an A HTML element surrounding the IMG element.  If this element is also found, the function performs an HTTP GET to the URL listed in the A element’s HREF attribute.   This form of the Click_Img function is useful when the alternate text or image source for an IMG element are known, but where the image appears in the document is not known.
Parameters
  • alttext - The alternative text
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching IMG element could be found which was surrounded by an A HTML element, and the resulting HTTP GET request was performed successfully.  Otherwise, the function returns false.

 

 

{:#anchor_clickimage_text2}ClickImage_Text2 Method
Syntax HRESULT ClickImage_Text2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR alttext, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickImage_Text (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • alttext - The alternative text
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching IMG element could be found which was surrounded by an A HTML element, and the resulting HTTP GET request was performed successfully.  Otherwise, the function returns false.

 

 

{:#anchor_clicklink}ClickLink Method
Syntax HRESULT ClickLink([in] BSTR linktext, [in] int tagid, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function first finds the A HTML element referenced by the tagid parameter.  A HTML elements are indexed by their location in the document, with 0 being the index of the first A element.  If the tagid points to a valid A element, the function tries to match the A element’s link text with the given link text.  If a match is found, the function performs an HTTP GET to the URL listed in the A element’s HREF attribute.  If the element referenced by the tagid is not a match, the function searches through all A elements on the page for a match.  This form of the Click_Link function is useful when both the link text and the location of the A element is known.  By using the index of the A element as a hint to finding the link, the function can operate more efficiently than using the link text alone.
Parameters
  • linktext - The link text
  • tagid - The index of the A element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching A HTML element could be found, and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

**{:#anchor_clicklink2} ClickLink2** Method
Syntax HRESULT ClickLink2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR linktext, [in] int tagid, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickLink (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • linktext - The link text
  • tagid - The index of the A element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching A HTML element could be found, and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_clicklink_tag}ClickLink_Tagid Method
Syntax HRESULT ClickLink_Tagid([in] int tagid, [out, retval] VARIANT_BOOL* pResult);
Description This function finds the A HTML element referenced by the tagid parameter. A HTML elements are indexed by their location in the document, with 0 being the index of the first A element.  If the tagid points to a valid A element, the function performs an HTTP GET to the URL listed in the A element’s HREF attribute. This form of the Click_Link function is useful when the link text is dynamic, and only the link’s location in the document remains constant.
Parameters
  • tagid - The index of the A element
Return value This function returns true if tagid points to a valid A HTML element, and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

**{:#anchor_clicklink_tagid2} ** ClickLink_Tagid2  Method
Syntax HRESULT ClickLink_Tagid2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] int tagid, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickLink_Tagid (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • tagid - The index of the A element
Return value This function returns true if tagid points to a valid A HTML element, and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

ClickLink_Text_Text Method
Syntax HRESULT ClickLink_Text([in] BSTR linktext, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function searches through all A HTML elements in the current document and checks if their link text matches the given link text. Link text is defined to be the ordinary text surrounded by the A and /A elements.  If a matching A element is found, the function performs an HTTP GET to the URL listed in the A element’s HREF attribute. This form of the Click_Link function is useful when the link text is known, but where the link text appears in the document is not known.
Parameters
  • linktext - The link text
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching A HTML element could be found and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

**{:#anchor_clicklink_text2} ClickLink_Text2** Method
Syntax HRESULT ClickLink_Text2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR linktext, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as ClickLink_Text (above) but adds the window, frame, and iframe that should be used as the target for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • linktext - The link text
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if a matching A HTML element could be found and the resulting HTTP GET request was performed successfully; otherwise, the function returns false.

 

 

{:#anchor_deletecookies}DeleteCookies Method
Syntax HRESULT DeleteCookies([in] BSTR name, [in] BSTR domain, [out, retval] VARIANT_BOOL* pResult);
Description This function removes all cookies in the browser’s cookie cache that match the given domain. The domain must contain at least 2 dots. If the given domain has only 2 parts (e.g.: .keynote.com), the function will remove cookies for all servers in the domain (e.g.: www.keynote.com, shopping.keynote.com, etc.).
Parameters
  • name - Not used
  • domain - The domain
  • pResult - true if the cookies associated with the domain could be removed successfully
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_enablecaching}EnableCaching Property
Syntax HRESULT EnableCaching([in] int val);
Description This function sets the caching level bitmap, which is used when URLs are added to the cache.
Parameters (set)
  • val - The caching level bitmap - Can be a bit-wise OR of:
    • CACHE_LEVEL_NONE (0x00)
    • CACHE_LEVEL_ALL (0x01)
    • CACHE_LEVEL_IMAGE (0x02)
    • CACHE_LEVEL_APPLET (0x04)
    • CACHE_LEVEL_FRAME (0x08)
    • CACHE_LEVEL_SCRIPT (0x10)
Return value Returns S_OK if successful, or an error value otherwise.
Remarks
If the cache level none bit is set, no caching of URLs will be performed unless other bits are set. The caching level defaults to CACHE_LEVEL_IMAGE CACHE_LEVEL_APPLET CACHE_LEVEL_FRAME CACHE_LEVEL_SCRIPT

 

 

{:#anchor_enablecookies}EnableCookies Property
Syntax HRESULT EnableCookies([out, retval] VARIANT_BOOL *pVal); HRESULT EnableCookies([in] VARIANT_BOOL val);
Description This function determines how the browser handles cookies.  If cookies are enabled, the browser will store cookies returned through use of the Set-Cookie HTTP header or through the use of META HTML tag.  It will also use the appropriate cookies using the Cookie HTTP header when making HTTP requests.  If cookies are not enabled, no cookies are stored or sent. 
Parameters (get)
  • *pVal - Returns the current cookie flag setting.
Parameters (set)
  • val - Sets (or resets) the cookie flag.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks By default, cookies are enabled.

 

 

{:#anchor_endaction}EndAction Method
Syntax HRESULT EndAction();
Description Tells the browser that an action has completed.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_endsession}EndSession Method
Syntax HRESULT EndSession();
Description This function ends the current session, or transaction. The current session ID is incremented.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_error}Error Property
Syntax HRESULT Error([out, retval] BSTR *pVal); HRESULT Error([in] BSTR val);
Description This will get and/or set the current error code from the playback module.
Parameter (get)
  • *pVal - Current error code
Parameter (put)
  • val - Error code to set
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_errorchecking}ErrorChecking Property
Syntax HRESULT ErrorChecking([out, retval] int *pVal); HRESULT ErrorChecking([in] int val);
Description  
Parameters (get)
  • *pVal - Retrieves the current error checking level.
Parameters (set)
  • val - Sets the error checking level where:
    • LOOSE_ERROR_CHECKING (0)
    • STRICT_ERROR_CHECKING (1)
Return value Returns S_OK if successful, or an error value otherwise.

 

 

ErrorDeferredStop Property
Syntax HRESULT ErrorDeferredStop ([out, retval] int *pVal); HRESULT ErrorDeferredStop ([in] int val);
Description This flag is used to tell the playback logic whether or not to immediately stop on a 404 or other HTML error. This is useful when the 404 error page has content that the user would like to measure.
Parameters (get)
  • *pVal - Returns an integer indicating the current state of the option.
Parameters (set)
  • val - Integer value that sets the option
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_errornumber}ErrorNumber Property
Syntax HRESULT ErrorNumber([out, retval] int *pVal);
Description This function gives access to the most recent playback error.
Parameters (get)
  • *pVal - Contains the most recent Keynote error code encountered.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_findformactionbypartial}FindFormActionByPartial Method
Syntax HRESULT FindFormActionByPartial([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR partial, [in] int index, [out, retval] BSTR* pResult);
Description This function searches through the HTML document and returns the ACTION attribute of FORM HTML elements whose ACTION attribute contains the partial URL given. The ACTION value is resolved to a fully qualified URL before being returned. The index parameter determines which match is returned. An index value of 0 causes the first match to be returned.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • partial - The partial URL
  • index - (Optional) The occurrence of the FORM element
Return value This function returns the ACTION attribute if the matching FORM element is found. Otherwise, an empty string is returned.

 

 

**{:#anchor_findinputvaluebyname} FindInputValueByName** Method
Syntax HRESULT FindInputValueByName([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR name, [in] int index, [out, retval] BSTR* pResult);
Description This function searches through the HTML document and returns the VALUE attribute INPUT HTML elements whose NAME attribute matches the given name. The index parameter determines which match is returned. An index value of 0 causes the first match to be returned, etc. 
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • name - The input name
  • index - (Optional) The occurrence of the INPUT element
Return value This function returns the VALUE attribute if the matching INPUT element is found. Otherwise, an empty string is returned.

 

 

**{:#anchor_findjsparaminanchor} FindJSParamInAnchor** Method
Syntax HRESULT FindJSParamInAnchor([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR fname, [in] int paramNum, [in] int index, [out, retval] BSTR* pResult);
Description This function searches through the HTML document and finds the use of the JavaScript pseudo protocol in the HREF attribute of A HTML elements. When the JavaScript pseudo protocol is detected, Find_JSParam_InAnchor checks if the JavaScript function name is the same as the given function name. If they match, the Find_JSParam_InAnchor checks how many times the JavaScript function has been used and compares it with the given index value. For an index value of 0, the function will use the first occurrence of the JavaScript function, etc. Once Find_JSParam_InAnchor has found the correct occurrence of the JavaScript function, it extracts the appropriate parameter out of the function call.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • fname - The function name
  • paramNum - The parameter number
  • index - The occurrence of the function
Return value This function returns a parameter of a JavaScript function invocation if the function can be found. Otherwise, an empty string is returned.

 

 

**{:#anchor_findstringafter} FindStringAfter** Method
Syntax HRESULT FindStringAfter([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] int index, [in] BSTR start, [in] int length, [out, retval] BSTR* pResult);
Description This function searches through the HTML document and finds occurrences of the start token. When the correct occurrence of the start token is found, the function returns a number of characters following the token. The number of characters is determined by the numchars parameter. If the start token is left as an empty string, the function uses blocks of white space characters (space, tab, CR/LF) as the token.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • index - The relative number of the occurrence of the string to be returned
  • start - The beginning sub-string
  • length - The number of characters to return
Return value This function returns a number of characters after the given start token if the correct number of start tokens can be found. Otherwise, an empty string is returned.

 

 

**{:#anchor_findstringbetween} FindStringBetween** Method
Syntax HRESULT FindStringBetween([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] int index, [in] BSTR begin, [in] BSTR end, [out, retval] BSTR* pResult);
Description This function searches through the HTML document and finds occurrences of the start token. When the correct occurrence of the start token is found, the function returns all characters between the start and end tokens. If either the start or end tokens are left as empty strings, the function will use blocks of white space characters (space, tab, CR/LF) as the tokens.
Parameters
  • iWindow - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • index - The relative number of the occurrence of the string to be returned
  • begin - The beginning sub-string
  • end - The ending sub-string
Return value This function returns the characters between the start and end tokens if the correct number of start tokens can be found. Otherwise, an empty string is returned.

 

 

**{:#anchor_formadddataencode} FormAddDataEncode** Method
Syntax HRESULT FormAddDataEncode([in] int window, [in] BSTR frame, [in] int form, [in] BSTR name, [in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description This function allows the user to generate arbitrary key/value pairs to be used as part of the form’s data.
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • form - Value indicating the relative form number
  • name - The key name
  • value - The value
Return value This function returns true if the key/value pair was added to the form’s data successfully. Otherwise, the function returns false. This function also performs hex encoding of the ‘%’ and ‘+’ characters.

 

 

** FormAddDataEncode2** Method
Syntax HRESULT FormAddDataEncode2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR name, [in] BSTR value, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormClickCheckbox except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • form - Value indicating the relative form number
  • name - The key name
  • value - The value
Return value This function returns true if the key/value pair was added to the form’s data successfully. Otherwise, the function returns false. This function also performs hex encoding of the ‘%’ and ‘+’ characters.

 

 

**{:#anchor_formclickcheckbox} FormClickCheckbox** Method
Syntax HRESULT FormClickCheckbox([in] int window, [in] BSTR frame, [in] int form, [in] BSTR name, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates use of an HTML INPUT element of the CHECKBOX type. Running this function produces the same form data as clicking on a check box in an HTML form. The index determines which check box in a group of check boxes is selected. A group of check boxes is defined to be the set of CHECKBOX INPUT elements in a form that have the same NAME attribute. The index into this group is 0-based.  Display text is not used in the evaluation of the function, but is useful in improving code readability.
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • form - Value indicating the relative form number
  • name - The name of the input
  • label - The display text associated with the input
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • index - The index into the group of check boxes
Return value This function returns true if the CHECKBOX INPUT element could be found and form data could be generated for its activation. Otherwise, the function returns false.

 

 

** FormClickCheckbox2** Method
Syntax HRESULT FormClickCheckbox2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR name, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormClickCheckbox except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • form - Value indicating the relative form number
  • name - The name of the input
  • label - The display text associated with the input
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • index - The index into the group of check boxes
Return value This function returns true if the CHECKBOX INPUT element could be found and form data could be generated for its activation. Otherwise, the function returns false.

 

 

{:#anchor_formclickimage2}FormClickImage2 Method
Syntax HRESULT FormClickImage2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR name, [in] int xValue, [in] int yValue, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormClickImage except for the additon of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • form - Value indicating the relative form number
  • name - The name of the input
  • xValue - The X coordinate of the click point
  • yValue - The Y coordinate of the click point
Return value This function returns true if the form data was generated successfully and the resulting HTTP request was also successful. Otherwise, the function returns false.

 

 

**{:#anchor_formclickradiobutton} FormClickRadioButton** Method
Syntax HRESULT FormClickRadioButton([in] int window, [in] BSTR frame, [in] int form, [in] BSTR name, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates use of an HTML INPUT element of the RADIO type.  Running this function produces the same form data as clicking on a radio button in an HTML form. The index determines which button in a group of radio buttons is selected. A group of radio buttons is defined to be the set of RADIO INPUT elements in a form that have the same NAME attribute. The index into this group is 0-based. Display text is not used in the evaluation of the function, but is useful in improving code readability.
Parameters
  • Window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the input
  • Label - The display text associated with the input
  • Isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Index - The index into the group of radio buttons
Return value This function returns true if the RADIO INPUT element could be found and form data could be generated for its activation. Otherwise, the function returns false.

 

 

** FormClickRadioButton2** Method
Syntax HRESULT FormClickRadioButton2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR name, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormClickRadioButton except for the addition of the iFrame parameter
Parameters
  • Window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the input
  • Label - The display text associated with the input
  • Isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Index - The index into the group of radio buttons
Return value This function returns true if the RADIO INPUT element could be found and form data could be generated for its activation. Otherwise, the function returns false.

 

 

**{:#anchor_forminputfile} FormInputFile** Method
Syntax HRESULT FormInputFile([in] int window, [in] BSTR frame, [in] int form, [in] BSTR name, [in] BSTR file, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates use of an HTML INPUT element of the FILE type. Running this function produces similar form data as typing in a filename into a FILE INPUT. Instead of reading a file off the local disk and using it as part of the form data, however, the function uses either previously loaded file data or a string of ‘0’ characters.
Parameters
  • Window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the input
  • File - The value of the input, generally a filename
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if the form data was generated successfully. Otherwise, it returns false.

 

 

** FormInputFile2** Method
Syntax HRESULT FormInputFile2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR name, [in] BSTR file, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormInputFile except for the addition of the iFrame parameter
Parameters
  • Window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the input
  • File - The value of the input, generally a filename
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if the form data was generated successfully. Otherwise, it returns false.

 

 

{:#anchor_forminputfilebyindex}FormInputFileByIndex Method
Syntax HRESULT FormInputFileByIndex([in] int window, [in] BSTR frame, [in] int form, [in] BSTR file, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates use of an HTML INPUT element of the FILE type.  Running this function produces similar form data as typing in a filename into a FILE INPUT. Instead of reading a file off the local disk and using it as part of the form data, however, the function uses either previously loaded file data or a string of ‘0’ characters. This differs from the FormInputFile by use of the index parameter. This additionally parameter allows the user to specify a relative FILE index to use
Parameters
  • Window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the input
  • File - The value of the input, generally a filename
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Index - The index of the INPUT FILE element
Return value This function returns true if the form data was generated successfully. Otherwise, it returns false.

 

 

** FormInputFileByIndex2** Method
Syntax HRESULT FormInputFileByIndex2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR file, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormInputFileByIndex except for the addition of the iFrame parameter
Parameters
  • Window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the input
  • File - The value of the input, generally a filename
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Index - The index of the INPUT FILE element
Return value This function returns true if the form data was generated successfully. Otherwise, it returns false.

 

 

** FormPutTextEncode** Method
Syntax HRESULT FormPutTextEncode([in] int window, [in] BSTR frame, [in] int form, [in] BSTR field, [in] BSTR value, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description This function add a key/value pair that will be used to modify either the path or the message body of the next HTTP request.  If the next request uses the GET or HEAD methods, the information is used in the request path.  If the next request uses the POST method, the information is used in the message body. This function also performs hex encoding of the ‘%’ and ‘+’ characters. This function should be used when the user is sure that the value parameter has not been previously hex encoded.
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • form - Value indicating the relative form number
  • field - The key
  • value - The value
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if the key/value pair was added successfully. Otherwise, they return false.

 

 

** FormPutTextEncode2** Method
Syntax HRESULT FormPutTextEncode2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR field, [in] BSTR value, [in] VARIANT_BOOL isconst, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormPutTextEncode except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • form - Value indicating the relative form number
  • field - The key
  • value - The value
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
Return value This function returns true if the key/value pair was added successfully. Otherwise, they return false.

 

 

**{:#anchor_formputtextencodebyindex} FormPutTextEncodeByIndex** Method
Syntax HRESULT FormPutTextEncodeByIndex([in] int window, [in] BSTR frame, [in] int form, [in] BSTR value, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description This function simulate use of an HTML INPUT element of the TEXT, TEXTAREA, or PASSWORD types. Running this function produces the same form data as typing in characters into one of the above HTML INPUT element types. The difference between the regular version of the function and the Encode version of the function is that the Encode version performs hex encoding of the ‘%’ and ‘+’ characters. Thus, the normal version is used when the value parameter may have undergone previous hex encoding routines, as it will not re-encode previously encoded characters. The Encode version should be used when the user is sure that the value parameter has not been previously hex encoded.
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Value - The value of the input
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Tagid - The index of the INPUT element
Return value This function returns true if form data was generated successfully. Otherwise, they return false.

 

 

** FormPutTextEncodeByIndex2** Method
Syntax HRESULT FormPutTextEncodeByIndex2([in] int window, [in] BSTR frame, [in] int form, [in] int iFrame, [in] BSTR value, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormPutTextEncodeByIndex except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Value - The value of the input
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Tagid - The index of the INPUT element
Return value This function returns true if form data was generated successfully. Otherwise, they return false.

 

 

**{:#anchor_formselect} FormSelect** Method
Syntax HRESULT FormSelect([in] int window, [in] BSTR frame, [in] int form, [in] BSTR name, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates use of an HTML SELECT element. Running this function produces the same form data as selecting one of the options of a multiple-choice menu in an HTML form. The 0-based index is used as a hint for finding the HTML OPTION element that matches the given display text.
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the SELECT element
  • Label - The display text for the option selected
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • optionIndex - The index of option desired; if -1, no index hint is used.
  • Tagid - The index of the INPUT element
Return value This function returns true if the HTML SELECT element can be found and an option in that element matches the given display text. Otherwise, the function returns false.

 

 

** FormSelect2** Method
Syntax HRESULT FormSelect([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR name, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormSelect except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Name - The name of the SELECT element
  • Label - The display text for the option selected
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • optionIndex - The index of option desired; if -1, no index hint is used.
  • Tagid - The index of the INPUT element
Return value This function returns true if the HTML SELECT element can be found and an option in that element matches the given display text. Otherwise, the function returns false.

 

 

**{:#anchor_formselectbyindex} FormSelectByIndex** Method
Syntax HRESULT FormSelectByIndex([in] int window, [in] BSTR frame, [in] int form, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int selectIndex, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates use of an HTML SELECT element. Running this function produces the same form data as selecting one of the options of a multiple-choice menu in an HTML form. The 0-based index is used as a hint for finding the HTML OPTION element that matches the given display text.
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Label - The name of the SELECT element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • selectIndex - The index of the select element in the form
  • optionIndex - The index of the option within the specified select
Return value This function returns true if the HTML SELECT element can be found and an option in that element matches the given display text. Otherwise, the function returns false.

 

 

**{:#anchor_formselectbyindex2} FormSelectByIndex2** Method
Syntax HRESULT FormSelectByIndex2([in] int window, [in] BSTR frame, [in] int form, [in] int selectIndex, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description This function is similar to FormSelectByIndex but eliminates the need for the label of the option in question.
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • selectIndex - The index of the select element in the form
  • optionIndex - The index of the option within the specified select
Return value This function returns true if the HTML SELECT element can be found and an option in with the requested index can be found. Otherwise, the function returns false.

 

 

** FormSelectByIndex3** Method
Syntax HRESULT FormSelectByIndex([in] int window, [in] BSTR frame, [in] int form, [in] BSTR label, [in] VARIANT_BOOL isconst, [in] int selectIndex, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormSelectByIndex except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Label - The name of the SELECT element
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • selectIndex - The index of the select element in the form
  • optionIndex - The index of the option within the specified select
Return value This function returns true if the HTML SELECT element can be found and an option in that element matches the given display text. Otherwise, the function returns false.

 

 

** FormSelectByIndex4** Method
Syntax HRESULT FormSelectByIndex4([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] int selectIndex, [in] int optionIndex, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormSelectByIndex2 except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • selectIndex - The index of the select element in the form
  • optionIndex - The index of the option within the specified select
Return value This function returns true if the HTML SELECT element can be found and an option in with the requested index can be found. Otherwise, the function returns false.

 

 

**{:#anchor_formsubmit} FormSubmit** Method
Syntax HRESULT FormSubmit([in] int window, [in] BSTR frame, [in] int form, [in] BSTR value, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description This function simulates the use of an INPUT element of the SUBMIT type. Running this function produces the same form data as clicking on a submit button in a form. In addition to generating the appropriate form data, this function also submits the data using HTTP to the URL specified by the form’s ACTION attribute and uses the returned data to modify the contents of a frame. The 0-based index is used to determine which submit element is validated against the given value.
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • Value - The value of the input, as well as the submit button text
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Index - The index of the submit element in the form
Return value This function returns true if the given value must matches the VALUE attribute of the SUBMIT INPUT element referenced by the given index, and the resulting HTTP request was successful. Otherwise, the function returns false.

 

 

** FormSubmit2** Method
Syntax HRESULT FormSubmit2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR value, [in] VARIANT_BOOL isconst, [in] int index, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormSubmit except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • Value - The value of the input, as well as the submit button text
  • isconst - (Deprecated) Determines whether the link text is a constant or a variable.
  • Index - The index of the submit element in the form
Return value This function returns true if the given value must matches the VALUE attribute of the SUBMIT INPUT element referenced by the given index, and the resulting HTTP request was successful. Otherwise, the function returns false.

 

 

**{:#anchor_formsubmiturl} FormSubmitUrl** Method
Syntax HRESULT FormSubmitUrl([in] int window, [in] BSTR frame, [in] int form, [in] BSTR url, [out, retval] VARIANT_BOOL* pResult);
Description This function submits the form. Submission consists of sending all form data that has been generated for the form to the URL specified by the form’s ACTION attribute. The resulting data is used to modify the contents of the frame specified by the form’s TARGET attribute.
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • Form - Value indicating the relative form number
  • url - Optional value to add the destination of the GET or POST; if null, the destination is obtained from the FORM itself.
Return value This function returns true if the form submission was successful. Otherwise, the function returns false.

 

 

** FormSubmitUrl2** Method
Syntax HRESULT FormSubmitUrl2([in] int window, [in] BSTR frame, [in] int iFrame, [in] int form, [in] BSTR url, [out, retval] VARIANT_BOOL* pResult);
Description Same as FormSubmitUrl except for the addition of the iFrame parameter
Parameters
  • window - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Form - Value indicating the relative form number
  • url - Optional value to add the destination of the GET or POST; if null, the destination is obtained from the FORM itself.
Return value This function returns true if the form submission was successful.  Otherwise, the function returns false.

 

 

** FrameErrorFatal** Property
Syntax HRESULT FrameErrorFatal([out, retval] int *pVal); HRESULT FrameErrorFatal([in] int val);
Description This flag is used to tell the playback logic whether or not to stop on any frame’s base page errors. Since the HTML from a frame is considered content, this flag tells the playback routine to either treat a retrieval problem as a content error or as a page failure.
Parameters (get)
  • *pVal - Returns an integer indicating the current state of the option.
Parameters (set)
  • val - Integer value that sets the option
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_framesdownloaded} FramesDownloaded** Property
Syntax HRESULT FramesDownloaded([out, retval] VARIANT_BOOL *pVal); HRESULT FramesDownloaded([in] VARIANT_BOOL val);
Description This function determines how the FRAME HTML tag is handled. If frame loading is enabled, the browser will attempt to retrieve any frames defined in an HTML document. The appropriate EWebFrame objects are created for these frames, and they are populated using the SRC attribute of each FRAME tag. If frame loading is disabled, no automatic frame loading will take place. 
Parameters (get)
  • *pVal - Returns the current frame loading flag setting.
Parameters (set)
  • val - Sets (or resets) the frame loading flag.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The frame loading flag defaults to true.

 

 

**{:#anchor_get} Get** Method
Syntax HRESULT Get([in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description This function makes an HTTP GET request to the specified URL. The results of the request are stored in the frame’s HTML document. GET requests are the most common form of HTTP request, and are used to retrieve most URLs that involve little or no form data.
Parameters Val - The target URL *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_get2} Get2** Method
Syntax HRESULT Get2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description Same as Get (above) but adds the window, frame, and iframe that should be used for the navigation.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Val - Target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_getbase} GetBase** Method
Syntax HRESULT GetBase([in] int frame, [out, retval] BSTR* pResult);
Description This function returns the base HREF for the requested frame.
Parameters
  • frame - Index of the requested frame
Return value Returns the base URL for the requested frame. If no base URL has been specified, this will return the document URL.

 

 

** GetBase2** Method
Syntax HRESULT GetBase2(([in] int iWindow, [in] BSTR frame, [in] int iFrame, [out, retval] BSTR* pResult);
Description This function returns the base HREF for the requested frame.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Val - Target URL
  • *pResult - Returns the base of the requested URL.
Return value Returns the base URL for the requested frame. If no base URL has been specified, this will return the document URL.

 

 

** GetBinaryContent** Method
Syntax HRESULT GetBinaryContent([in] int frame, [out, retval] VARIANT* pResult);
Description This function returns the binary content of the base page of the requested frame.
Parameters
  • frame - Index of the requested frame
Return value Returns a variant of the contents of the frame’s base page.

 

 

** GetBinaryContent2** Method
Syntax HRESULT GetBinaryContent2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [out, retval] VARIANT* pResult);
Description This function returns the binary content of the base page of the requested frame.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used

 

 

**{:#anchor_getcontent} GetContent** Method
Syntax HRESULT GetContent([in] int frame, [out, retval] BSTR* pResult);
Description This function returns the content of the base page of the requested frame.
Parameters
  • frame - Index of the requested frame
Return value Returns a string of the contents of the frame’s base page.

 

 

** GetContent2** Method
Syntax HRESULT GetContent2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [out, retval] BSTR* pResult);
Description This function returns the content of the base page of the requested frame.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
Return value Returns a string of the contents of the requested window/frame combination.

 

 

**{:#anchor_getcookievalue} GetCookieValue** Method
Syntax HRESULT GetCookieValue([in] BSTR name, [in] BSTR domain, [in] BSTR path, [out, retval] BSTR* pResult);
Description This function retrieves the value of the cookie, if it exists, that has the specified name and that applies to the specified domain and path. If multiple cookies with different paths use the same name, the one with the most specific path is returned.
Parameters
  • Name - The cookie name
  • Domain - The domain
  • Path - The path
  • *pResult - The results
Return value Returns S_OK if successful, or an error value otherwise.

 

 

** GetForm** Method
Syntax HRESULT GetForm([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] int formIndex, [in] BSTR type, [in] BSTR attribute, [in] VARIANT_BOOL filtered, [out, retval] VARIANT* linkArray);
Description This function will retrieve an array of elements from the requested form that fulfills the query set.
 Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • type - The form element type to obtain; the list can be one of the following:
    • Inputs
    • Selects
    • FormData
    • _name
    • _method
    • _action
    • _encoding
    • _target
  • attribute - Describes the attribute the user is interested in. The list can be one of the following:
    • _name
    • _method
    • _action
    • _encoding
    • _target
  • filtered - If this is set to true, the attribute value will be used to filter the result set. If set to false, the entire element set will be returned.
  • linkArray - The retultant array of elements that matched the query
Return value This function returns true if the document pointer could be returned. Otherwise, the function returns false.

 

 

** GetFrameHtmlDom** Method
Syntax HRESULT GetFrameHtmlDom([out, retval] IHTMLDocument2** pDomDocument);
Description This function retrieves the MSHTML DOM Document2 pointer fo rthe current window.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • **pDomDocument - The IHTMLDocument2 pointer to the current window
Return value This function returns true if the document pointer could be returned. Otherwise, the function returns false.

 

 

{:#anchor_getframename}GetFrameName Method
Syntax HRESULT GetFrameName([in] int frame, [out, retval] BSTR* pResult);
Description This function retrieves the frame’s name.
Parameters
  • frame - Index of the requested frame
Return value This function returns true if the frame’s name could be retrieved successfully. Otherwise, the function returns false. The frame name is returned through the name output parameter.

 

 

** GetHtmlDom** Method
Syntax HRESULT GetHtmlDom([out, retval] IHTMLDocument2** pDomDocument);
Description This function retrieves the MSHTML DOM Document2 pointer fo rthe current window.
Parameters
  • **pDomDocument - The IHTMLDocument2 pointer to the current window
Return value This function returns true if the document pointer could be returned. Otherwise, the function returns false.

 

 

** GetHtmlDom2** Method
Syntax HRESULT GetHtmlDom2((([in] int iWindow, [in] BSTR frame, [in] int iFrame, [out, retval] IHTMLDocument2** pDomDocument);
Description This function retrieves the MSHTML DOM Document2 pointer fo rthe current window.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • **pDomDocument - The IHTMLDocument2 pointer to the current window
Return value This function returns true if the document pointer could be returned. Otherwise, the function returns false.

 

 

**** ** GetHtmlElements** Method
Syntax HRESULT GetHtmlElements([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR elementName, [in] BSTR attribute, [in] VARIANT_BOOL filtered, [out, retval] VARIANT* linkArray);
Description This function will retrieve an array of elements from the requested page that fulfills the query set.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • elementName - The element type to obtain - the list can be one of the following:
    • Anchors
    • Images
    • Areas
    • Frames
    • Scripts
    • Forms
    • Cookies
    • Inputs
    • Applets
  • attribute - Describes the attribute the user is interested in. The list can be one of the following:
    • _name
    • _method
    • _action
    • _encoding
    • _target
  • filtered - If this is set to true, the attribute value is used to filter the result set. If set to false, the entire element set is returned.
  • linkArray - The resultant array of elements that matched the query
Return value This function returns true if the document pointer could be returned. Otherwise, the function returns false.

 

 

**{:#anchor_getrequestheaders} GetRequestHeaders** Method
Syntax HRESULT GetRequestHeaders([in] int frame, [out, retval] BSTR* pResult);
Description This function returns the request headers from the requested frame.
Parameters
  • frame - Index of the requested frame
Return value This function returns the headers in a single string with carriage return and line feed characters between each header.

 

 

**{:#anchor_getresponseheaders} GetResponseHeaders** Method
Syntax HRESULT GetResponseHeaders([in] int frame, [out, retval] BSTR* pResult);
Description This function returns the response headers from the requested frame.
Parameters
  • frame - Index of the requested frame
Return value This function returns the headers in a single string with carriage return and line feed characters between each header.

 

 

**{:#anchor_geturl} GetURL** Method
Syntax HRESULT GetURL([in] int frame, [out, retval] BSTR* pResult);
Description This function will return the URL that was navigated to for this frame.
Parameters
  • frame - Index of the requested frame
Return value Returns the final URL that resulted in the retrieval of the requested frame.

 

 

** GetURL2** Method
Syntax HRESULT GetURL2(([in] int iWindow, [in] BSTR frame, [in] int iFrame, [out, retval] BSTR* pResult);
Description This function will return the URL that was navigated to for this frame.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • **pDomDocument - The IHTMLDocument2 pointer to the current window
Return value Returns the final URL that resulted in the retrieval of the requested frame.

 

 

**{:#anchor_getvariable} GetVariable** Method
Syntax HRESULT GetVariable([in] BSTR varName, [out, retval] BSTR* pResult);
Description This function provides a means to resolve a recorder variable.
Parameters
  • varName - The recorder variable name
  • *pResult - The results
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_head} Head** Method
Syntax HRESULT Head([in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description This function makes an HTTP HEAD request to the specified URL. The results of the request are stored in the frame’s HTML document. HEAD requests are used to retrieve header information for a URL without causing the added overhead of retrieving the complete document
Parameters
  • Val - The target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_head2} Head2** Method
Syntax HRESULT Head2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description Same as Head (above) but adds the window, frame, and iframe that should be used for the navigation.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Val - The target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_imagesdownloaded} ImagesDownloaded** Property
Syntax HRESULT ImagesDownloaded([out, retval] VARIANT_BOOL *pVal); HRESULT ImagesDownloaded([in] VARIANT_BOOL val);
Description This function determines how the IMG HTML tag is handled. If image loading is enabled, the browser will attempt to retrieve the object associated with each IMG tag by using its SRC attribute as the URL. If image loading is disabled, no objects associated with IMG tags will be retrieved. 
Parameters (get)
  • *pVal - Returns the current image downloading flag setting.
Parameters (set)
  • val - Sets (or resets) the image downloading flag.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The image loading flag defaults to true.

 

 

**{:#anchor_initialize} Initialize** Method
Syntax HRESULT Initialize([in] int agentId, [in] int agentInstId, [in] int timeOffset, [in] int targetId, [in] int execId, [in]  int debug );
Description This is the first call that must be made to initiate a Keynote transaction session. It will create all the internal interfaces required to perform the measurement and collect the resultant data.
Parameters
  • AgentId - This is the agent ID for the agent.
  • AgentInstId - This is the agent instance ID for the agent.
  • TimeOffset - This is the difference between the clock on the agent and the real NTP time.
  • Targeted - This is the target IDfor the transaction being submitted.
  • ExecId - This is a execution number for this execution. It can be any number.
  • debug
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_instrumentationinitializehighleveldata} InstrumentationInitializeHighLevelData** Method
Syntax HRESULT InstrumentationInitializeHighLevelData();
Description This function sets up the previously defined agent ID, agent instance ID, target ID, base_utd, and the script name to a instrumentation symbolic substitution routine. This function is only necessary if instrumentation is enabled in the transaction.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_keepconnection} KeepConnection** Property
Syntax HRESULT KeepConnection([in] VARIANT_BOOL val);
Description This function tells the browser to include the Connection: keep-alive HTTP header.
Parameters (set)
  • val - A value of true sets this function, false turns off this function.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_load} Load** Method
Syntax HRESULT Load([in] BSTR script);
Description This function will instruct the Parameter Manager subsystem to load the particular script into its in-memory storage. This is normally performed automatically at the start of a transaction.
Parameters
  • script - A string representation of the transaction ID
Return value Returns S_OK if successful, or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 

**{:#anchor_loggerrefresh} LoggerRefresh** Method
Syntax HRESULT LoggerRefresh([in] VARIANT_BOOL value);
Description This function performs a ‘pre-measurement’ cleanup of the logger mechanism. The logger mechanism in ApP is responsible for collecting the measurement data during the course of executing a transaction.
Parameters
  • value - Always use TRUE.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 


MetaRefreshErrorFatal
Property
Syntax HRESULT MetaRefreshErrorFatal([out, retval] int *pVal); HRESULT MetaRefreshErrorFatal([in] int val);
Description This flag is used to tell the playback logic whether or not to stop on any meta redirect errors. Since the HTML from the result of a meta refresh is considered content, this flag tells the playback routine to either treat a retrieval problem as a content error or as a page failure.
Parameters (get)
  • *pVal - Returns an integer indicating the current state of the option.
Parameters (set)
  • val - Integer value that sets the option
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_outputdata} OutputData** Property
Syntax HRESULT OutputData([out, retval] BSTR *pVal);
Description This function will retrieve the current data results that have accumulated for the transaction.
Parameters
  • *pVal - Returns the current XML snippet of the resultant data.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_pause} Pause** Method
Syntax HRESULT Pause([in] int pause);
Description This function causes the browser object to pause for a predefined number of seconds. It can be used to simulate user think time, or time spent reading an HTML document.
Parameters
  • pause - The time to pause, in seconds
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_poolsize} PoolSize** Property
Syntax HRESULT PoolSize([out, retval] int *pVal); HRESULT PoolSize([in] int val);
Description This function tells the connection manager the number of measurement threads that should be created for this transaction.
Parameters (get)
  • *pVal - Returns the current number of measurement threads created for this transaction.
Parameters (set)
  • val - Sets the number of measurement threads for this transaction.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The default pool size is 2.

 

 

**{:#anchor_post} Post** Method
Syntax HRESULT Post([in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description This function makes an HTTP POST request to the specified URL. The results of the request are stored in the frame’s HTML document. POST requests are common when there are large amounts of form data or when the form data needs to be hidden
Parameters
  • Val - The target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

{:#anchor_post2}Post2 Method
Syntax HRESULT Post2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description Same as Post (above) but adds the window, frame, and iframe that should be used for the navigation.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Val - The target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_proxypassword} ProxyPassword** Property
Syntax HRESULT ProxyPassword([in] BSTR val);
Description This function sets the password that will be used for authentication with any HTTP proxy that requires authentication.
Parameters (set)
  • val - The password to use for authentication with HTTP proxies
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_proxyusername} ProxyUserName** Property
Syntax HRESULT ProxyUserName([in] BSTR val);
Description This function sets the username that will be used for authentication with any HTTP proxy that requires authentication.
Parameters (set)
  • val - The username to use for authentication with HTTP proxies
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_put} Put** Method
Syntax HRESULT Put([in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description This function makes an HTTP PUT request to the specified URL. The results of the request are stored in the frame’s HTML document.  PUT requests create a file at the target URL that contains the data sent with the request. Since most web servers do not grant PUT privileges, this is a rarely used request type.
Parameters
  • Val - The target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_put2} Put2** Method
Syntax HRESULT Put2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR val, [out, retval] VARIANT_BOOL* pResult);
Description Same as Put (above) but adds the window, frame, and iframe that should be used for the navigation.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • Val - The target URL
  • *pResult - The result
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_putcookie} PutCookie** Method
Syntax HRESULT PutCookie([in] BSTR name, [in] BSTR value, [in] BSTR domain, [in] BSTR path, [in] VARIANT_BOOL secure, [in] VARIANT_BOOL instrumentation);
Description This function stores a cookie in the browser’s cookie cache.
Parameters
  • name - The cookie name
  • value - The cookie value
  • domain - The domain for which the cookie is valid
  • path - The path for which the cookie is valid
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_requesttracking} RequestTracking** Property
Syntax HRESULT RequestTracking([out, retval] VARIANT_BOOL *pVal); HRESULT RequestTracking([in] VARIANT_BOOL val);
Description Obsolete - indicated that the application should log all the request headers to a log file.
Parameters (get)
  • *pVal - Returns a Boolean indicating the current state of the ‘request tracking’ flag.
Parameters (set)
  • val - Boolean value that sets the ‘request’ tracking’ flag
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_reset} Reset** Method
Syntax HRESULT Reset();
Description This function will delete all measurement data collected for this transaction.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

** Row** Property
Syntax HRESULT Row([out, retval] int *pVal); HRESULT Row([in] int val);
Description This function accesses the current profile ID. The profile IDis a numeric value that indicates which row of data to use from the virtual profile data that can exist in a script.
Parameters (get)
  • *pVal - Returns the current profile ID.
Parameters (set)
  • val - Sets the profile ID.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

** ScriptId** Property
Syntax HRESULT ScriptId([in] BSTR val);
Description Sets the script ID (the transaction ID) to the playback routine. This is normally performed automatically at the start of a transaction.
Parameters
  • val - String representation of the transaction ID
Return value Returns S_OK if successful, or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 

**{:#anchor_scriptsdownloaded} ScriptsDownloaded** Property
Syntax HRESULT ScriptsDownloaded([out, retval] VARIANT_BOOL *pVal); HRESULT ScriptsDownloaded([in] VARIANT_BOOL val);
Description This function determines how the SCRIPT and NOSCRIPT HTML tags is handled. If script loading is enabled, the browser will retrieve any scripts that are stored externally by using the tag’s SRC attribute as the URL. In addition, it will ignore any HTML that is contained within the NOSCRIPT tag. If script loading is disabled, no objects associated with the SCRIPT tags will be retrieved. In addition, the browser will parse any HTML that is contained within the NOSCRIPT tag. 
Parameters (get)
  • *pVal - Returns the current script downloading flag.
Parameters (set)
  • val - Sets (or resets) the script downloading flag.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks The script loading flag defaults to true.

 

 

**{:#anchor_serviceoption} ServiceOption** Property
Syntax HRESULT ServiceOption([in] BSTR val);
Description Sets the service options that dictate the amount of data collection to perform. The following values are permitted:
  • “S”       (SERVICE_MODE_STANDARD )
  • “A”       (SERVICE_MODE_ANALYZE)
  • “F”       (SERVICE_MODE_FULL_ANALYZE)
  • “P”       (SERVICE_MODE_PREMIUM)
Parameters
  • val - Single-character string indicating the service mode to apply to the current transaction
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_sessionrc} SessionRC** Property
Syntax HRESULT SessionRC([out, retval] VARIANT_BOOL *pVal); HRESULT SessionRC([in] VARIANT_BOOL val);
Description This function allows the user to determine the current session status. Both ‘get’ and ‘set’ functions are provided.
Parameters (get)
  • *pVal - A Boolean flag that shows the current session status
Parameters (set)
  • val - Gives the user the ability to set the current session status.
Return value Returns S_OK if successful, or an error value otherwise.
Remarks If the user sets the SessionRC to false, most functions will fail until the session status is restored to true.

 

 

**{:#anchor_setconfiguration} SetConfiguration** Method
Syntax HRESULT SetConfiguration();
Description Establishes the defaults and the user specified parameters for use in the playback engine. These parameters include the enabling of the various download flags, validation rules, content exclusion information, etc.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_setdatadir} SetDataDir** Method
Syntax HRESULT SetDataDir([in] BSTR dir);
Description This function tells the Parameter Manager subsystem what disk sub-directory should be used for this transaction. This is automatically called at the beginning of a transaction
Parameters
  • dir - String indicating the subdirectory to use
Return value Returns S_OK if successful, or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 

** SetErrorDetails** Method
Syntax HRESULT SetErrorDetails(BSTR errorCode, BSTR errorText, BSTR errorPageTitle, BSTR errorHtmlElementText, BSTR errorPageUrl);
Description This function creates a record in the output data stream for MyKeynote use. It is used to communicate additional error information that is of interest to a particular error condition.
Parameters
  • errorCode - The error code to be set
  • errorText - The error text (limit 60 characters)
  • errorPageTitle - The page title (limit 255 characters)
  • errorHtmlElementText - The HTML element text (limit 255 characters)
  • errorPageUrl - The error page URL (limit 2048 characters)
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_setpostbodydata} SetPostBodyData** Method
Syntax HRESULT SetPostBodyData([in] BSTR format, [in] BSTR data, [in] int len, [out, retval] VARIANT_BOOL* pResult);
Description This function sets the post body data for the next HTTP POST request made by this frame. The value for the Content-Type HTTP header for the POST will be the format given. If non NULL post body data is specified, any form data added through use of the Add_Form_Data functions will be ignored.
Parameters
  • format - The MIME type of the data
  • data - The data
  • len - The length of the data, in bytes
  • *pResult - The result
Return value This function returns true if the post body was set successfully. Otherwise, the function returns false.

 

 

**{:#anchor_setpostbodydata2} SetPostBodyData2** Method
Syntax HRESULT SetPostBodyData2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR format, [in] BSTR data, [in] int len, [out, retval] VARIANT_BOOL* pResult);
Description Same as SetPostBodyData (above) but adds the window, frame, and iframe that should be used as the targe for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • format - The MIME type of the data
  • data - The data
  • len - The length of the data, in bytes
  • *pResult - The result
Return value This function returns true if the post body was set successfully. Otherwise, the function returns false.

 

 

**{:#anchor_setpostbodystringdata} SetPostBodyStringData** Method
Syntax HRESULT SetPostBodyStringData([in] BSTR format, [in] BSTR data, [out, retval] VARIANT_BOOL* pResult);
Description This function sets the post body data for the next HTTP POST request made by this frame. The value for the Content-Type HTTP header for the POST will be the format given. Any form data added through use of the Add_Form_Data functions will be ignored.
Parameters
  • format - The MIME type of the data
  • data - The data
  • *pResult - The result
Return value This function returns true if the post body was set successfully. Otherwise, the function returns false.

 

 

**{:#anchor_setpostbodystringdata2} SetPostBodyStringData2** Method
Syntax HRESULT SetPostBodyStringData2([in] int iWindow, [in] BSTR frame, [in] int iFrame, [in] BSTR format, [in] BSTR data, [out, retval] VARIANT_BOOL* pResult);
Description Same as SetPostBodyStringData (above) but adds the window, frame, and iframe that should be used as the targe for adding the data.
Parameters
  • iWindow - Value indicating the window that should be used
  • Frame - Value indicating the frame name that should be used
  • iFrame - Value indicating the iframe that should be used
  • format - The MIME type of the data
  • data - The data
  • *pResult - The result
Return value This function returns true if the post body was set successfully. Otherwise, the function returns false.

 

 

**{:#anchor_settimeoffset} SetTimeOffset** Method
Syntax HRESULT SetTimeOffset([in] long value, [out, retval] VARIANT_BOOL* pResult);
Description This function will tell the playback routine what offset should be applied to the real time clock to get to real time. This function should not ever be required.
Parameters
  • value - Time in milliseconds (positive or negative) to adjust the real-time clock
Return value Returns S_OK if successful, or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 

**{:#anchor_startaction} StartAction** Method
Syntax HRESULT StartAction();
Description Tells the playback browser that a new action has begun.
Parameters  
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_startsession} StartSession** Method
Syntax HRESULT StartSession([in] int pause, [out, retval] int* sessionId);
Description This function notifies the browser that a transaction is beginning. As the beginning of each session, or transaction, the browser clears authentication data, frame contents, form data, the URL cache, and all cookies.
Parameters
  • pause - This is an option variable that indicates how long to pause before beginning this transaction.
  • sessionId - The current session ID, which starts at 0, is returned through this parameter.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

TargetId Property
Syntax HRESULT TargetId([out, retval] int *pVal); HRESULT TargetId([in] int val);
Description This function accesses the current target ID (transaction ID).
Parameters (get)
  • *pVal - Returns the current target ID.
Parameters (set)
  • val - Sets the target ID.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_timeout} Timeout** Property
Syntax HRESULT Timeout([out, retval] int *pVal); HRESULT Timeout([in] int val);
Description This function sets the Internet timeout used by the browser when making HTTP requests. The Internet timeout determines how long the browser will wait before giving up with an error when performing the following actions: establishing the initial connection with a web server, sending an HTTP request, and receiving up to 5000 bytes of return data. The default Internet timeout value is 45000 milliseconds.
Parameters (get)
  • *pVal - Returns the current Internet timeout value.
Parameters (set)
  • val - Sets the Internet timeout value.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_unload} Unload** Method
Syntax HRESULT Unload([in] BSTR script);
Description This will tell the Parameter Manager subsystem to remove from its internal cache, the contents of the current script. This is normally performed automatically at end of the transaction.
Parameters
  • script - A string representation of the transaction ID
Return value Returns S_OK if successful, or an error value otherwise.
Remarks Should not be necessary to call this function directly.

 

 

**{:#anchor_uploadsize} UploadSize** Property
Syntax HRESULT UploadSize([out, retval] int *pVal); HRESULT UploadSize([in] int val);
Description This function determines the length of the string that is generated when the browser encounters an HTML form that uses multipart/form-data encoding. In multipart/form-data forms, INPUT elements of the FILE type are often used to upload files. The browser will generate a string of ‘0’ characters to simulate the effect of sending data to the web server. The default upload size of 10000 characters. The upload size cannot be set above 100,000 characters. To use a custom file data source, the upload size must be set to -1.
Parameters (get)
  • *pVal - Returns the current upload size.
Parameters (set)
  • val - Sets the upload size.
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_username} UserName** Property
Syntax HRESULT UserName([in] BSTR val);
Description This function sets the username that will be used for general authentication for all HTTP requests. If no proxy username is specified, the username also applies to proxy authentication.
Parameters (set)
  • val - The username that will be used for general authentication
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_userpassword} UserPassword** Property
Syntax HRESULT UserPassword([in] BSTR val);
Description This function sets the password that will be used for general authentication for all HTTP requests. If no proxy password is specified, this password also applies to proxy authentication.
Parameters (set)
  • val - The password that will be used for general authentication
Return value Returns S_OK if successful, or an error value otherwise.

 

 

**{:#anchor_windowcount} WindowCount** Property
Syntax HRESULT WindowCount([out, retval] int *pVal);
Description This function returns the number of windows created by the current action.
Parameters (get)
  • *pVal - The number of windows created by the current action
Return value Returns S_OK if successful, or an error value otherwise.