src/mac/morefile/FullPath.cpp

   1 /*
   2 **      Apple Macintosh Developer Technical Support
   3 **
   4 **      Routines for dealing with full pathnames... if you really must.
   5 **
   6 **      by Jim Luther, Apple Developer Technical Support Emeritus
   7 **
   8 **      File:           FullPath.c
   9 **
  10 **      Copyright © 1995-1998 Apple Computer, Inc.
  11 **      All rights reserved.
  12 **
  13 **      You may incorporate this sample code into your applications without
  14 **      restriction, though the sample code has been provided "AS IS" and the
  15 **      responsibility for its operation is 100% yours.  However, what you are
  16 **      not permitted to do is to redistribute the source as "DSC Sample Code"
  17 **      after having made changes. If you're going to re-distribute the source,
  18 **      we require that you make it clear in the source that the code was
  19 **      descended from Apple Sample Code, but that you've made changes.
  20 */
  21
  22 #include <Types.h>
  23 #include <Errors.h>
  24 #include <Memory.h>
  25 #include <Files.h>
  26 #include <TextUtils.h>
  27 #include <Aliases.h>
  28
  29 #define __COMPILINGMOREFILES
  30
  31 #include "fspcompa.h"
  32 #include "fullpath.h"
  33
  34 /*
  35         IMPORTANT NOTE:
  36
  37         The use of full pathnames is strongly discouraged. Full pathnames are
  38         particularly unreliable as a means of identifying files, directories
  39         or volumes within your application, for two primary reasons:
  40
  41         ¥      The user can change the name of any element in the path at virtually
  42                 any time.
  43         ¥      Volume names on the Macintosh are *not* unique. Multiple
  44                 mounted volumes can have the same name. For this reason, the use of
  45                 a full pathname to identify a specific volume may not produce the
  46                 results you expect. If more than one volume has the same name and
  47                 a full pathname is used, the File Manager currently uses the first
  48                 mounted volume it finds with a matching name in the volume queue.
  49
  50         In general, you should use a fileÕs name, parent directory ID, and
  51         volume reference number to identify a file you want to open, delete,
  52         or otherwise manipulate.
  53
  54         If you need to remember the location of a particular file across
  55         subsequent system boots, use the Alias Manager to create an alias record
  56         describing the file. If the Alias Manager is not available, you can save
  57         the fileÕs name, its parent directory ID, and the name of the volume on
  58         which itÕs located. Although none of these methods is foolproof, they are
  59         much more reliable than using full pathnames to identify files.
  60
  61         Nonetheless, it is sometimes useful to display a fileÕs full pathname to
  62         the user. For example, a backup utility might display a list of full
  63         pathnames of files as it copies them onto the backup medium. Or, a
  64         utility might want to display a dialog box showing the full pathname of
  65         a file when it needs the userÕs confirmation to delete the file. No
  66         matter how unreliable full pathnames may be from a file-specification
  67         viewpoint, users understand them more readily than volume reference
  68         numbers or directory IDs. (Hint: Use the TruncString function from
  69         TextUtils.h with truncMiddle as the truncWhere argument to shorten
  70         full pathnames to a displayable length.)
  71
  72         The following technique for constructing the full pathname of a file is
  73         intended for display purposes only. Applications that depend on any
  74         particular structure of a full pathname are likely to fail on alternate
  75         foreign file systems or under future system software versions.
  76 */
  77
  78 /*****************************************************************************/
  79
  80 pascal  OSErr   GetFullPath(short vRefNum,
  81                                                         long dirID,
  82                                                         ConstStr255Param name,
  83                                                         short *fullPathLength,
  84                                                         Handle *fullPath)
  85 {
  86         OSErr           result;
  87         FSSpec          spec;
  88
  89         *fullPathLength = 0;
  90         *fullPath = NULL;
  91
  92         result = FSMakeFSSpecCompat(vRefNum, dirID, name, &spec);
  93         if ( (result == noErr) || (result == fnfErr) )
  94         {
  95                 result = FSpGetFullPath(&spec, fullPathLength, fullPath);
  96         }
  97
  98         return ( result );
  99 }
 100
 101 /*****************************************************************************/
 102
 103 pascal  OSErr   FSpGetFullPath(const FSSpec *spec,
 104                                                            short *fullPathLength,
 105                                                            Handle *fullPath)
 106 {
 107         OSErr           result;
 108         OSErr           realResult;
 109         FSSpec          tempSpec;
 110         CInfoPBRec      pb;
 111
 112         *fullPathLength = 0;
 113         *fullPath = NULL;
 114
 115         // Default to noErr
 116         realResult = noErr;
 117
 118         /* Make a copy of the input FSSpec that can be modified */
 119         BlockMoveData(spec, &tempSpec, sizeof(FSSpec));
 120
 121         if ( tempSpec.parID == fsRtParID )
 122         {
 123                 /* The object is a volume */
 124
 125                 /* Add a colon to make it a full pathname */
 126                 ++tempSpec.name[0];
 127                 tempSpec.name[tempSpec.name[0]] = ':';
 128
 129                 /* We're done */
 130                 result = PtrToHand(&tempSpec.name[1], fullPath, tempSpec.name[0]);
 131         }
 132         else
 133         {
 134                 /* The object isn't a volume */
 135
 136                 /* Is the object a file or a directory? */
 137                 pb.dirInfo.ioNamePtr = tempSpec.name;
 138                 pb.dirInfo.ioVRefNum = tempSpec.vRefNum;
 139                 pb.dirInfo.ioDrDirID = tempSpec.parID;
 140                 pb.dirInfo.ioFDirIndex = 0;
 141                 result = PBGetCatInfoSync(&pb);
 142                 // Allow file/directory name at end of path to not exist.
 143                 realResult = result;
 144                 if ( (result == noErr) || (result == fnfErr) )
 145                 {
 146                         /* if the object is a directory, append a colon so full pathname ends with colon */
 147                         if ( (result == noErr) && (pb.hFileInfo.ioFlAttrib & ioDirMask) != 0 )
 148                         {
 149                                 ++tempSpec.name[0];
 150                                 tempSpec.name[tempSpec.name[0]] = ':';
 151                         }
 152
 153                         /* Put the object name in first */
 154                         result = PtrToHand(&tempSpec.name[1], fullPath, tempSpec.name[0]);
 155                         if ( result == noErr )
 156                         {
 157                                 /* Get the ancestor directory names */
 158                                 pb.dirInfo.ioNamePtr = tempSpec.name;
 159                                 pb.dirInfo.ioVRefNum = tempSpec.vRefNum;
 160                                 pb.dirInfo.ioDrParID = tempSpec.parID;
 161                                 do      /* loop until we have an error or find the root directory */
 162                                 {
 163                                         pb.dirInfo.ioFDirIndex = -1;
 164                                         pb.dirInfo.ioDrDirID = pb.dirInfo.ioDrParID;
 165                                         result = PBGetCatInfoSync(&pb);
 166                                         if ( result == noErr )
 167                                         {
 168                                                 /* Append colon to directory name */
 169                                                 ++tempSpec.name[0];
 170                                                 tempSpec.name[tempSpec.name[0]] = ':';
 171
 172                                                 /* Add directory name to beginning of fullPath */
 173                                                 (void) Munger(*fullPath, 0, NULL, 0, &tempSpec.name[1], tempSpec.name[0]);
 174                                                 result = MemError();
 175                                         }
 176                                 } while ( (result == noErr) && (pb.dirInfo.ioDrDirID != fsRtDirID) );
 177                         }
 178                 }
 179         }
 180         if ( result == noErr )
 181         {
 182                 /* Return the length */
 183 #if TARGET_CARBON
 184                 *fullPathLength = GetHandleSize(*fullPath);
 185 #else
 186                 *fullPathLength = InlineGetHandleSize(*fullPath);
 187 #endif
 188                 result = realResult;    // return realResult in case it was fnfErr
 189         }
 190         else
 191         {
 192                 /* Dispose of the handle and return NULL and zero length */
 193                 if ( *fullPath != NULL )
 194                 {
 195                         DisposeHandle(*fullPath);
 196                 }
 197                 *fullPath = NULL;
 198                 *fullPathLength = 0;
 199         }
 200
 201         return ( result );
 202 }
 203
 204 /*****************************************************************************/
 205
 206 pascal OSErr FSpLocationFromFullPath(short fullPathLength,
 207                                                                          const void *fullPath,
 208                                                                          FSSpec *spec)
 209 {
 210         AliasHandle     alias;
 211         OSErr           result;
 212         Boolean         wasChanged;
 213         Str32           nullString;
 214
 215         /* Create a minimal alias from the full pathname */
 216         nullString[0] = 0;      /* null string to indicate no zone or server name */
 217         result = NewAliasMinimalFromFullPath(fullPathLength, fullPath, nullString, nullString, &alias);
 218         if ( result == noErr )
 219         {
 220                 /* Let the Alias Manager resolve the alias. */
 221                 result = ResolveAlias(NULL, alias, spec, &wasChanged);
 222
 223                 DisposeHandle((Handle)alias);   /* Free up memory used */
 224         }
 225         return ( result );
 226 }
 227
 228 /*****************************************************************************/
 229
 230 pascal OSErr LocationFromFullPath(short fullPathLength,
 231                                                                   const void *fullPath,
 232                                                                   short *vRefNum,
 233                                                                   long *parID,
 234                                                                   Str31 name)
 235 {
 236         OSErr   result;
 237         FSSpec  spec;
 238
 239         result = FSpLocationFromFullPath(fullPathLength, fullPath, &spec);
 240         if ( result == noErr )
 241         {
 242                 *vRefNum = spec.vRefNum;
 243                 *parID = spec.parID;
 244                 BlockMoveData(&spec.name[0], &name[0], spec.name[0] + 1);
 245         }
 246         return ( result );
 247 }
 248
 249 /*****************************************************************************/
 250