All DatabasesInside Mac - Basic Toolbox
PBOpenSync
PBOpen Open the named device driver
#include <Files.h> Device Manager
OSErr PBOpen(pb, async );
ParmBlkPtr pb ; address of a 50-byte IOParam structure
Boolean async ; 0=await completion; 1=immediate return
returns Error Code; 0=no error
PBOpen is used by the File Manager and the Device Manager.
File Manager Usage
PBOpen opens the data fork of a file, enabling I/O operations. It is
functionally equivalent to FSOpen, except that you can use your own local file
buffer (a.k.a. access path), you can specify a File Permission level, and the
function can be executed asynchronously.
pb is the address of a 50-byte IOParam structure. The following fields
are relevant for File Manager usage:
Out-In Name Type Size Offset Description
-> ioCompletion ProcPtr 4 12 Completion routine address (if async = TRUE )
-> ioNamePtr StringPtr 4 18 Address of full or partial path/ filename
-> ioVRefNum short 2 22 Volume or working directory ref; 0= default
-> ioVersNum SignedByte 1 26 Version (best to use 0, must use 0 on HFS)
-> ioPermssn SignedByte 1 27 File Permission (1=read, 2=write, et.al)
-> ioMisc Ptr 4 28 Address of 522-byte buffer (0=use volume buf)
<- ioResult OSErr 2 16 Error Code (0=no error, 1=not done yet)
<- ioRefNum short 2 24 Receives file reference number
async is a Boolean value. Use FALSE for normal (synchronous) operation
or TRUE to enqueue the request and resume control immediately. See
Async I/O.
File Mgr Returns: an operating system Error Code. It will be one of:
noErr (0) No error
bdNamErr (-37) Bad name
extFSErr (-58) External file system
fnfErr (-43) File not found
ioErr (-36) I/O error
nsvErr (-35) No such volume
opWrErr (-49) File already open for writing
permErr (-54) Attempt to open locked file
tmfoErr (-42) Too many files open
File Mgr Notes:
PBOpen opens an access path for the file identified by ioVRefNum and
ioNamePtr. If ioVRefNum is 0, the current default volume and directory is
assumed (see SetVol).
The ioParam.ioPermssn field specifies read-only, read/write, and sharing
options. In most cases, you can simply set the permission parameter to
fsCurPerm. Some applications request fsRdWrPerm, to ensure that they
can both read and write to a file. The constants that can be passed in this
field are the following:
fsCurPerm exclusive read/write permission if it is available;
otherwise, exclusive read, if that is available
fsRdPerm exclusive read permission
fsWrPerm exclusive write permission
fsRdWrPerm exclusive read/write permission
fsRdWrShPerm shared read/write permission
In shared environments, permission requests are translated into the
"deny-mode" permissions defined by AppleShare.
Set ioMisc to 0 for normal I/O buffering (via the volume buffer). If you
wish to set up your own access buffer (possibly to speed up multiple-file
I/O), set ioMisc to point to a 522-byte area of memory.
The PBHOpen function works the same, with the addition that it allows
you to specify a "hard" directory ID in its parameter block. Use
PBOpenRF for direct access to the resource fork of a file.
The most common way to obtain ioNamePtr and ioVRefNum is by using the
Standard File Package, as illustrated in this example. See FSOpen for
related information and a similar example.
Example
#include <Files.h>
#include <StandardFile.h>
void MyReadFile (IOParam *pb);
SFReply tr;
short rc, fRefNum;
Point where;
IOParam pb; Î/* make a 50-byte param block */
where.h=100; where.v=50; [TOKEN:12074] where the dialog window goes */
SFGetFile( where, "\pSelect a file.", 0, -1, 0, 0, &tr );
if ( tr.good ) {
pb.ioNamePtr = tr.fName; [TOKEN:12074] values from SFGetFile */
pb.ioVRefNum = tr. vRefNum;
pb.ioVersNum = 0; [TOKEN:12074] always best to use this */
pb.ioMisc = 0; /* use volume buffer */
pb.ioPermssn = fsRdPerm; [TOKEN:12074] read-only permission */
rc=PBOpen( &pb, FALSE ); /* synchronous operation */
if ( rc ) { /* . . . handle the error . . . */ }
MyReadFile( &pb ); [TOKEN:12074] read the file */
PBClose( &pb, FALSE );
}
else { /* . . . the user clicked Cancel in SFGetFile . . . */ }
Device Manager Usage
PBOpen opens the device driver named in the ioNamePtr parameter,
enabling I/O operations. It is functionally equivalent to OpenDriver, except
that you can specify a read/write permission level, and the function can be
executed asynchronously.
pb is the address of a 50-byte IOParam structure. The following fields
are relevant for Device Manager usage:
Out-In Name Type Size Offset Description
-> ioCompletion ProcPtr 4 12 Completion routine address (if async =TRUE)
<- ioResult OSErr 2 16 Error Code (0=no error, 1=not done yet)
-> ioNamePtr StringPtr 4 18 Address of device driver name
<- ioRefNum short 2 24 Receives device driver reference number
-> ioPermssn SignedByte 1 27 Rd/Wrt permission (1=read, 2=write, et.al.)
async is a Boolean value. Use FALSE for normal (synchronous) operation
or TRUE to enqueue the request and resume control immediately. See
Async I/O.
Returns: an operating system Error Code. It will be one of:
noErr (0) No error
badUnitErr (-21) refNum doesn't match unit table
unitEmptyErr (-22) refNum specifies NIL handle in unit table
openErr (-23) Requested Read/Write permission and the driver's Open
permissions don't match
dInstErr (-26) Couldn't find driver in resource file
Device Mgr Notes:
PBOpen opens a device driver when used by the Device Manager. It is
the same call, with the same name, used by the File Manager to open files.
Additionally, the Device Manager and File Manager share the same
parameter block data structure, although file-specific aspects do not apply
to the Device Manager calls.
The ioPermssn field specifies read-only, read/write, and sharing options.
Referenced by (12):