AmigaDOS Packets

Packet passing handles all communication performed by AmigaDOS between processes. The function diagram below shows how packets fit in with the other components of the Amiga operating system.

   +--------------+
   | User Process +-----------------------+
   +-------+------+                       |
           |                              |
           |                              |
    Function Calls                        |
           |                              |
          \|/                             |
 +---------+--------+                     |
 | AmigaDOS Open(), |                     |
 |   Close(), etc.  |                     |
 +---------+--------+                     |
           |                              |
           |                              |
      +-Packets---+--------+     +-----Packets--------+
      |           |        |     |        |           |
     \|/         \|/      \|/   \|/      \|/         \|/
 +----+----+ +----+----+ +-+--+--+-+ +----+----+ +----+----+
 | FFS/OFS | | FFS/OFS | | FFS/OFS | |   CON:  | |   CON:  |
 |   DH0:  | |   DF0:  | |   DF1:  | | Window1 | | Window2 |
 | Handler | | Handler | | Handler | | Handler | | Handler |
 | Process | | Process | | Process | | Process | | Process |
 +----+----+ +-------+-+ +----+----+ +----+----+ +----+----+
      |              |        |           |           |
     \|/            \|/      \|/         \|/         \|/
 +----+--------+  +--+--------+----+ +----+-----------+----+
 |Hddisk.device|  |Trackdisk.device| |    Console.device   |
 +-------------+  +----------------+ +---------------------+

A StandardPacket (defined in <dos/dosextens.h>) is used to send packet commands to a process's MsgPort. The StandardPacket structure contains an Exec Message structure and an AmigaDOS DOSPacket structure:

   struct StandardPacket
   {   struct Message   sp_Msg;
       struct DOSPacket sp_Pkt;
   };

This structure must be longword-aligned, and initialized to link the Message and DOSPacket sections to each other:

   packet->sp_Msg.mn_Node.ln_Name = (char *) &(packet->sp_Pkt);
   packet->sp_Pkt.dp_Link         = &(packet->sp_Msg);

Packets must also be initialized with a ReplyPort which can be created with the amiga.lib function CreatePort():

   if (replyport = (struct MsgPort *) CreatePort(NULL, 0))
       packet->sp_Pkt.dp_Port = replyport;

The DOSPacket portion of the StandardPacket structure is used to pass the packet type and arguments, and to receive the results of the packet. The argument types, number of arguments, and results vary for different packet types and are documented with each packet description. A DOSPacket must be longword-aligned and has the following general structure:

Type	Name	Description
struct Message*	dp_Link	Pointer back to Exec message structure
struct Message*	dp_Port	Reply port for the packet. Must be filled in each send
LONG	dp_Type	Packet type
LONG	dp_Res1	For filesystem calls this is the result that would have been returned by the function; eg. Write("W") returns actual length written.
LONG	dp_Res2	For filesystem calls this is what would have been returned by IoErr()
LONG	dp_Arg1	Argument [1] (depends on packet type)
LONG	dp_Arg2	Argument 2 (depends on packet type)
LONG	dp_Arg3	Argument 3 (depends on packet type)
LONG	dp_Arg4	Argument 4 (depends on packet type)
LONG	dp_Arg5	Argument 5 (depends on packet type)
LONG	dp_Arg6	Argument 6 (depends on packet type)
LONG	dp_Arg7	Argument 7 (depends on packet type)

The format of a specific packet depends on its type; but in all cases it contains a back-pointer to the Message structure, the MsgPort for the reply, and two result fields. When AmigaDOS sends a packet, the reply port is overwritten with the process ID of the sender so that the packet can be returned. Thus, when sending a packet to an AmigaDOS handler process, you must fill in the reply MsgPort each time; otherwise when the packet returns, AmigaDOS has overwritten the original port. AmigaDOS maintains all other fields except the result fields.

All AmigaDOS packets are sent to the message port created as part of a process; this message port is initialized so that arriving messages cause signal bit 8 to be set. An AmigaDOS process that is waiting for a message waits for signal 8 to be set. When the process wakes up because this event has occurred, GetMsg() takes the message from the message port and extracts the packet address. If the process is an AmigaDOS handler process, then the packet contains a value in the PktType field that indicates an action to be performed, such as reading some data. The argument fields contain specific information such as the size of the buffer where the characters go.

When the handler process has completed the work required to satisfy this request, the packet returns to the sender, using the same message structure. Both the message structure and the packet structure must be allocated by the client and not deallocated before the reply has been received. Normally AmigaDOS is called by the client to send the packet, such as when a call to Read() is made. However, there are cases where asynchronous I/O is required, and in this case the client may send packets to the handler process as required. The packet and message structures must be allocated, and the process ID field filled in with the message port where this packet must return. A call to PutMsg() then sends the message to the destination. Note that many packets may be sent out, returning to either the same or different message ports.

Packet Types

Packets sent to a filesystem or handler can be divided into several basic categories:

Basic Input/Output.

These actions deal with transferring data to and from objects controlled by the handler.

File/Directory Manipulation/Information.

These actions are used to gain access to and manipulate the high-level structures of the filesystem.

Volume Manipulation/Information.

These actions allow access to the specific volume controlled by the filesystem.

Handler Maintenance and Control.

These actions allow control over the handler/filesystem itself, independent of the actual volume or structure underneath.

Handler Internal.

These actions are never sent to the handler directly. Instead they are generally responses to I/O requests made by the handler. The handler makes these responses look like packets to simplify processing.

Obsolete Packets.

These packets are no longer valid for use by handlers and filesystems.

Console Only Packets.

These packets are specific to console handlers. Filesystems can ignore these packets.

Each packet type documented in this section is listed with its action name, its corresponding number, any AmigaDOS routines that use this packet, and the list of parameters that the packet uses. The C variable types for the packet parameters are one of the following types:

   BPTR    This is a BCPL pointer (the address of the given object
           shifted right by 2). @{b}Note:@{ub} This means that the object must be
           aligned on a longword boundary.
   LOCK    This is a BPTR to a FileLock structure returned by a previous
           ACTION_LOCATE_OBJECT. A lock of 0 is legal, indicating the
           root of the volume for the handler.
   BSTR    This is a BPTR to a string where the first byte indicates the
           number of characters in the string. A byte of this length is
           unsigned but because the information is stored in a byte, the
           strings are limited to 255 characters in length.
   BOOL    A 32-bit boolean value either containing DOSTRUE (-1) or
           DOSFALSE (0). @{b}Note:@{ub}Equality comparisons with DOSTRUE should be
           avoided.
   CODE    A 32-bit error code as defined in the <dos/dos.h> include
           file. Handlers should not return error codes besides those
           defined in <dos/dos.h>.
   ARG1    The FileHandle->fh_Arg1 field.
   LONG    A 32-bit integer value.