]> git.saurik.com Git - wxWidgets.git/blob - src/mac/morefile/FullPath.h
added wx/defs.h include to correct compilation issues under Mac OS X
[wxWidgets.git] / 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__ */