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 92extern "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 109EXTERN_API( OSErr ) 110GetFullPath( 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 160EXTERN_API( OSErr ) 161FSpGetFullPath( 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 215EXTERN_API( OSErr ) 216FSpLocationFromFullPath( 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 250EXTERN_API( OSErr ) 251LocationFromFullPath( 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 312