URLCop Taking the "U" in "URL" Seriously Flash Sheridan Apple Newton Systems Group SQA flash@newton.apple.com 6 November 1996 The Problem: A hot new URL type appears (new to the Newton, at least), with a hot new client. If an old application encounters a URL of the new type, what should it do with it? The old application may be concerned only incidentally with the web: It mig ht be a PIM with a slot for a companyÕs URL; it might be a word processor; or it might even be an html browser which was released several days ago. The Solution: The exact wrong answer is to say that the user should wait for existing applications to be updated. On the Macintosh, the answer is now clear, thanks to a great deal of work by the Internet Config freeware team: a single central clearing- house for URL strings. Thanks to the Newton view system, the Newton equivalent was a lot easier to write. All URLCop does is receive a URL string and perhaps some options, and pass them along to an application which has declared that it can handle that type of URL string. It pays no attention to the options, or to the content of the URL; it merely passes them on. GetURL and FetchURL (Clients) Applications which encounter a URL string of a type which they cannot handle should call GetRoot().urlCop:?GetURL(URLstring, nil) This will display the item to the user, if possible; if no handler exists for the given type, a negative error code is returned. If the application wants the value of the item returned instead of displayed, it should call GetRoot().urlCop:?FetchURL(URLstring, nil) These are primarily for normal applications, but can also be used by browsers when they encounter a URL of a type they cannot handle. GetURL and FetchURL (Browsers) Methods in the Base View of Your Application: :GetURL(URLstring, optionsFrame or nil) :FetchURL(URLstring, optionsFrame or nil) The second argument may be ignored; or you may handle as many options as you want. (See the table at the end.) The GetURL method should display to the user the item denoted by the URL string; the FetchURL method should return the value of the item, but not display it. Registering with URLCop (Browsers) GetRoot().urlCop:?RegisterURLHandler( yourAppSymbol, { types: array, GetURL: true, FetchURL: true, version: n }) yourAppSymbol: Your application's symbol. types: An array of strings or symbols, indicating which URL types the registering app is offering to handle, e.g., ['http, 'ftp]. version: An integer. An application which cannot handle the FetchURL (or GetURL) method should omit the corresponding slot. Registering with URLCop: (Fine Print) Transports can also register in the same manner. Registering from your InstallScript is not guaranteed to work if URLCop is not active when youÕre first installed. To be safe, call it also from your ViewSetupDoneScript, or let the user do so manually. Registering again with the same version number wil l do no harm. The values of the GetURL and FetchURL slots can be something other than true, but this is primarily for retrofitting compatibility onto non-standard browsers. Use a symbol to indicate a method in your base view. You can also insert an arbitrary function , which will be performed in the context of the frame. The registry is stored in a soup, so the usual warnings about sucking the universe into a soup entry apply. There are additional, imperfect, options for tie-breaking; see the full documentation for details. The initial version of URLCop had a different name for this method; the old name will continue to be supported, but is deprecated. If the browserÕs registration frame has a slot called 'excludedFileExtensions containing an array of strings, any URL string ending with a member of the array will not be passed to the browser. InetConnected and InetDisconnected GetRoot().(yourAppSymbol):?InetConnected() GetRoot().(yourAppSymbol):?InetDisconnected() If you add InetConnected: TRUE to your registration frame, your application will be conditionally sent the InetConnected method when the Internet Enabler connects. Likewise for the InetDisconnected method. Even if your application is not a conventional browser, you can still receive these notifications by just executing: GetRoot().urlCop:?RegisterURLHandler( yourAppSymbol, { types: [], InetConnected: true, InetDisconnected: true, version: n }) The Options Frame The second argument to GetURL and FetchURL may be a frame or nil. All the slots in this argument are optional, and the precise interpretation of a slot is up to the implementor. Implementors are free to invent other options slots, though they should proba bly discuss naming conventions in comp.sys.newton.programmer beforehand. Slot Type Meaning Save boolean or string If true, save to the default location, normally as an attachment in the InBox. If a string, save to the soup with the specified name on the default store. If nil or missing, do not save, but display if possible. Autoconnect boolean If true, connect without further user intervention. Autodisconnect boolean If true, disconnect after resource is obtained, or after failure. Age integer If the URL is cached and its age is less than this number of minutes, get the cached URL instead. If this is missing or nil, the implementor may always use the cached URL. To ensure that the implementor always gets a fresh copy, make this value -1. ScrollPercentage integer (0 to 100) If present and supported by the receiver, the initial display should be as though the user had scolled scroll% through the resource. (This is definitely optional, but many existing web pages have no significant information until the second Newton screen- full.) Worksite worksite Worksite to use for connection. Parts array of symbols Indicates the only parts that are of interest, e.g., 'title, 'links. 'header. AsType class symbol Return value as this type. Only meaningful for FetchURL. Note that as support for this is optional, the client must still be careful not to make unsafe assumptions about the return value. Converted boolean If non-nil, this method may return an application dependent version of the resource, rather than the unconverted value of the URL. Limitations URLCop only pays attention to the type of a URL string. It knows nothing about the content of the URL. URLCop trusts browsers which register themselves. Like all NewtonScript code, this is subject to abuse, and the only real work-around is for the user not to run badly-written packages. The tie-breaking mechanism could be improved, but would still not be infallible. It is possible to write a prefs editor for the tie-breaker. Send me mail if you want to do this. For the package and full documentation, see .