AmigaDOS Packets - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:22:15Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:22, 26 January 2025
Line 39:		Line 39:
	Exec Message structure and an AmigaDOS DOSPacket structure:		Exec Message structure and an AmigaDOS DOSPacket structure:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct StandardPacket		struct StandardPacket
	{ struct Message sp_Msg;		{ struct Message sp_Msg;
Line 49:		Line 49:
	Message and DOSPacket sections to each other:		Message and DOSPacket sections to each other:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	packet->sp_Msg.mn_Node.ln_Name = (char *) &(packet->sp_Pkt);		packet->sp_Msg.mn_Node.ln_Name = (char *) &(packet->sp_Pkt);
	packet->sp_Pkt.dp_Link = &(packet->sp_Msg);		packet->sp_Pkt.dp_Link = &(packet->sp_Msg);
Line 56:		Line 56:
	Packets must also be initialized with a ReplyPort which is created with AllocSysObject():		Packets must also be initialized with a ReplyPort which is created with AllocSysObject():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	if (replyport = (struct MsgPort *) IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))		if (replyport = (struct MsgPort *) IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
	packet->sp_Pkt.dp_Port = replyport;		packet->sp_Pkt.dp_Port = replyport;
Line 447:		Line 447:

	Finding the MsgPort of a unique named handler process such as "DF0:":		Finding the MsgPort of a unique named handler process such as "DF0:":
	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	port = (struct MsgPort *) IDOS->DeviceProc("DF1:");		port = (struct MsgPort *) IDOS->DeviceProc("DF1:");
	</syntaxhighlight>		</syntaxhighlight>

	Finding the MsgPort of the handler process for an open file:		Finding the MsgPort of the handler process for an open file:
	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	fh = IDOS->Open("CON:0/40/640/140/Test", MODE_NEWFILE);		fh = IDOS->Open("CON:0/40/640/140/Test", MODE_NEWFILE);
	if ((fh) && (fh->Type))		if ((fh) && (fh->Type))
Line 462:		Line 462:

	Finding the MsgPort of your process's console handler:		Finding the MsgPort of your process's console handler:
	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Task* task = IExec->FindTask(NULL);		struct Task* task = IExec->FindTask(NULL);
	if (task->tc_Node.ln_Type == NT_PROCESS)		if (task->tc_Node.ln_Type == NT_PROCESS)

Steven Solie at 18:59, 2 October 2015

2015-10-02T18:59:19Z

← Older revision		Revision as of 18:59, 2 October 2015
Line 86:		Line 86:
	\| int32		\| int32
	\| dp_Res1		\| dp_Res1
	\| For ~~filesystem~~ calls this is the result that would have been returned by the function; eg. Write("W") returns actual length written.		\| For file system calls this is the result that would have been returned by the function; eg. Write("W") returns actual length written.
	\|-		\|-
	\| int32		\| int32
	\| dp_Res2		\| dp_Res2
	\| For ~~filesystem~~ calls this is what would have been returned by IoErr()		\| For file system calls this is what would have been returned by IoErr()
	\|-		\|-
	\| int32		\| int32
Line 130:		Line 130:
	= Packet Types =		= Packet Types =

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

Line 149:		Line 149:

	; Obsolete Packets		; Obsolete Packets
	: These packets are no longer valid for use by handlers/~~filesystems~~.		: These packets are no longer valid for use by handlers/file systems.

	; Deprecated Packets		; Deprecated Packets
	: These packets are superceded by new ones with updated functionality and ~~filesystems~~/handlers should avoid implementing these packets at all and let dos.library emulate the old and limited functionality.		: These packets are superceded by new ones with updated functionality and file systems/handlers should avoid implementing these packets at all and let dos.library emulate the old and limited functionality.

	; Console Only Packets		; Console Only Packets
Line 171:		Line 171:
	\| This is a BCPL pointer to a string where the first byte indicates the number of characters in the string. This length byte is unsigned but because it is stored in only 8 bits, the strings are limited to 255 characters in length before V52 of dos.library.<br/>		\| This is a BCPL pointer to a string where the first byte indicates the number of characters in the string. This length byte is unsigned but because it is stored in only 8 bits, the strings are limited to 255 characters in length before V52 of dos.library.<br/>

	As of V52+ dos.library, "extended BSTR" (XBSTR) strings can be sent to handlers and ~~filesystems~~ from dos.library for extensibility reasons, while still maintaining legacy backward compatibility. These extended BSTR strings are in the same format as a legacy BSTR string but are guaranteed to have a null-terminator byte added to the end, and the length byte of these will be correct only up to 255 characters, past that length, the length byte will always read 255 (0xFF) and is there just for limited legacy compatibility. These extended BSTR strings are always documented and identified by having an additional dospacket identifier parameter supplied, consult the individual DOS packet documentation for details.<br/>		As of V52+ dos.library, "extended BSTR" (XBSTR) strings can be sent to handlers and file systems from dos.library for extensibility reasons, while still maintaining legacy backward compatibility. These extended BSTR strings are in the same format as a legacy BSTR string but are guaranteed to have a null-terminator byte added to the end, and the length byte of these will be correct only up to 255 characters, past that length, the length byte will always read 255 (0xFF) and is there just for limited legacy compatibility. These extended BSTR strings are always documented and identified by having an additional dospacket identifier parameter supplied, consult the individual DOS packet documentation for details.<br/>

	See also ACTION_INHIBIT_DOS_LONGPATH_HANDLING for details on this DOS packet and how to formally control the use of XBSTR strings.		See also ACTION_INHIBIT_DOS_LONGPATH_HANDLING for details on this DOS packet and how to formally control the use of XBSTR strings.

Steven Solie at 20:57, 12 March 2014

2014-03-12T20:57:16Z

← Older revision		Revision as of 20:57, 12 March 2014
Line 1:		Line 1:
	[[Category:DOS]]~~{{WIP}}~~		[[Category:DOS]]
	= Introduction =		= Introduction =

Steven Solie: /* Packet Types */

2014-03-12T20:51:21Z

Packet Types

Show changes

Steven Solie: /* Summary of Defined Packet Numbers */

2014-03-12T20:34:57Z

Summary of Defined Packet Numbers

Show changes

Steven Solie: /* Important Note for AmigaOS 4 Developers */

2014-02-19T00:12:43Z

Important Note for AmigaOS 4 Developers

← Older revision		Revision as of 00:12, 19 February 2014
Line 181:		Line 181:
	=== Important Note for AmigaOS 4 Developers ===		=== Important Note for AmigaOS 4 Developers ===

	The following specification of [[AmigaDOS]] packet types dates back to the original documentation as provided by Commodore-Amiga in an AmigaMail article published concurrently with the release of OS2.0. Developers working on current versions of the Amiga Operating System need to refer to the SDK documentation and included AutoDocs as the following has not been updated to reflect changes in dos.library itself, nor changes to the implementation of FFS, nor to new packet types introduced alongside SFS or JXFS. The following specification is only provided as an additional reference and is to be updated to reflect changes introduced with Release 3 and Release 4 of the operating system.		The following specification of AmigaDOS packet types dates back to the original documentation as provided by Commodore-Amiga in an AmigaMail article published concurrently with the release of OS2.0. Developers working on current versions of the Amiga Operating System need to refer to the SDK documentation and included AutoDocs as the following has not been updated to reflect changes in dos.library itself, nor changes to the implementation of FFS, nor to new packet types introduced alongside SFS or JXFS. The following specification is only provided as an additional reference and is to be updated to reflect changes introduced with Release 3 and Release 4 of the operating system.

	== Basic Input/Output ==		== Basic Input/Output ==

Steven Solie: /* Introduction */

2014-02-19T00:12:16Z

Introduction

← Older revision		Revision as of 00:12, 19 February 2014
Line 39:		Line 39:
	Exec Message structure and an AmigaDOS DOSPacket structure:		Exec Message structure and an AmigaDOS DOSPacket structure:

			<syntaxhighlight>
	struct StandardPacket		struct StandardPacket
	{ struct Message sp_Msg;		{ struct Message sp_Msg;
	struct DOSPacket sp_Pkt;		struct DOSPacket sp_Pkt;
	};		};
			</syntaxhighlight>

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

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

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

			<syntaxhighlight>
	if (replyport = (struct MsgPort *) ~~CreatePort~~(~~NULL~~, 0))		if (replyport = (struct MsgPort *) IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
	packet->sp_Pkt.dp_Port = replyport;		packet->sp_Pkt.dp_Port = replyport;
			</syntaxhighlight>

	The DOSPacket portion of the StandardPacket structure is used to pass the		The DOSPacket portion of the StandardPacket structure is used to pass the
Line 75:		Line 80:
	\| Reply port for the packet. Must be filled in each send		\| Reply port for the packet. Must be filled in each send
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Type		\| dp_Type
	\| Packet type		\| Packet type
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Res1		\| dp_Res1
	\| For filesystem calls this is the result that would have been returned by the function; eg. Write("W") returns actual length written.		\| For filesystem calls this is the result that would have been returned by the function; eg. Write("W") returns actual length written.
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Res2		\| dp_Res2
	\| For filesystem calls this is what would have been returned by IoErr()		\| For filesystem calls this is what would have been returned by IoErr()
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg1		\| dp_Arg1
	\| Argument 1 (depends on packet type)		\| Argument 1 (depends on packet type)
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg2		\| dp_Arg2
	\| Argument 2 (depends on packet type)		\| Argument 2 (depends on packet type)
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg3		\| dp_Arg3
	\| Argument 3 (depends on packet type)		\| Argument 3 (depends on packet type)
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg4		\| dp_Arg4
	\| Argument 4 (depends on packet type)		\| Argument 4 (depends on packet type)
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg5		\| dp_Arg5
	\| Argument 5 (depends on packet type)		\| Argument 5 (depends on packet type)
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg6		\| dp_Arg6
	\| Argument 6 (depends on packet type)		\| Argument 6 (depends on packet type)
	\|-		\|-
	\| ~~LONG~~		\| int32
	\| dp_Arg7		\| dp_Arg7
	\| Argument 7 (depends on packet type)		\| 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.
	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
	All AmigaDOS packets are sent to the message port created as part of a
			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.
	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.
	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 =		= Packet Types =

Steven Solie: /* Using Packets Directly */

2014-02-19T00:08:02Z

Using Packets Directly

Show changes

Steven Solie: /* Summary of Defined Packet Numbers */

2014-02-19T00:03:15Z

Summary of Defined Packet Numbers

Show changes

Steven Solie: /* Important Note for OS4 Developers */

2013-05-13T21:15:00Z

Important Note for OS4 Developers

← Older revision		Revision as of 21:15, 13 May 2013
Line 200:		Line 200:
	\|}		\|}

	=== Important Note for ~~OS4~~ Developers ===		=== Important Note for AmigaOS 4 Developers ===

	The following specification of [[AmigaDOS]] packet types dates back to the original documentation as provided by Commodore-Amiga in an AmigaMail article published concurrently with the release of OS2.0. Developers working on current versions of the Amiga Operating System need to refer to the SDK documentation and included AutoDocs as the following has not been updated to reflect changes in dos.library itself, nor changes to the implementation of FFS, nor to new packet types introduced alongside SFS or JXFS. The following specification is only provided as an additional reference and is to be updated to reflect changes introduced with Release 3 and Release 4 of the operating system.		The following specification of [[AmigaDOS]] packet types dates back to the original documentation as provided by Commodore-Amiga in an AmigaMail article published concurrently with the release of OS2.0. Developers working on current versions of the Amiga Operating System need to refer to the SDK documentation and included AutoDocs as the following has not been updated to reflect changes in dos.library itself, nor changes to the implementation of FFS, nor to new packet types introduced alongside SFS or JXFS. The following specification is only provided as an additional reference and is to be updated to reflect changes introduced with Release 3 and Release 4 of the operating system.