mirror of
https://github.com/nickshanks/ResKnife.git
synced 2024-06-03 01:29:40 +00:00
1 line
12 KiB
C
Executable File
1 line
12 KiB
C
Executable File
/*
|
|
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 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.
|
|
*/
|
|
|
|
#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__ */
|
|
|