NetHopper 3.0 URL Manipulator API

URL Manipulator Introduction

NetHopper 3.0 provides an entity called the URL Manipulator, which provides web transaction services:

Services for converting string URLs into web transaction requests

And so on....

URL Strings, Whole URLs, and Transaction Requests

NetHopper 3.0 provides numerous facilities for processing URLs and transaction requests.

There are three kinds of URL-like entities to deal with here: raw URL strings, wholeURL frames, and transaction request frames. URL strings are simply the standard URL strings a user my type in, or which an HTML document might list in a hyperlink reference. A URL string might be relative to a base URL.

WholeURL frames are a parsed version of the URL string which includes more contect information and is guaranteed to be an absolute URL. In addition, a wholeURL separates the basic URL information from "extra data" (typically form data), for faster processing.

A transaction request frame includes even more context than a wholeURL by precisely defining the protocol "method" to be used, authentication information, caching modes, and user status display flags.

Most of the NetHopper APIs accept transaction request frames; however, the user typically wants to type in URL strings. The URL Manipulator provides all the methods you'll need to bridge between the two worlds.

Accessing the URL Manipulator

The URL Manipulator is a ROM portion of the NetHopper Core. You access the URL Manipulator using a Unit interface. Simply include the "URL.unit" file in your project then access the URL manipulator using a unit refernce:

UnitReference( kURLUnitSymbol,kURLInterfaceSubUnitSymbol);

Note: If the NetHopper Core isn't installed, this unit reference will be bogus. You should use the kMissingImportsFunc at runtime to determine whether your package is missing any unit reference imports.

URL String and WholeURL Manipulation Functions

The Transaction Core provides a subunit for manipulating URL strings and wholeURL frames. This subunit can currently be accessed by referencing TransactionManager.fURLManipulator. In the following sections this reference will be referred to as the URLManipulator.

Note: the URL manipulation code is now exported as a unit separate from the Transaction Core.

Converting a URL String to a wholeURL Frame

Typically a URL arrives in the form of a full or relative URL string. These strings need to be parsed into something more useful. This converstion converts a string URL to a wholeURL frame. The Transaction Core provides methods for parsing URL strings into wholeURL frames. The wholeURL frame holds all of the info in a URL string in a useful format.

wholeURL :=

URLManipulator:NewWholeURLFromString(URLstring);

//take a URL string in, return a new wholeURL object

wholeURL :=

URLManipulator:NewWholeURLFromBaseAndRelativeString(baseWholeURL, relativeURLstr);

//take a base wholeURL and a relative URL string, return new wholeURL object

Testing wholeURL Equality

You can test two whole URLs for equality by calling the method URLEqual. This method takes as parameters the two wholeURLs you wish to test.

Boolean areEqual := URLManipulator:URLEqual(aWholeURL, bWholeURL);

//take two whole URLs, determine if they're equal

Accessing Various Parts of a Whole URL

You can use the following methods to access specific parts of a whole URL.

String filenameStr := URLManipulator:GetFilename(aWholeURL); //return the directory & filename for this wholeURL, if any

String hostStr := URLManipulator:GetHost(aWholeURL);//return the host domain name string, if any

Int portNumber := URLManipulator:GetPort(aWholeURL); //return the port number, if any

String protocolName := URLManipulator:GetProtocol(aWholeURL); //return the protocol string, if any

String refStr := URLManipulator:GetRef(aWholeURL); //return the marker or "ref" str (something like <A name="#myRef">), if any

Example: in the URL "http://www.allpen.com:80/nethopper-api/URL_unit_info.html#aName" the parts are:

• filnameStr: "/nethopper-api/URL_unit_info.html"
• hostStr: "www.allpen.com"
• portNumber: 80
• protocolName: "http"
• refStr: "aName" (a marker for the anchor with name "aName")

Converting a Whole URL to a String

Sometimes you'll want to generate a string representation of a wholeURL. To do this, use the ToString method as follows:

String newURLString := URLManipulator:ToString(aWholeURL);

//convert a wholeURL frame into a human-readable string

Transaction Request Manipulation Functions

The URL Manipulator provides some additional methods for manipulating Transaction Requests.

Generating a Transaction Request Frame from a wholeURL

In order to use a wholeURL to perform transactions, you need to insert the wholeURL into a transaction request frame.

transactionRequest :=

URLManipulator:BuildDefaultDocumentRequest(wholeURL);

You can then manipulate and pass off this transaction request frame to a Transaction Manager.

Getting Extra Data

A transaction's "extra data" is typically used for things like posting forms data. You can access the whole URL's extra data by using the method GetExtraData as follows:

String extraDataStr := URLManipulator:GetExtraData(transactionRequest);

//return the extra data for this request (such as form data), if any

Setting Extra Data

You can set the whole URL's extra data by using the method SetExtraData as follows:

URLManipulator:SetExtraData(transactionRequest, "name1=value1&name2=value2&name3=value3");

//stuff in form data....NOTE that "?" should NOT be prepended to data string

Setting the Transaction Protocol Mode

URLs themselves are "incomplete" transaction requests. You need to specify additional context to provide a complete transaction request. For instance, HTTP 1.0 has three protocol modes: GET, POST, and HEAD. By default the protocol mode is assumed to be GET, but there is no place to specify the mode in an HTTP URL. A transaction request frame provides this additional context so that you can specify the non-default transaction mode.

Most protocols support more than one transaction mode; however, most URLs do not specify the kind of transaction to execute. For instance, you can both send and receive files using FTP, but by default an FTP URL specifies a receive transaction. Because of this, a transaction request frame provides a context around a URL in which you can specify the transaction mode you wish to carry out.

You can set the protocol mode that NetHopper uses as follows

URLManipulator:SetProtocolMode(transactionRequest, kProtocolMethodPOST);

This example sets the transaction mode to HTTP POST. In the case of HTTP this tells the HTTP protocol to post some data and wait for a response.

Setting the "Use Caches" Mode for a Transaction

You can set whether the Transaction Request should pull data from any local caches. If you set this value to TRUE (the default), local caches are searched for the content first. If you set this value to NIL, the local cache is ignored.

URLManipulator:SetUseCaches(transactionRequest, lookAtCache);

Where lookAtCache is a boolean-- TRUE or NIL.

Controlling User Status Display for a Transaction

You can control whether transaction status is displayed to the user by setting a slot in the transaction frame:

URLManipulator:SetStatusDisplayMode(transactionRequest, mode);

Where mode can be one of the following:

• 'quiet. This turns off user status display. This allows "background" transactions, but it also means that your application is responsible for displaying status or logging errors for the user's benefit.
• 'verbose. This shows everything to the user.

The complementary method to SetStatusDisplayMode is GetStatusDisplayMode:

displayMode := URLManipulator:GetStatusDisplayMode(transactionRequest);

Where displayMode is one of the symbols given above.