home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / Libraries / StdPrefs 1.0 / ReadMe next >
Encoding:
Text File  |  1997-07-24  |  6.8 KB  |  195 lines  |  [ttro/ttxt]
  1. StdPrefs 1.0
  2. Preference file routines, ReadMe.
  3. Copyright (c) 1996, 1997 by John Montbriand.  All Rights Reserved.
  4. Permission hereby granted for public use.
  5. Distribute freely in areas where the laws of copyright apply.
  6. USE AT YOUR OWN RISK.
  7. DO NOT DISTRIBUTE MODIFIED COPIES.
  8. Comments/questions/postcards* to the author at the address:
  9.   John Montbriand
  10.   P.O. Box. 1133
  11.   Saskatoon Saskatchewan Canada
  12.   S7K 3N2
  13. or by email at:
  14.    tinyjohn@sk.sympatico.ca
  15. *if you mail a postcard, then I will provide you with technical support
  16. regarding questions you may have about this file.
  17.    see also: <http://www3.sk.sympatico.ca/tinyjohn>
  18.  
  19.  
  20. Contents
  21. About StdPrefs...
  22. Implementation Notes
  23. Materials
  24. Finding the Preferences Folder
  25. Finding Your Preferences File
  26. Creating Preferences Files
  27. Files in this package
  28. Copies for sale!
  29. NO WARRANTY
  30. Bug reports make this a better product!
  31. Further Reference
  32. Other
  33.  
  34. About StdPrefs...
  35.     
  36. Preferences files are commonly used by applications and other utilities to store various configuration parameters for their operation.  This library provides a convenient set of routines you can use in any application for conveniently creating and accessing preferences files.  In system 6, these files are located in the System Folder, and in system seven or later, these files are located in the Preferences folder (which is located in the System Folder).
  37.     
  38. Implementation Notes
  39.  
  40. In this implementation, preferences files are searched for by file type and creator, not by name.  This is so your preferences files do not become lost if the user decides to change the name, or if your program and it's file names are translated into another language.
  41.  
  42. The routines are safe to use with any version of Mac OS that includes the hierarchical file system, which first appeared in the MacPlus era.  Odds are, this isn't something you have to worry too much about, but these routines have been implemented for use with both System 6 and system 7.x.
  43.  
  44. Materials
  45.  
  46. The routines documented herein are the copyright property of John Montbriand.  They're handy, easy to use, and practical.  I hope all who find them will use them well.
  47.  
  48. Copyright (c) 1996, 1997 by John Montbriand.  All Rights Reserved.
  49. Permission hereby granted for public use.
  50. Distribute freely in areas where the laws of copyright apply.
  51. USE AT YOUR OWN RISK.
  52. DO NOT DISTRIBUTE MODIFIED COPIES.
  53.  
  54.  
  55. Finding the Preferences Folder
  56.  
  57. FindPreferencesFolder
  58.  
  59. OSErr FindPreferencesFolder(short *pvol, long *pdir);
  60.  
  61. FindPreferencesFolder finds the preferences folder returning its volume reference number and directory id.  Under system 6, this will be the System Folder.  Under System 7, this will be the Preferences folder inside of the System Folder.
  62.  
  63. EXAMPLE:  
  64.  
  65. short vRefNum;
  66. long parID;
  67. OSErr err;
  68.  
  69. err = FindPreferencesFolder(&vRefNum, &parID);
  70. if (err != noErr)  goto bail;
  71. ....
  72.  
  73.  
  74. Finding Your Preferences File
  75.  
  76. PrefsDirSearch
  77.  
  78. OSErr PrefsDirSearch(OSType creator, OSType type,
  79.         short *fvol, long *fdir, StringPtr fname);
  80. PrefsDirSearch searches the preferences folder for a file with the given creator and type.  If such a file exists, then fvol, fdir, and fname are set to refer to the file.  Under system 6, the System Folder is searched, and, under System 7, the Preferences folder inside of the System Folder is searched.  If a file with the given type and creator cannot be found, the routine returns fnfErr.
  81.  
  82.  
  83. EXAMPLE:  
  84.  
  85. OSErr err;
  86. short vRefNum;
  87. long parID;
  88. Str255 name;
  89.  
  90. err = PrefsDirSearch('????', 'PREF', &vRefNum, &parID, name);
  91. if (err != noErr) goto bail;
  92. ....
  93.  
  94.  
  95. FSpPrefsDirSearch
  96.  
  97. OSErr FSpPrefsDirSearch(OSType creator, OSType type, FSSpec *spec);
  98.  
  99. FSpPrefsDirSearch is identical to PrefsDirSearch except it returns information about the file's location in a file specification record.  If a file with the given type and creator cannot be found, the routine returns fnfErr.
  100.  
  101. EXAMPLE:  
  102.  
  103. OSErr err;
  104. FSSpec spec;
  105.  
  106. err = FSpPrefsDirSearch('????', 'PREF', &spec);
  107. if (err != noErr) goto bail;
  108. ....
  109.  
  110.  
  111. Creating Preferences Files
  112.  
  113. PrefsCreate
  114.  
  115. OSErr PrefsCreate(OSType creator, OSType type, StringPtr defaultname,
  116.     short *fvol, long *fdir, StringPtr fname);
  117.  
  118. PrefsCreate creates a file in the prefs folder with the given creator type and defaultname.  If a file already exists with the name defaultname, then a digit (1 2 3...) is appended to defaultname until a unique name is found.  This routine creates a resource fork for the file too.  Once the file has been successfully created,  fvol, fdir, and fname are set to refer to the file.
  119.  
  120. EXAMPLE:  
  121.  
  122. OSErr err;
  123. short vRefNum;
  124. long parID;
  125. Str255 name;
  126.  
  127. err = PrefsDirSearch('????', 'PREF', &vRefNum, &parID, name);
  128. if (err == fnfErr)
  129.     err = PrefsCreate('????', 'PREF', "\pMyPrefs", &vRefNum, &parID, name);
  130. if (err != noErr) goto bail;
  131. ....
  132.  
  133.  
  134. FSpPrefsCreate
  135.  
  136. OSErr FSpPrefsCreate(OSType creator, OSType type, StringPtr defaultname,
  137.     FSSpec *spec);
  138.  
  139. FSpPrefsCreate is identical to PrefsCreate except it returns information about the created file's location in a file specification record.
  140.  
  141. EXAMPLE:  
  142.  
  143. OSErr err;
  144. FSSpec spec;
  145.  
  146. err = FSpPrefsDirSearch('????', 'PREF', &spec);
  147. if (err == fnfErr)
  148.     err = FSpPrefsCreate('????', 'PREF', "\pMyPrefs", &spec);
  149. if (err != noErr) goto bail;
  150. ....
  151.  
  152.  
  153. Files in this package
  154.  
  155. StdPrefs.c -- source code for the StdPrefs routines' implementation
  156. StdPrefs.h -- header file providing interfaces to the StdPrefs routines
  157. ReadMe  -- this file
  158.  
  159. :Libraries: -- precompiled libraries, ready to link.  
  160. StdPrefs.o -- 68K version of the StdPrefs library
  161. StdPrefs.xcoff -- PowerPC version of the StdPrefs library
  162.  
  163.  
  164. Copies for sale!
  165.  
  166. These libraries are provided for free and you may use them in any program you make;  however, if you would like to purchase a copy of these libraries and have a legal paper trail establishing your right to use them, then send along a cheque or a money order in the amount of $10.00 for the purchase of one copy.  I'll send you a receipt.
  167.  
  168.  
  169. NO WARRANTY
  170.  
  171. No warranties are made regarding these files.  John Montbriand disclaims all warranties regarding these files, either express or implied, including but not limited to implied warranties of merchantability and fitness for any particular purpose.  These files are provided "AS IS" without any warranty of any kind.  Use them at your own risk.  Copies of these files are not for sale in areas where the law does not allow exclusion of implied warranties.
  172.  
  173.  
  174. Bug reports make this a better product!
  175.  
  176. As in all of my products, I advertise a $10.00 finder's fee for bug reports that lead to corrections.  If you find a problem here, report it!  it could be worth your while....
  177.  
  178.  
  179. Further Reference
  180.  
  181. Inside Macintosh: Files by Apple Computer, Inc.  Addison-Wesley.
  182. A discussion of files, file handling routines, and  how to use them.
  183.     
  184. The C Programming Language 2nd edition by Brian W. Kernighan and Dennis M. Ritchie.  Prentice Hall.
  185.  
  186.  
  187. Other
  188.  
  189. Have a great day!
  190.  
  191. John Montbriand
  192. Author
  193.  
  194.  
  195.