mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-05 00:25:27 +00:00
244 lines
9.0 KiB
C
244 lines
9.0 KiB
C
/*
|
|
** Apple Macintosh Developer Technical Support
|
|
**
|
|
** Routines for dealing with full pathnames... if you really must.
|
|
**
|
|
** by Jim Luther, Apple Developer Technical Support Emeritus
|
|
**
|
|
** File: FullPath.h
|
|
**
|
|
** Copyright © 1995-1998 Apple Computer, Inc.
|
|
** All rights reserved.
|
|
**
|
|
** 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.
|
|
*/
|
|
|
|
#ifndef __FULLPATH__
|
|
#define __FULLPATH__
|
|
|
|
#include <MacTypes.h>
|
|
#include <Files.h>
|
|
|
|
#include "Optimization.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*
|
|
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 fileÕs 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 fileÕs name, its parent directory ID, and the name of the
|
|
volume on which itÕs 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 fileÕs 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 userÕs 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.
|
|
*/
|
|
|
|
/*****************************************************************************/
|
|
|
|
pascal OSErr GetFullPath(short vRefNum,
|
|
long dirID,
|
|
ConstStr255Param name,
|
|
short *fullPathLength,
|
|
Handle *fullPath);
|
|
/* ¦ Get a full pathname to a volume, directory or file.
|
|
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
|
|
*/
|
|
|
|
/*****************************************************************************/
|
|
|
|
pascal OSErr FSpGetFullPath(const FSSpec *spec,
|
|
short *fullPathLength,
|
|
Handle *fullPath);
|
|
/* ¦ Get a full pathname to a volume, directory or file.
|
|
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.
|
|
|
|
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
|
|
*/
|
|
|
|
/*****************************************************************************/
|
|
|
|
pascal OSErr FSpLocationFromFullPath(short fullPathLength,
|
|
const void *fullPath,
|
|
FSSpec *spec);
|
|
/* ¦ Get a FSSpec from a full pathname.
|
|
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
|
|
*/
|
|
|
|
/*****************************************************************************/
|
|
|
|
pascal OSErr LocationFromFullPath(short fullPathLength,
|
|
const void *fullPath,
|
|
short *vRefNum,
|
|
long *parID,
|
|
Str31 name);
|
|
/* ¦ Get an object's location from a full pathname.
|
|
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
|
|
*/
|
|
|
|
/*****************************************************************************/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#include "OptimizationEnd.h"
|
|
|
|
#endif /* __FULLPATH__ */
|