Some devices, in addition to their commands, provide library-style
functions which can be directly called by applications.  These functions
are documented in the device specific FD files and Autodocs of the Amiga
ROM Kernel Reference Manual: includes and autodocs, and in the devices
volume of this manual set.

Devices with functions behave much like Amiga libraries, i.e., you set up
a base address pointer and call the functions as offsets from the pointer.
See the "exec libraries" chapter for more information.

The procedure for accessing a device's functions is as follows:

  * Declare the device base address variable in the global data area.
    The correct name for the base address can be found in the device's FD
    file.

  * Create a message port data structure.

  * Create an I/O request data structure.

  * Call opendevice(), passing the i/o request.  if opendevice() is
    successful (returns 0), the address of the device base may be found
    in the io_device field of the i/o request structure. consult the
    include file for the structure you are using to determine the full
    name of the io_Device field.  The base address is only valid while
    the device is open.

  * Set the device base address variable to the pointer returned in the
    io_device field.

We will use the timer device to illustrate the above method.  The name of
the timer device base address is listed in its FD file as TimerBase.


#include <devices/timer.h>

struct Library *TimerBase;            /* device base address pointer */
struct MsgPort *TimerMP;              /* message port pointer        */
struct timerequest *TimerIO;          /* I/O request pointer         */

if (TimerMP=CreatePort(NULL,NULL))    /* Create the message port.    */
{
    /* Create the I/O request.  */
    if ( TimerIO = (struct timerequest *)
         CreateExtIO(TimerMP,sizeof(struct timerequest)) )
    {
        /* Open the timer device.  */
        if ( !(OpenDevice(TIMERNAME,UNIT_MICROHZ,TimerIO,0)) )
        {
            /* Set up pointer for timer functions.  */
            TimerBase = (struct Library *)TimerIO->tr_node.io_device;

            /* Use timer device library-style functions such as /*
            /* CmpTime() ...*/

            CloseDevice(TimerIO);     /* Close the timer device. */
        }
        else
            printf("Error: Could not open %s\n",TIMERNAME);
    }
    else
        printf("Error: Could not create I/O request\n");
}
else
    printf("Error: Could not create message port\n");
}