X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/223d09f6b523aac674ef9b72a883dfa8d37c5d4e..d16477fd754fb9d6a80e2eccffa0c587a8077e85:/src/mac/morefile/FullPath.h diff --git a/src/mac/morefile/FullPath.h b/src/mac/morefile/FullPath.h index 3594a174eb..e1710c12bc 100644 --- a/src/mac/morefile/FullPath.h +++ b/src/mac/morefile/FullPath.h @@ -1,242 +1,311 @@ /* -** 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 +#ifndef __MACTYPES__ +#include +#endif + +#ifndef __FILES__ #include +#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__ */