This documentation explains how to use Kallisys Newton Libraries. At the time I'm writing this, it only applies to the ZLib and the NIL.
Kallisys Newton Libraries can be interfaced from NewtonScript and from C++.
The NewtonScript interface is based on units. This document briefly explains how to use units, but I suggest that you go and read the documentation in the Q&As and the DTS Sample Code MooUnit. [Note: the Sample Code archive includes the Q&As chapter on Units]
Please note that this documentation applies to NTK. Ask Steve Weyer about how to use units with NDE.
To use a Kallisys Newton Library in your package, you need to include in your NTK project the .unit file provided with the library package. This is a text file for NTK that defines the unit. It also defines a constant for the version of the Kallisys Newton Library. And you'll find there the symbol of the library unit. For example, in the ZLib.unit file, you can read:
DeclareUnit(kZLibSymbol, kZLibMajor, kZLibMinor,
{
...
};
kZLibSymbol is a constant for the symbol of the library unit, kZLibMajor is the major version and kZLibMinor
the minor version.
Once included, you can include in your code any of the objects (functions, prototypes) defined in the unit with the
UnitRef function (you can also use the UR abbreviation for UnitRef). For example, to use ProtoDeflateStream from the ZLib,
just write UR( kZLibSymbol, 'ProtoDeflateStream ). The public objects of the unit (such as
ProtoDeflateStream) are declared in the .unit file and documented in the library documentation.
Units also allow you to know if the library is present at any time in your code. It's a good idea to look if the library is present before using it. You can also be told when the library goes away.
To know if a library is present, you can use the MissingImports function. This function should be passed the package ref of your package. There are several ways to get it, the easiest is to pass it the result of ObjectPkgRef function to which you would have passed an object that is in your package. Note: this won't work if you have been EnsureInternal'd, TotalClone'd. Another way is to call GetPkgRef if you know on which store your package is.
If you're importing only from one library, you could just compare the resulf of MissingImports with nil:
if call kMissingImportsFunc with ( ObjectPkgRef( "Me" ) ) then// "Me" object is in this package.begin// The libraries we're using aren't presentGetRoot():Notify( 3, "MyApp", "I can't work without library Foo" ); end;
If you're importing from several libraries, you may want to decode the result of MissingImports to give a more explicit message to the user or just do it without some libraries. This result is NIL when nothing is missing or an array of frames with three slots, name (a string representing the symbol of the library), major (the major version you're requiring), minor (the minor version you're requiring).
What is great with Units is that the system can ask you for a warning message to display to the user when he's removing a package exporting a unit and tell you when a unit you're importing from has been removed. You cannot prevent the user from removing this unit, you can just tell him that you'll no longer function.
To give a warning message, you need to add a function to the frame part you're importing units from (if you don't know what a frame part is, you have only one in your package). This function is RemovalApproval and could be added with something like this in one of the text files processed by NTK:
SetPartFrameSlot('RemovalApproval, func(unitName, major, minor)
begin
return "This operation will also disable myApp."
end);
unitName is the symbol of the unit in a string, major and minor are the versions. Please note when deciding which string to put that a unit is removed when the package it's in is frozen, deleted or when it's on a store which is removed (however, in the latter case, you won't be called and the user won't be warned).
When the unit is about to be removed, the system will call your function and display a warning to the user who will be able to cancel the operation. If he decides to not cancel it, another function (if you define it) of your package will be called:
SetPartFrameSlot('ImportDisabled, func(unitName, major, minor)
begin
GetRoot().(kAppSymbol):Close();
end);
In this function you can disable any part of your software which uses the library, for example by closing your application.
The Kallisys Newton Libraries provide, in addition to a NewtonScript, a C++ interface for maximum speed of your applications. The functions you can access from C++ are usually primitives of the NewtonScript APIs and can be called from another task than the NewtonScript task. Please report to the individual library documentation for this point.
Since any user interface is ran in the NewtonScript task, there is no way to be told when the library is removed. It shouldn't be a problem if you're calling the C++ APIs from the NewtonScript task, you just need to use the NewtonScript method to close your application nicely or take whatever action is appropriate. If you're calling the C++ APIs from another task, you may want to lock the NewtonScript task with a semaphore until you've finished with the library.
The C++ Interface is based on the P-Class concepts. Please refer to the P-Class documentation in the DDK Introduction manual.
To use a Kallisys Newton Library, you need to link your code with two object files which are provided with the SDK. These two object files include the required glue to access the library. You also need a header file (from which one of the two object files is generated with the ProtocolGen tool) for the definitions of the APIs. There is also a source file (from which the second object file is generated), provided in case you would like to recompile the thing. You don't normally need it. If the library defines any class which you can use, you might need additionnal headers which define them.
The Library Driver is accessed with a static method of the interface class. For example, for the Newton Internet Library, the class
PNIL has a static method called GetNILDriver(). Calling this method returns an object based on the
PNIL class, the driver. You can call the methods of this object as defined in the provided header file.
The Library Driver is always present in memory when the library package is active (it doesn't require much RAM anyway). If the
library package isn't present, the static function GetNILDriver() will return nil.