Important: The information in this document is obsolete and should not be used for new development.
Device Manager Parameter Block
The Device Manager provides both a high-level and a low-level interface for communicating with device drivers. You pass information to the low-level functions in a parameter block structure, defined by theParamBlockRec
union.
typedef union ParamBlockRec { IOParam ioParam; FileParam fileParam; VolumeParam volumeParam; CntrlParam cntrlParam; SlotDevParam slotDevParam; MultiDevParam multiDevParam; } ParamBlockRec; typedef ParamBlockRec *ParmBlkPtr;The Device Manager uses two forms of the parameter block: one for the open, close, read, and write functions (theIOParam
structure) and another for the control and status functions (theCntrlParam
structure). Other managers use other structures of theParamBlockRec
union.
typedef struct IOParam { QElemPtr qLink; /* next queue entry */ short qType; /* queue type */ short ioTrap; /* routine trap */ Ptr ioCmdAddr; /* routine address */ ProcPtr ioCompletion; /* completion routine address */ OSErr ioResult; /* result code */ StringPtr ioNamePtr; /* pointer to driver name */ short ioVRefNum; /* volume reference or drive number */ short ioRefNum; /* driver reference number */ char ioVersNum; /* not used by the Device Manager */ char ioPermssn; /* read/write permission */ Ptr ioMisc; /* not used by the Device Manager */ Ptr ioBuffer; /* pointer to data buffer */ long ioReqCount; /* requested number of bytes */ long ioActCount; /* actual number of bytes completed */ short ioPosMode; /* positioning mode */ long ioPosOffset; /* positioning offset */ } IOParam; typedef struct CntrlParam { QElemPtr qLink; /* next queue entry */ short qType; /* queue type */ short ioTrap; /* routine trap */ Ptr ioCmdAddr; /* routine address */ ProcPtr ioCompletion; /* completion routine address */ OSErr ioResult; /* result code */ StringPtr ioNamePtr; /* pointer to driver name */ short ioVRefNum; /* volume reference or drive number */ short ioCRefNum; /* driver reference number */ short csCode; /* type of control or status request */ short csParam[11]; /* control or status information */ } CntrlParam;The first eight fields are common to both structures. Each structure also includes its own unique fields.
Field descriptions for fields common to both structures
Field descriptions for the
qLink
- A pointer to the next entry in the driver I/O queue. (This field is used internally by the Device Manager to keep track of asynchronous calls awaiting execution.)
qType
- The queue type. (This field is used internally by the Device Manager.)
ioTrap
- The trap number of the routine that was called. (This field is used internally by the Device Manager.)
ioCmdAddr
- The address of the routine that was called. (This field is used internally by the Device Manager.)
ioCompletion
- A pointer to a completion routine. When making asynchronous requests, you must set this field to
nil
if you are not specifying a completion routine. The Device Manager automatically sets this field tonil
when you make a synchronous request.ioResult
- A value indicating whether the routine completed successfully. The Device Manager sets this field to 1 when it queues an asynchronous request. When the driver completes the request, it places the actual result code in this field. You can poll this field to detect when the driver has completed the request and to determine its result code. The Device Manager executes the completion routine after this field receives the result code.
ioNamePtr
- A pointer to the name of the driver. You use this field only when opening a driver.
ioVRefNum
- The drive number, if any. The meaning of this field depends on the device driver. The Disk Driver uses this field to identify disk devices.
IOParam
structure
ioRefNum
- The driver reference number.
ioVersNum
- Not used.
ioPermssn
- The read/write permission of the driver. When you open a driver, you must supply one of the following values in this field:
enum {/* access permissions */ fsCurPerm = 0, /* retain current permission */ fsRdPerm = 1, /* allow reads only */ fsWrPerm = 2, /* allow writes only */ fsRdWrPerm = 3/* allow reads and writes
*/};
- The Device Manager compares subsequent read and write requests with the read/write permission of the driver. If the request type is not permitted, the Device Manager returns a result code indicating the error.
ioMisc
- Not used.
ioBuffer
- A pointer to the data buffer for the driver to use for reads or writes.
ioReqCount
- The requested number of bytes for the driver to read or write.
ioActCount
- The actual number of bytes the driver reads or writes.
ioPosMode
- The positioning mode used by drivers of block devices. Bits 0 and 1 of this field indicate where an operation should begin relative to the physical beginning of the block-formatted medium. You can use the following constants to test or set the value of these bits:
enum { /* positioning modes */ fsAtMark = 0, /* at current position */ fsFromStart = 1, /* offset from beginning */ fsFromMark = 3 /* offset from current position */ };
- The Disk Driver allows you to add the following constant to this field to specify a read-verify operation:
enum { rdVerify = 64 /* read-verify mode */ };
Field descriptions for the
- See the description of the
PBRead
function on page 1-70.ioPosOffset
- The byte offset, relative to the position specified by the positioning mode, where the driver should perform the operation. If you specify the
fsAtMark
positioning mode, the Device Manager ignores this field.CntrlParam
structure
ioCRefNum
- The driver reference number.
csCode
- A value identifying the type of control or status request. Each driver may interpret this number differently.
csParam
- The control or status information passed to or from the driver. This field is declared generically as an array of eleven integers. Each driver may interpret the contents of this field differently. Refer to the driver's documentation for specific information.