====== Native Features Best Practice =======

The entry point to any Native Features functionality from a user application is device driver entry that is accessible in your DEVDIR folder. Every such driver has to provide its own 'protocol' description which needs to be followed in order to be able to successfully use it. An example of such protocol can be the MultiTOS introduced Drag & Drop protocol as described in the Atari Compendium.

The described approach brings number of advantages:

   * The application works in all TOS compatible systems.

   * Any Native Feature that the application uses can be implemented in multiple ways (possibly using a future HW extension) with no change to the application itself.

   * Uses designated OS extension mechanisms and therefore does not violate any rules for example for memory protection or virtual memory to work.

   * It makes also old applications be able to use the new features.

\\ 
**SO REMEMBER! There is no better or easier way to access Native Feature functionality from any application.**

At this point people tend to start complaining that when they know all the
technical details then it is possible to access Native Features also
differently and that there is no need to use the device drivers.

Well, let me give you a couple of wrong examples:

   * there are for illustration many applications that attempt to use the TOS's internal Line-A interfaces that were never completely documented. Those applications do not work properly on Atari clone machines for example for only one reason: They used an interface from a different layer of the operating system that was not guaranteed to stay compatible.

   * Another wrong approach is to use the TOS Cookie Jar to get a pointer to a structure of functions to be used to perform actions. This has been discussed several times in the FreeMiNT mailing list that it is a good way of preventing your application to be usable with memory protection. In general this violates the access permissions and must not be used by any new applications any more.

Still not convinced? In that case I can only recommend to ask someone more experienced to explain that to you so that you could understand the problem.

====== Example ======

===== Usage =====

With a properly installed device driver (in FreeMiNT or using BetaDOS
in TOS) you can send a file to the emulator's stderr output (the native
console) as follows:

<code>
$ cat mytextfile.txt > /dev/nfstderr
</code>

Note: The previous example is from FreeMiNT shell. In other environments
this would be rather to the ''x:\dev'' folder (substitute ''x:'' with the
appropriate drive).

You can as well start your favorite text editor and 'Save as...' any file
to the ''x:\dev\nfstderr'' entry which will send it to the console as well
(under FreeMiNT the ''x:'' will always be ''u:'').


In order to get the whole thing independent of the drive letter in the ''x:\dev''
we define the DEVDIR environment variable to point to the right one so that
applications work regardles of where it is configured.

If you think about how the ''cat'' and ''QED'' access the ''x:\dev\nfstderr''
then you will find that it is using simple file IO functions. For example
the following C snippet would write the ''Test NF_STDERR'' to the native
console:

<code>
char devname[64];
char *devdir = getenv("DEVDIR");

/* construct the device name "$DEVDIR\\nfstderr" */
strcpy( devname, devdir ? devdir : "u:\\dev" );
strcat( devname, "\\nfstderr");

FILE *f = fopen(devname, "w");
if ( f) {
      char buf[] = "Test NF_STDERR\r\n";
      fwrite(buf, strlen(buf), 1, f);
      fclose( f);
}
</code>

[[natfeats:example|Here is a more detailed example]] available including
the actual code pieces you need to write such OS extension. There you can also
find more references to driver implementations present in the FreeMiNT and
ARAnyM cvs repositories.


====== Driver installation =====

===== FreeMiNT =====

Under FreeMiNT this is very straightforward and well documented. The only
thing to do is to install the particular FreeMiNT module (''.xfs'', ''.xdd'', ''.xif''
or other) to the appropriate folder according to the FreeMiNT documentation.
Usually this is the ''c:\mint\[1-16-X]'' folder. In our case you would install
the ''nfstderr.xdd'' there.

===== Other OSes =====

A little more tricky is to get the above described setup in TOS environment.
The same should AFAIK work for MagiC as well. All the drivers there are to
be used with BetaDOS. So you first need to install BetaDOS properly.

In order to get the ''x:\dev'' folder you need to configure BetaDOS to install
the dev.dos driver to the drive ''x:''. This is similar to CD-ROM access
driver configuration in BetaDOS.  

You need to put the dos.dev to the C:\auto folder and add the following line
to BDCONFIG.SYS (the ''X:'' in the ''X:2'' there corresponds to the ''x:'' in the ''x:\dev'' folder name):

<code>
*DOS, DEV.DOS, X:2
</code>

To get the x:\dev\nfstderr you need to install the nfstderr.bos driver
the following way:

<code>
*BOS, NFSTDERR.BOS, E:A
</code>

The '':A'' section there is not significant. Only the ''E'' must be unique
among the BOS drivers installed (this is the internal BOS device number
- see BetaDOS documentation for more).