src/mac/morefile/FullPath.h

   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.h
   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 #ifndef __FULLPATH__
  23 #define __FULLPATH__
  24
  25 #include <Types.h>
  26 #include <Files.h>
  27
  28 #include "optim.h"
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  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
  42                 virtually 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
  56         record describing the file. If the Alias Manager is not available, you
  57         can save the fileÕs name, its parent directory ID, and the name of the
  58         volume on which itÕs located. Although none of these methods is
  59         foolproof, they are much more reliable than using full pathnames to
  60         identify files.
  61
  62         Nonetheless, it is sometimes useful to display a fileÕs full pathname
  63         to the user. For example, a backup utility might display a list of full
  64         pathnames of files as it copies them onto the backup medium. Or, a
  65         utility might want to display a dialog box showing the full pathname of
  66         a file when it needs the userÕs confirmation to delete the file. No
  67         matter how unreliable full pathnames may be from a file-specification
  68         viewpoint, users understand them more readily than volume reference
  69         numbers or directory IDs. (Hint: Use the TruncString function from
  70         TextUtils.h with truncMiddle as the truncWhere argument to shorten
  71         full pathnames to a displayable length.)
  72
  73         The following technique for constructing the full pathname of a file is
  74         intended for display purposes only. Applications that depend on any
  75         particular structure of a full pathname are likely to fail on alternate
  76         foreign file systems or under future system software versions.
  77 */
  78
  79 /*****************************************************************************/
  80
  81 pascal  OSErr   GetFullPath(short vRefNum,
  82                                                         long dirID,
  83                                                         ConstStr255Param name,
  84                                                         short *fullPathLength,
  85                                                         Handle *fullPath);
  86 /*      ¦ Get a full pathname to a volume, directory or file.
  87         The GetFullPath function builds a full pathname to the specified
  88         object. The full pathname is returned in the newly created handle
  89         fullPath and the length of the full pathname is returned in
  90         fullPathLength. Your program is responsible for disposing of the
  91         fullPath handle.
  92
  93         Note that a full pathname can be made to a file/directory that does not
  94         yet exist if all directories up to that file/directory exist. In this case,
  95         GetFullPath will return a fnfErr.
  96
  97         vRefNum                 input:  Volume specification.
  98         dirID                   input:  Directory ID.
  99         name                    input:  Pointer to object name, or nil when dirID
 100                                                         specifies a directory that's the object.
 101         fullPathLength  output: The number of characters in the full pathname.
 102                                                         If the function fails to create a full
 103                                                         pathname, it sets fullPathLength to 0.
 104         fullPath                output: A handle to the newly created full pathname
 105                                                         buffer. If the function fails to create a
 106                                                         full pathname, it sets fullPath to NULL.
 107
 108         Result Codes
 109                 noErr                           0               No error
 110                 nsvErr                          -35             No such volume
 111                 ioErr                           -36             I/O error
 112                 bdNamErr                        -37             Bad filename
 113                 fnfErr                          -43             File or directory does not exist (fullPath
 114                                                                         and fullPathLength are still valid)
 115                 paramErr                        -50             No default volume
 116                 memFullErr                      -108    Not enough memory
 117                 dirNFErr                        -120    Directory not found or incomplete pathname
 118                 afpAccessDenied         -5000   User does not have the correct access
 119                 afpObjectTypeErr        -5025   Directory not found or incomplete pathname
 120
 121         __________
 122
 123         See also:       FSpGetFullPath
 124 */
 125
 126 /*****************************************************************************/
 127
 128 pascal  OSErr   FSpGetFullPath(const FSSpec *spec,
 129                                                            short *fullPathLength,
 130                                                            Handle *fullPath);
 131 /*      ¦ Get a full pathname to a volume, directory or file.
 132         The GetFullPath function builds a full pathname to the specified
 133         object. The full pathname is returned in the newly created handle
 134         fullPath and the length of the full pathname is returned in
 135         fullPathLength. Your program is responsible for disposing of the
 136         fullPath handle.
 137
 138         Note that a full pathname can be made to a file/directory that does not
 139         yet exist if all directories up to that file/directory exist. In this case,
 140         FSpGetFullPath will return a fnfErr.
 141
 142         spec                    input:  An FSSpec record specifying the object.
 143         fullPathLength  output: The number of characters in the full pathname.
 144                                                         If the function fails to create a full pathname,
 145                                                         it sets fullPathLength to 0.
 146         fullPath                output: A handle to the newly created full pathname
 147                                                         buffer. If the function fails to create a
 148                                                         full pathname, it sets fullPath to NULL.
 149
 150         Result Codes
 151                 noErr                           0               No error
 152                 nsvErr                          -35             No such volume
 153                 ioErr                           -36             I/O error
 154                 bdNamErr                        -37             Bad filename
 155                 fnfErr                          -43             File or directory does not exist (fullPath
 156                                                                         and fullPathLength are still valid)
 157                 paramErr                        -50             No default volume
 158                 memFullErr                      -108    Not enough memory
 159                 dirNFErr                        -120    Directory not found or incomplete pathname
 160                 afpAccessDenied         -5000   User does not have the correct access
 161                 afpObjectTypeErr        -5025   Directory not found or incomplete pathname
 162
 163         __________
 164
 165         See also:       GetFullPath
 166 */
 167
 168 /*****************************************************************************/
 169
 170 pascal OSErr FSpLocationFromFullPath(short fullPathLength,
 171                                                                          const void *fullPath,
 172                                                                          FSSpec *spec);
 173 /*      ¦ Get a FSSpec from a full pathname.
 174         The FSpLocationFromFullPath function returns a FSSpec to the object
 175         specified by full pathname. This function requires the Alias Manager.
 176
 177         fullPathLength  input:  The number of characters in the full pathname
 178                                                         of the target.
 179         fullPath                input:  A pointer to a buffer that contains the full
 180                                                         pathname of the target. The full pathname
 181                                                         starts with the name of the volume, includes
 182                                                         all of the directory names in the path to the
 183                                                         target, and ends with the target name.
 184         spec                    output: An FSSpec record specifying the object.
 185
 186         Result Codes
 187                 noErr                           0               No error
 188                 nsvErr                          -35             The volume is not mounted
 189                 fnfErr                          -43             Target not found, but volume and parent
 190                                                                         directory found
 191                 paramErr                        -50             Parameter error
 192                 usrCanceledErr          -128    The user canceled the operation
 193
 194         __________
 195
 196         See also:       LocationFromFullPath
 197 */
 198
 199 /*****************************************************************************/
 200
 201 pascal OSErr LocationFromFullPath(short fullPathLength,
 202                                                                   const void *fullPath,
 203                                                                   short *vRefNum,
 204                                                                   long *parID,
 205                                                                   Str31 name);
 206 /*      ¦ Get an object's location from a full pathname.
 207         The LocationFromFullPath function returns the volume reference number,
 208         parent directory ID and name of the object specified by full pathname.
 209         This function requires the Alias Manager.
 210
 211         fullPathLength  input:  The number of characters in the full pathname
 212                                                         of the target.
 213         fullPath                input:  A pointer to a buffer that contains the full
 214                                                         pathname of the target. The full pathname starts
 215                                                         with the name of the volume, includes all of
 216                                                         the directory names in the path to the target,
 217                                                         and ends with the target name.
 218         vRefNum                 output: The volume reference number.
 219         parID                   output: The parent directory ID of the specified object.
 220         name                    output: The name of the specified object.
 221
 222         Result Codes
 223                 noErr                           0               No error
 224                 nsvErr                          -35             The volume is not mounted
 225                 fnfErr                          -43             Target not found, but volume and parent
 226                                                                         directory found
 227                 paramErr                        -50             Parameter error
 228                 usrCanceledErr          -128    The user canceled the operation
 229
 230         __________
 231
 232         See also:       FSpLocationFromFullPath
 233 */
 234
 235 /*****************************************************************************/
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #include "optimend.h"
 242
 243 #endif  /* __FULLPATH__ */