--- /dev/null
+/*
+ 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__ */
+
projects / wxWidgets.git / blobdiff