ResKnife/External/MoreFiles/FullPath.h

/*
     File:       FullPath.h
 
     Contains:   Routines for dealing with full pathnames... if you really must.
 
     Version:    Technology: MoreFiles
                 Release:    1.5.2
 
     Copyright:  <20> 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:
    
    <20>   The user can change the name of any element in the path at
        virtually any time.
    <20>   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<6C>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<6C>s name, its parent directory ID, and the name of the
    volume on which it<69>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<6C>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<65>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);