src/mac/carbon/morefile/FullPath.h

   1 /*
   2      File:       FullPath.h
   3
   4      Contains:   Routines for dealing with full pathnames... if you really must.
   5
   6      Version:    Technology: MoreFiles
   7                  Release:    1.5.2
   8
   9      Copyright:  © 1995-2001 by Apple Computer, Inc., all rights reserved.
  10
  11      Bugs?:      For bug reports, consult the following page on
  12                  the World Wide Web:
  13
  14                      http://developer.apple.com/bugreporter/
  15
  16 */
  17
  18 /*
  19     You may incorporate this sample code into your applications without
  20     restriction, though the sample code has been provided "AS IS" and the
  21     responsibility for its operation is 100% yours.  However, what you are
  22     not permitted to do is to redistribute the source as "DSC Sample Code"
  23     after having made changes. If you're going to re-distribute the source,
  24     we require that you make it clear in the source that the code was
  25     descended from Apple Sample Code, but that you've made changes.
  26 */
  27
  28 /*
  29     IMPORTANT NOTE:
  30
  31     The use of full pathnames is strongly discouraged. Full pathnames are
  32     particularly unreliable as a means of identifying files, directories
  33     or volumes within your application, for two primary reasons:
  34
  35     ¥   The user can change the name of any element in the path at
  36         virtually any time.
  37     ¥   Volume names on the Macintosh are *not* unique. Multiple
  38         mounted volumes can have the same name. For this reason, the use of
  39         a full pathname to identify a specific volume may not produce the
  40         results you expect. If more than one volume has the same name and
  41         a full pathname is used, the File Manager currently uses the first
  42         mounted volume it finds with a matching name in the volume queue.
  43
  44     In general, you should use a fileÕs name, parent directory ID, and
  45     volume reference number to identify a file you want to open, delete,
  46     or otherwise manipulate.
  47
  48     If you need to remember the location of a particular file across
  49     subsequent system boots, use the Alias Manager to create an alias
  50     record describing the file. If the Alias Manager is not available, you
  51     can save the fileÕs name, its parent directory ID, and the name of the
  52     volume on which itÕs located. Although none of these methods is
  53     foolproof, they are much more reliable than using full pathnames to
  54     identify files.
  55
  56     Nonetheless, it is sometimes useful to display a fileÕs full pathname
  57     to the user. For example, a backup utility might display a list of full
  58     pathnames of files as it copies them onto the backup medium. Or, a
  59     utility might want to display a dialog box showing the full pathname of
  60     a file when it needs the userÕs confirmation to delete the file. No
  61     matter how unreliable full pathnames may be from a file-specification
  62     viewpoint, users understand them more readily than volume reference
  63     numbers or directory IDs. (Hint: Use the TruncString function from
  64     TextUtils.h with truncMiddle as the truncWhere argument to shorten
  65     full pathnames to a displayable length.)
  66
  67     The following technique for constructing the full pathname of a file is
  68     intended for display purposes only. Applications that depend on any
  69     particular structure of a full pathname are likely to fail on alternate
  70     foreign file systems or under future system software versions.
  71 */
  72
  73 #ifndef __FULLPATH__
  74 #define __FULLPATH__
  75
  76 #ifndef __MACTYPES__
  77 #include <MacTypes.h>
  78 #endif
  79
  80 #ifndef __FILES__
  81 #include <Files.h>
  82 #endif
  83
  84 #include "Optimization.h"
  85
  86
  87 #if PRAGMA_ONCE
  88 #pragma once
  89 #endif
  90
  91 #ifdef __cplusplus
  92 extern "C" {
  93 #endif
  94
  95 #if PRAGMA_IMPORT
  96 #pragma import on
  97 #endif
  98
  99 #if PRAGMA_STRUCT_ALIGN
 100     #pragma options align=mac68k
 101 #elif PRAGMA_STRUCT_PACKPUSH
 102     #pragma pack(push, 2)
 103 #elif PRAGMA_STRUCT_PACK
 104     #pragma pack(2)
 105 #endif
 106
 107 /*****************************************************************************/
 108
 109 EXTERN_API( OSErr )
 110 GetFullPath(
 111   short              vRefNum,
 112   long               dirID,
 113   ConstStr255Param   name,
 114   short *            fullPathLength,
 115   Handle *           fullPath);
 116
 117
 118 /*
 119     The GetFullPath function builds a full pathname to the specified
 120     object. The full pathname is returned in the newly created handle
 121     fullPath and the length of the full pathname is returned in
 122     fullPathLength. Your program is responsible for disposing of the
 123     fullPath handle.
 124
 125     Note that a full pathname can be made to a file/directory that does not
 126     yet exist if all directories up to that file/directory exist. In this case,
 127     GetFullPath will return a fnfErr.
 128
 129     vRefNum         input:  Volume specification.
 130     dirID           input:  Directory ID.
 131     name            input:  Pointer to object name, or nil when dirID
 132                             specifies a directory that's the object.
 133     fullPathLength  output: The number of characters in the full pathname.
 134                             If the function fails to create a full
 135                             pathname, it sets fullPathLength to 0.
 136     fullPath        output: A handle to the newly created full pathname
 137                             buffer. If the function fails to create a
 138                             full pathname, it sets fullPath to NULL.
 139
 140     Result Codes
 141         noErr               0       No error
 142         nsvErr              -35     No such volume
 143         ioErr               -36     I/O error
 144         bdNamErr            -37     Bad filename
 145         fnfErr              -43     File or directory does not exist (fullPath
 146                                     and fullPathLength are still valid)
 147         paramErr            -50     No default volume
 148         memFullErr          -108    Not enough memory
 149         dirNFErr            -120    Directory not found or incomplete pathname
 150         afpAccessDenied     -5000   User does not have the correct access
 151         afpObjectTypeErr    -5025   Directory not found or incomplete pathname
 152
 153     __________
 154
 155     See also:   FSpGetFullPath
 156 */
 157
 158 /*****************************************************************************/
 159
 160 EXTERN_API( OSErr )
 161 FSpGetFullPath(
 162   const FSSpec *  spec,
 163   short *         fullPathLength,
 164   Handle *        fullPath);
 165
 166
 167 /*
 168     The GetFullPath function builds a full pathname to the specified
 169     object. The full pathname is returned in the newly created handle
 170     fullPath and the length of the full pathname is returned in
 171     fullPathLength. Your program is responsible for disposing of the
 172     fullPath handle.
 173
 174     Note that a full pathname can be made to a file/directory that does not
 175     yet exist if all directories up to that file/directory exist. In this case,
 176     FSpGetFullPath will return a fnfErr.
 177
 178     IMPORTANT: The definition of a FSSpec is a volume reference number (not a
 179     drive number, working directory number, or 0), a parent directory ID (not 0),
 180     and the name of a file or folder (not an empty name, a full pathname, or
 181     a partial pathname containing one or more colon (:) characters).
 182     FSpGetFullPath assumes it is getting a FSSpec that matches the rules.
 183     If you have an FSSpec record that wasn't created by FSMakeFSSpec (or
 184     FSMakeFSSpecCompat from FSpCompat in MoreFiles which correctly builds
 185     FSSpecs), you should call GetFullPath instead of FSpGetFullPath.
 186
 187     spec            input:  An FSSpec record specifying the object.
 188     fullPathLength  output: The number of characters in the full pathname.
 189                             If the function fails to create a full pathname,
 190                             it sets fullPathLength to 0.
 191     fullPath        output: A handle to the newly created full pathname
 192                             buffer. If the function fails to create a
 193                             full pathname, it sets fullPath to NULL.
 194
 195     Result Codes
 196         noErr               0       No error
 197         nsvErr              -35     No such volume
 198         ioErr               -36     I/O error
 199         bdNamErr            -37     Bad filename
 200         fnfErr              -43     File or directory does not exist (fullPath
 201                                     and fullPathLength are still valid)
 202         paramErr            -50     No default volume
 203         memFullErr          -108    Not enough memory
 204         dirNFErr            -120    Directory not found or incomplete pathname
 205         afpAccessDenied     -5000   User does not have the correct access
 206         afpObjectTypeErr    -5025   Directory not found or incomplete pathname
 207
 208     __________
 209
 210     See also:   GetFullPath
 211 */
 212
 213 /*****************************************************************************/
 214
 215 EXTERN_API( OSErr )
 216 FSpLocationFromFullPath(
 217   short         fullPathLength,
 218   const void *  fullPath,
 219   FSSpec *      spec);
 220
 221
 222 /*
 223     The FSpLocationFromFullPath function returns a FSSpec to the object
 224     specified by full pathname. This function requires the Alias Manager.
 225
 226     fullPathLength  input:  The number of characters in the full pathname
 227                             of the target.
 228     fullPath        input:  A pointer to a buffer that contains the full
 229                             pathname of the target. The full pathname
 230                             starts with the name of the volume, includes
 231                             all of the directory names in the path to the
 232                             target, and ends with the target name.
 233     spec            output: An FSSpec record specifying the object.
 234
 235     Result Codes
 236         noErr               0       No error
 237         nsvErr              -35     The volume is not mounted
 238         fnfErr              -43     Target not found, but volume and parent
 239                                     directory found
 240         paramErr            -50     Parameter error
 241         usrCanceledErr      -128    The user canceled the operation
 242
 243     __________
 244
 245     See also:   LocationFromFullPath
 246 */
 247
 248 /*****************************************************************************/
 249
 250 EXTERN_API( OSErr )
 251 LocationFromFullPath(
 252   short         fullPathLength,
 253   const void *  fullPath,
 254   short *       vRefNum,
 255   long *        parID,
 256   Str31         name);
 257
 258
 259 /*
 260     The LocationFromFullPath function returns the volume reference number,
 261     parent directory ID and name of the object specified by full pathname.
 262     This function requires the Alias Manager.
 263
 264     fullPathLength  input:  The number of characters in the full pathname
 265                             of the target.
 266     fullPath        input:  A pointer to a buffer that contains the full
 267                             pathname of the target. The full pathname starts
 268                             with the name of the volume, includes all of
 269                             the directory names in the path to the target,
 270                             and ends with the target name.
 271     vRefNum         output: The volume reference number.
 272     parID           output: The parent directory ID of the specified object.
 273     name            output: The name of the specified object.
 274
 275     Result Codes
 276         noErr               0       No error
 277         nsvErr              -35     The volume is not mounted
 278         fnfErr              -43     Target not found, but volume and parent
 279                                     directory found
 280         paramErr            -50     Parameter error
 281         usrCanceledErr      -128    The user canceled the operation
 282
 283     __________
 284
 285     See also:   FSpLocationFromFullPath
 286 */
 287
 288 /*****************************************************************************/
 289
 290 #include "OptimizationEnd.h"
 291
 292 #if PRAGMA_STRUCT_ALIGN
 293     #pragma options align=reset
 294 #elif PRAGMA_STRUCT_PACKPUSH
 295     #pragma pack(pop)
 296 #elif PRAGMA_STRUCT_PACK
 297     #pragma pack()
 298 #endif
 299
 300 #ifdef PRAGMA_IMPORT_OFF
 301 #pragma import off
 302 #elif PRAGMA_IMPORT
 303 #pragma import reset
 304 #endif
 305
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310 #endif /* __FULLPATH__ */
 311