/*
-** 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.
+ 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__
-#include <Types.h>
+#ifndef __MACTYPES__
+#include <MacTypes.h>
+#endif
+
+#ifndef __FILES__
#include <Files.h>
+#endif
-#include "Optim.h"
+#include "Optimization.h"
+
+
+#if PRAGMA_ONCE
+#pragma once
+#endif
#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.
-*/
+#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
/*****************************************************************************/
-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
+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
*/
/*****************************************************************************/
-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
+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
*/
/*****************************************************************************/
-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
+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
*/
/*****************************************************************************/
-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
+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
-#include "OptimEnd.h"
+#endif /* __FULLPATH__ */
projects / wxWidgets.git / blobdiff