src/mac/carbon/morefilex/MoreFilesXReadMe.txt

   1 MoreFilesX
   2
   3 Copyright (c) 1992-2002 Apple Computer, Inc.
   4 All rights reserved.
   5
   6 ________________________________________________________________________________
   7
   8 About MoreFilesX
   9
  10 MoreFilesX is a collection of useful high-level File Manager routines that use the HFS Plus APIs introduced in Mac OS 9.0 wherever possible.
  11
  12 While many of the routines in MoreFilesX are based on the older MoreFiles sample code (which used the older File Manager APIs), by using the HFS Plus APIs, the routines in MoreFilesX have several advantages over the older MoreFiles code:
  13
  14 ¥ The routines are simpler to understand because the high-level HFS Plus APIs are more powerful.
  15
  16 ¥ The routines support the features of the HFS Plus volume format such as long Unicode filenames and files larger than 2GB.
  17
  18 ¥ In many cases, the routines execute more efficiently than code that uses the older File Manager APIs -- especially on non-HFS volumes.
  19
  20 ¥ The routines use Apple's standard exception and assertion macros (the require, check, and verify macros) which improves readability and error handling, and which provides easy debug builds -- just add #define DEBUG 1 and every exception causes an assertion.
  21
  22 ¥ The routines are thread safe. There are no global or static variables so multiple program threads can use MoreFilesX routines safely.
  23
  24 If you are writing new Carbon applications for Mac OS X that call the File Manager, you should use MoreFilesX -- not MoreFiles. If you're porting existing applications to Mac OS X and those applications use routines from MoreFiles, you should consider switching to the routines in MoreFilesX.
  25
  26 The routines were designed for applications running in the Mac OS X Carbon environment. All of the routines will work under Mac OS 9 if you define BuildingMoreFilesXForMacOS9 to 1. Doing that removes code that calls Mac OS X only APIs. MoreFilesX cannot be used in pre-Mac OS 9 system releases.
  27
  28 The routines in MoreFilesX have been tested (but not stress-tested) and are fully documented.
  29
  30 ________________________________________________________________________________
  31
  32 Files in the MoreFilesX Package
  33
  34 MoreFilesX.c - the source code for MoreFilesX.
  35
  36 MoreFilesX.h - the header files and complete documentation for the routines included in MoreFilesX.
  37
  38 ________________________________________________________________________________
  39
  40 How to use MoreFilesX
  41
  42 You can compile the code and link it into your programs. You can cut and paste portions of it into your programs. You can use it as an example. Since MoreFilesX is sample code, many routines are there simply to show you how to use the File Manager APIs. If a routine does more or less than what you want, you can have the source so you can modify it to do exactly you want it to do. Feel free to rip MoreFilesX off and modify its code in whatever ways you find work best for you.
  43
  44 You'll also notice that all routines that make other File Manager calls return an OSErr or OSStatus result. I always check for error results and you should too.
  45
  46 ________________________________________________________________________________
  47
  48 Documentation
  49
  50 The documentation for the routines can be found in the header files. There, you'll find function prototypes, and a description of each call that includes a complete listing of all input and output parameters. For example, here's the function prototype and documentation for one of the routines, FSPathMakeFSSpec.
  51
  52 OSStatus
  53 FSPathMakeFSSpec(
  54         UInt8 *path,
  55         FSSpec *spec,
  56         Boolean *isDirectory);  /* can be NULL */
  57
  58 /*
  59         The FSPathMakeFSSpec function converts a pathname to an FSSpec.
  60
  61         path                            --> A pointer to a C String that is the pathname. The
  62                                                         format of the pathname you must supply can be
  63                                                         determined with the Gestalt selector gestaltFSAttr's
  64                                                         gestaltFSUsesPOSIXPathsForConversion bit.
  65                                                         If the gestaltFSUsesPOSIXPathsForConversion bit is
  66                                                         clear, the pathname must be a Mac OS File Manager
  67                                                         full pathname in a C string. If the
  68                                                         gestaltFSUsesPOSIXPathsForConversion bit is set,
  69                                                         the pathname must be a UTF8 encoded POSIX absolute
  70                                                         pathname in a C string. In either case, the pathname
  71                                                         returned by FSMakePath can be passed to
  72                                                         FSPathMakeFSSpec.
  73         spec                            <-- The FSSpec.
  74         isDirectory                     <** An optional pointer to a Boolean.
  75                                                         If not NULL, true will be returned in the Boolean
  76                                                         if the specified path is a directory or false will
  77                                                         be returned in the Boolean if the specified path is
  78                                                         a file.
  79 */
  80
  81 What do those arrows in the documentation for each routine mean?
  82
  83         --> The parameter is an input
  84
  85         <-- The parameter is an output. The pointer to the variable
  86                 where the output will be returned (must not be NULL).
  87
  88         <** The parameter is an optional output. If it is not a
  89                 NULL pointer, it points to the variable where the output
  90                 will be returned. If it is a NULL pointer, the output will
  91                 not be returned and will possibly let the routine and the
  92                 File Manager do less work. If you don't need an optional output,
  93                 don't ask for it.
  94         **> The parameter is an optional input. If it is not a
  95                 NULL pointer, it points to the variable containing the
  96                 input data. If it is a NULL pointer, the input is not used
  97                 and will possibly let the routine and the File Manager
  98                 do less work.
  99
 100 While most of the routines in MoreFilesX have plenty of comments to clarify what the code is doing, a few have very few comments in their code because they simply make a single File Manager call. For those routines, the routine description is the comment. If something isn't clear, take a look at File Manager documentation online at <http://developer.apple.com/techpubs/macosx/Carbon/Files/FileManager/File_Manager/index.html>.
 101
 102 The methodology behind Apple's standard exception and assertion macros is clearly explained in Sean Parent's article "Living in an Exceptional World" develop, The Apple Technical Journal, August 1992 <http://developer.apple.com/dev/techsupport/develop/issue11toc.shtml>. Don't let the fact that this article is 10 years old fool you -- this is highly recommended reading.
 103
 104 ________________________________________________________________________________
 105
 106 Release Notes
 107
 108 v1.0    Jan 25, 2002
 109 First Release.
 110
 111 v1.0.1  Aug 23, 2002
 112 [2850624]  Fixed C++ compile errors and Project Builder warnings.
 113 [2853901]  Updated standard disclaimer.
 114 [2853905]  Fixed #if test around header includes.
 115 [3016251]  Changed FSMoveRenameObjectUnicode to not use the Temporary folder because it isn't available on NFS volumes.
 116
 117 ________________________________________________________________________________
 118
 119 Bug Reports and Enhancement Requests
 120
 121 To file bug reports and enhancement requests, please go to <http://developer.apple.com/bugreporter/> and include "MoreFilesX Sample Code" in the title of your message.
 122
 123 Yes, we know that some of the routines available in MoreFiles still aren't in MoreFilesX. They were omitted due to time constraints.
 124
 125 ________________________________________________________________________________