Data Converters provide an essential operation: conversion of one MIME data type into another MIME data type. This allows Converters to extend the range of data types that the Newton can support.
NetHopper itself will be bundled with Converters for things like text, HTML, JPEG, and GIF. However, we cannot predict all of the data types that clients might ask for. Therefore, we provide this plug-in API so that third parties can extend NetHopper's capabilities.
When NetHopper receives a data type that a converter has been registered for, but can only display some other data type, it calls upon the appropriate Converter. For instance, NetHopper might receive a JPEG image but only have a Data Viewer for displaying PICT images. In this case it might call upon a Converter which supports JPEG to PICT conversion.
The life cycle of a Converter is as follows:
RegistrationManager:RegMIMEDataConverter(converterSym, infoFrame);
In this case, infoFrame contains the following slots:
codeFrame This is a reference to a frame that implements all of the required Data Converter methods. (It doesn't matter whether this frame is read-only since NetHopper will create a RAM frame using this frame as its _proto.)
name This is a user-viewable string that will be used to name your Converter for things like helping the user pick which Converters are activated.
inputTypes This slot should contain an array of input MIME types supported, as described in "Specifying MIME Types" on page 7. This array is used by NetHopper to keep track of which input MIME types are supported by your Converter. NetHopper will only provide your Converter with data of a type that you've claimed to support.
outputTypes This slot should contain an array of output MIME types supported, as described in "Specifying MIME Types" on page 7. This array is used by NetHopper to keep track of which output MIME types are supported by your Converter. NetHopper will only accept data types from your Converter that you've claimed to support. Note: There is an implicit assumption here that your Converter can map between every input MIME type and every output MIME type. If that is not the case, you might consider breaking up your Converter into separate converters for which this is true. <TBD>Is there any problem with this?
preferencesForm This slot should contain a reference to any preferences view template you might have for configuring your Converter. This view might contain things like "resolution" or "bit-depth" preferences in the case of a graphics Converter. 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 you'll typically use system methods such as GetUserConfig(?) and SetUserConfig(?) to persistently store and retrieve these preferences. 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 your Converter, call the following Registration Manager unit method:
RegistrationManager:UnRegMIMEDataConverter(converterSym);
You need to make certain that converterSym is the same for Reg and UnReg.
Your Data Converter needs to provide a few interface methods for NetHopper. The methods are described in the sections that follow.
NetHopper can instantiate a new instance of your Converter using this method. You should use this method to intialize any resources you might need during your conversion.
converter:Instantiate();
This is a basic setup hook method.
NetHopper uses Convert to kick off the actual conversion of data.
converter:Convert(inputStream, outputStream, outputMIMEType);
inputStream is an input stream from which you can Read() data.
outputStream is an outputStream to which you can Write() data.
outputMIMEType is the type of data your Converter should write onto the output stream. To be safe, your Converter should call outputStream:setMIMEDataType(outputMIMEType).
You indicate that you are finished converting by calling Close on the inputStream and Close on the outputStream. This allows your client to detect when you have finished conversion.
NetHopper uses Dispose to tell your Converter to stop any operations in progress and completely release any allocated resources. After this method is called, your Converter will be subject to garbage collection.