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