Data Handlers handle MIME data types that NetHopper does not otherwise support. Data Handlers leverage the Protocols and Converters built in to NetHopper to effectively handle new data types.
A Data Handler supports offline handling/storage of non-viewable data. (Other NetHopper 3.0 extensions will support viewable data types such as images and documents.) Some good examples of data types which cannot be "viewed" from inside the NetHopper shell, but which need to be handled are: Newton packages and Newton iobox items. In the case of Newton packages, you might want to install the package or place it in the iobox. In the case of Newton iobox items, you might want to put away the item to the right place or place it in the iobox. It both cases it doesn't really make sense to open a "viewer" inside NetHopper to "look" at these data types.
Whenever the user requests some data of a type which cannot be displayed but for which there is a registered Data Handler, NetHopper will request that the data handler do something with the incoming data. The behavior is similar to the "Helper Applications" that Netscape uses to handle extended data types.
NetHopper opens a data stream hands that stream to the Data Handler when it instantiates a new instance of the Handler. NetHopper also calls the Handler's showStatus method so that the Handler can display its progress to the user. It is the Data Handler's job to read the data stream until it encounters an EOF, and process the data as is appropriate for that data type on the Newton platform.
The NetHopper Registration Manager unit provides a method for registering Data Handlers. All Data Handlers must use this method to tell NetHopper they are installed:
RegistrationManager:RegMIMEDataHandler(handlerSym, infoFrame);
The handlerSym must be a symbol with your developer signature appended (ex: '|FooDataHandler:ALLPEN|) to avoid collisions.
infoFrame contains the following slots:
codeFrame This is a reference to a frame that implements all of the required Data Handler methods.
name This is a user-viewable string that will be used to name your Handler for things helping the user configure which Handlers are activated.
types This slot should contain an array of MIME types supported, as described in "Specifying MIME Types". This array is used by NetHopper to keep track of which MIME types are supported by your Handler. NetHopper will only provide your Handler with data of a type that you've claimed to support.
preferencesForm This slot should contain a reference to any preferences view template you might have for configuring your Handler. This view might contain things like an auto-putaway preference. The default value is NIL, no preference view. If this slot exists and is non-NIL, this view will be displayed when the user picks "(name) Prefs" in the NetHopper preferences view. Note that this view template must use protoPrefsRollItem as its template and must have its overview slot set to the name of this prefs view as it should appear in the NetHopper prefs.
To unregister a Data Handler, call the UnRegMIMEDataHandler method:
RegistrationManager:UnRegMIMEDataHandler(handlerSym);
This method removes the Handler named by handlerSym from the Registration Manager's Data Handler registry.
<A Handler can be thought of as a stream sink, as opposed to a stream source or a stream filter. The Handler reads from the incoming data stream but does not generate an outgoing data stream that any part of NetHopper is interested in.>
A Handler must provide a few simple methods:
Initialize this instance of your Handler with the given parameters. NetHopper takes the codeFrame you provided during registration, creates a frame using codeFrame as the _proto, and calls the frame's inherited Instantiate method.
dataHandler:Instantiate(content, uniqueHandlerID, cbContext, cbMethodSym);
The parameters passed to Instantiate are described below.
content is a reference to a content descriptor frame from which your Handler can read data.
uniqueHandlerID is an identifier that you must pass back to your client in your callback. This ID helps your client determine which Handler has completed. Your Handler should simply save this token and return it in the Instantiate callback.
cbContext and cbMethodSym are provided by NetHopper so that your Handler can provide notice of when it is finished (for whatever reason). To notify NetHopper when your Handler is done, use something like the following code snippet:
AddDeferredSend(cbContext, cbMethodSym,[anyError, uniqueHandlerID]);
In the anyError parameter, place either an integer error code (-48404 or whatever) or NIL for no error.
In the uniqueHandlerID parameter, place the uniqueHandlerID which was passed into your Instantiate method. This helps your client determine which Data Handler's transaction has completed.
After you call this callback, your client will teardown your Handler by calling its Dispose method (see below), or it will call Instantiate again with a new input stream and callback parameters. This means that after you complete one transaction you should be prepared to handled another transaction or be disposed.
Stop any outstanding operations and clear all of the resources allocated. NetHopper calls this method after your Handler has finished its operations. NetHopper might also call this method if the user suddenly closes the NetHopper application. Your Handler should clean-up all of its allocated resources and prepare for garbage collection.
dataHandler:Dispose();
NetHopper guarantees that after your Handler's Dispose method is called, no further operations (other than garbage collection) will be allowed on that instance of your Handler.
To determine whether you should display the status of your transaction, use the URL Manipulator's GetStatusDisplayMode to find out whether status display was requested for this transaction. The transaction request frame is stored in content.transReq.