From: peter@cujo.curtin.edu.au (Peter N Lewis)
Subject: Summary: High Level File Manager routines (H-routines)
Followup-To: comp.sys.mac.programmer
Organization: NCRPDA, Curtin University
Date: Tue, 12 Jan 1993 04:17:45 GMT

Hi All,

Just thought I'd post a list of all the high level routines, maybe it'll
save Jon some answering time! :-)

All of these are available in System 6 & 7, and are pasted straight in with
ObiWan - if you don't remember them all, then get ObiWan and look them up
yourself!

OSErr:=HCreate(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,creator_OSType,fileType_OSType);
HCreateResFile(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255);
OSErr:=HDelete(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255);
OSErr:=HGetFInfo(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,
VARfndrInfo_FInfo);
OSErr:=HGetVol(volName_StringPtr,VAR_vRefNum_INTEGER,VAR_dirID_LONGINT);
OSErr:=HOpen(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255
,permission_SignedByte,VAR_refNum_INTEGER);
OSErr:=HOpenDF(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,
permission_SignedByte,VAR_refNum_INTEGER);
INTEGER:=HOpenResFile(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,
permission_SignedByte);
OSErr:=HOpenRF(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,
permission_SignedByte,VAR_refNum_INTEGER);
OSErr:=HRename(vRefNum_INTEGER,dirID_LONGINT,oldName_Str255,newName_Str255);
OSErr:=HSetFInfo(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,fndrInfo_FInfo);
OSErr:=HSetVol(volName_StringPtr,vRefNum_INTEGER,dirID_LONGINT);

Under System 7 there are FSp routines as well.  A good way of working under
System 6 & 7 is to use the FSSpec record, and call the routines using those
fields, eg:

oe:=HOpen(fs.vRefNum,fs.parID,fs.name,fsRdPerm,refNum);

Under System 7 you should use FSMakeFSSpec to create the FSSpec, under
System 6 you need to just fill it out yourself.

OSErr:=FSMakeFSSpec(vRefNum_INTEGER,dirID_LONGINT,fileName_Str255,
VAR_spec_FSSpec);

If you don't know why you should always be using dirID's, then read on,
especially read FAQ3:

Peter's FAQ1 - How do you tell if <modifier>-key is down.
Peter's FAQ2 - How do you get a full pathname.
Peter's FAQ3 - How to learn to love the File Manager.
Peter's NFAQ4 - When do you put ... on the end of a menu item
Peter's FAQ5 - How to set the SFGet/PutFile directory.

Peter's FAQ1 - How do you tell if <modifier>-key is down.
   Just call GetNextEvent(noEvent,er), and test the modifiers field 
of the event record.

Peter's FAQ2 - How do you get a full pathname.
   Take a look at Tech Note 238, available from ftp.apple.com (and
other places).  It tells you everything you need to know to get a
full pathname, and why you should, in general, use a volume name, 
dirID, filename (and perhaps volume creation date) triple instead.

Peter's FAQ3 - How to learn to love the File Manager.
   Its always those pesky wdrn's that are the problem.  Here is a
summary of some of the things to know:

vrn=volume reference number (small negative number eg -2)
wdrn=working directory reference number (large negative number eg -32123)
dirID=directory ID (small (but longInt!) positive number eg 4123)

vrn's and wdrn's can be used interchangably for the most part.
A vrn represents either a volume, or the root directory of a volume.
A vrn of -1 represents the startup (system) volume.
A wdrn represents a directory on a volume.
Neither a vrn nor a wdrn can be -32768 (TN 77), so use this as your nil
value
A dirID represents nothing without a vrn or a wdrn.
A dirID overrides the directory otherwise specified by the vrn or wdrn 
unless its 0, in which case its ignored.  If it is 2 it specifies the
root directory of the volume. If its 1 it specifies the Desktop directory

You should always use vrn,dirID pairs. To convert a wdrn into a vrn,dirID 
pair use this function GetWDInfo, which also returns the volume name.
You can also use GetVol/SetVol to conver volumenames to/from vrns.

To store (between invokations of a program) a vrn,dirID pair convert the
vrn to a volume name&creation date (for verification) and store them and
the dirID (and a filename perhaps).

Peter's NFAQ4 - When do you put ... on the end of a menu item
   Put an ellipsis (...) at the end of any menu item which requires more 
information in order to complete or simply displays information.  Usually 
this involves a dialog of some kind, be it modal or non modal.
   Leonard Rosenthol <leonardr@svctech.svcdudes.com>, Software Ventures

Peter's FAQ5 - How to set the SFGet/PutFile directory.
   To set the directory thats displayed by SFGet/PutFile, stuff the
volume reference number into SFSaveDisk, and the dirID into CurDirStore.
   CurDirStore=$398; Current dirID from Standard File [long] IV-72
   SFSaveDisk=$214; Negative of current vRefNum

Have fun all,
   Peter.

_______________________________________________________________________
Peter N Lewis <peter@cujo.curtin.edu.au>             Ph: +61 9 368 2055
Xref: sparky comp.sys.mac.programmer:20936 comp.os.ms-windows.programmer.tools:1928 comp.os.ms-windows.programmer.misc:4717