Accessing a device requires obtaining a message port, allocating memory for a specialized message packet called an I/O request, setting a pointer to the message port in the I/O request, and finally, establishing the link to the device itself by opening it. An example of how to do this will be provided later in this chapter. The message port is used by the device to return messages to you. A message port is obtained by calling the CreateMsgPort() or CreatePort() function. You must delete the message port when you are finished by calling the DeleteMsgPort() or DeletePort() function. For pre-V36 versions of the operating system (before Release 2.0), use the amiga.lib functions CreatePort() and DeletePort(); for V36 and higher, use the Exec functions CreateMsgPort() and DeleteMsgPort(). CreatePort() and DeletePort() are upward compatible, you can use them with V36/V37; CreateMsgPort() and DeleteMsgPort() are not backward compatible, however. The I/O request is used to send commands and data from your application to the device. The I/O request consists of fields used to hold the command you wish to execute and any parameters it requires. You set up the fields with the appropriate information and send it to the device by using Exec I/O functions. At least four methods exist for creating an I/O request: * Declaring it as a structure. The memory required will be allocated at compile time. * Declaring it as a pointer and calling the AllocMem() function. You will have to call the FreeMem() function to release the memory when you are done. * Declaring it as a pointer and calling the CreateExtIO() function. This function not only allocates the memory for the request, it also puts the message port in the I/O request. You will have to call the DeleteExtIO() function to delete the I/O request when you are done. This is the pre-V36 method (used in 1.3 and earlier versions of the operating system), but is upward compatible. * Declaring it as a pointer and calling the CreateIORequest() function. This function not only allocates the memory for the request, it also puts the message port in the I/O request. You will have to call the DeleteIORequest() function to delete the I/O request when you are done. This is the V36/V37 method; it is not backwards compatible. The message port pointer in the I/O request tells the device where to respond with messages for your application. You must set a pointer to the message port in the I/O request if you declare it as a structure or allocate memory for it using AllocMem(). The device is opened by calling the OpenDevice() function. In addition to establishing the link to the device, OpenDevice() also initializes fields in the I/O request. OpenDevice() has this format: return = OpenDevice(device_name,unit_number, (struct IORequest *)IORequest,flags) where: * device_name is one of the following NULL-terminated strings for system devices: audio.device keyboard.device serial.device clipboard.device narrator.device timer.device console.device parallel.device trackdisk.device gameport.device printer.device input.device scsi.device * unit_number refers to one of the logical units of the device. Devices with one unit always use unit 0. Multiple unit devices like the trackdisk device and the timer device use the different units for specific purposes. The device chapters discuss the units in detail. * IORequest is the structure discussed above. Some of the devices have their own I/O requests defined in their include files and others use standard I/O requests, (IOStdReq). The device chapters list the I/O request that each device requires. * flags are bits set to indicate options for some of the devices. This field is set to zero for devices which don't accept options when they are opened. The device chapters and autodocs list the flags values and uses. * return is an indication of whether the OpenDevice() was successful with zero indicating success. Never assume that a device will successfully open. Check the return value and act accordingly. Zero Equals Success for OpenDevice(). ------------------------------------- Unlike most Amiga system functions, OpenDevice() returns zero for success and a device-specific error value for failure.
[Back to Amiga Developer Docs]