home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / config / config.txt < prev    next >
Text File  |  1996-05-25  |  7KB  |  227 lines
  1.  
  2.             Config v1.0
  3.  
  4.            by Adam Dawes
  5.  
  6.            25th May 1996
  7.  
  8.  
  9.  
  10. Introduction
  11. ~~~~~~~~~~~~
  12.  
  13. Well, I hate Windows as much as the next man, but occasionally I stumble
  14. across a good idea hidden away within the operating system.
  15.  
  16. There are a couple of functions buried in there for reading and writing
  17. configuration files, and they actually make things very easy. I decided I'd
  18. had enough of messing around with config files on my Amiga, so I've ported
  19. the functions to Amiga C.
  20.  
  21. The idea is that the configuration files take a definitive structure which
  22. the Config functions can understand. Each config file is split in to a
  23. number of "Sections" (which are stored in the config file as a keyword
  24. inside square brackets). In each of these sections are a number of "Items",
  25. each of which contains an actual data item. The items are local to the
  26. section that contains them, so it's perfectly legal to use one item name in
  27. several sections, they'll all be treated separately.
  28.  
  29. The beauty behind the functions is you don't have to worry about creating
  30. files or scanning through them. Even when it comes to reading data, you
  31. don't have to care if the config file exists or not as you provide a
  32. default value to use if the file/section/item cannot be located.
  33. Everything is automated within the Config functions.
  34.  
  35.  
  36.  
  37.  
  38. Using the Config Functions
  39. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  40.  
  41. There are 4 public functions within the Config source code, as follows:
  42.  
  43.  
  44.    WriteConfig()
  45.    WriteConfigNumber()
  46.    ReadConfig()
  47.    ReadConfigNumber()
  48.  
  49.  
  50. Each of these functions is detailed below.
  51.  
  52.  
  53.  
  54. Function:
  55.     int WriteConfig(char *filename, char *section, char *item, char *data);
  56.  
  57. Parameters:
  58.     filename = the name of the config file (eg, "S:MyConfig.cfg")
  59.     section = the name of the section to add config data to
  60.     item = the item within the section to contain the config data
  61.     data = the actual data itself
  62.  
  63. Details:
  64.     You do not need to worry about anything at all when calling this
  65.     function. If the config file specified doesn't exist, it'll be
  66.     created for you. If the section specified doesn't exist, that will
  67.     be created. If the item doesn't exist, it'll be added to the
  68.     appropriate section; if it does exist, the previous data will be
  69.     replaced by the new data.
  70.  
  71.     If all goes well, the function will return CFG_WRITE_SUCCESS. If
  72.     something goes wrong (run out of memory, or the specified file
  73.     cannot be written to), CFG_WRITE_FAIL will be returned.
  74.  
  75.  
  76.  
  77. Function:
  78.     int WriteConfigNumber(char *filename, char *section, char *item, long data);
  79.  
  80. Parameters:
  81.     filename = the name of the config file
  82.     section = the name of the section to add config data to
  83.     item = the item within the section to contain the config data
  84.     data = a long integer to be written to the file
  85.  
  86. Details:
  87.     This function is more useful when reading/writing numbers to the config
  88.     file. It is actually only a small front-end to the WriteConfig()
  89.     function. If you need to write numbers that aren't longs (floats, for
  90.     instance), just make a copy of the WriteConfigNumber() function in to
  91.     your own code, and change the datatypes around as necessary. You can
  92.     then copy and alter ReadConfigNumber() appropriately as well to read
  93.     the data back in.
  94.  
  95.     As before, this will return CFG_WRITE_SUCCESS is all is well, or
  96.     CFG_WRITE_FAIL if something goes wrong.
  97.  
  98.  
  99.  
  100. Function:
  101.     int ReadConfig(char *filename, char *section, char *item, char *buffer,
  102.                    int bufsize, char *def);
  103.  
  104. Parameters:
  105.     filename = the name of the config file
  106.     section = the name of the section to read config data from
  107.     item = the item within the section that contains the config data
  108.     buffer = an empty character array ready to receive the config data
  109.     bufsize = the maximum length of chars than can be written to the buffer
  110.     def = a string that will be written to the buffer if the requested
  111.           config item cannot be found
  112.  
  113. Details:
  114.     Use ReadConfig() to get data back from your config file. It will look
  115.     for the specified section/item in the specified file.
  116.  
  117.     If the file cannot be opened, the section cannot be located, or the
  118.     item within the section is not found, the function will copy the
  119.     default string to your buffer, and return CFG_READ_SUCCESS. Therefore,
  120.     you don't need to care at all about whether the config file exists.
  121.     Just tell the function what you want to receive if your requested data
  122.     cannot be found.
  123.  
  124.     The function will return CFG_READ_SUCCESS if everything is ok, or
  125.     CFG_READ_FAIL if the string to be returned is larger than the supplied
  126.     buffer.
  127.  
  128.  
  129.  
  130. Function:
  131.     long ReadConfigNumber(char *filename, char *section, char *item,
  132.          long def);
  133.  
  134. Parameters:
  135.     filename = the name of the config file
  136.     section = the name of the section to read config data from
  137.     item = the item within the section that contains the config data
  138.     def = a long value that will be returned if the requested config item
  139.           cannot be found
  140.  
  141. Details:
  142.  
  143.     As with WriteConfigNumber(), this is just a front end to the
  144.     ReadConfig() function.
  145.  
  146.     This will return as a long value, the number located in the data item
  147.     specified. If the data item cannot be found, your default value will be
  148.     returned instead.
  149.  
  150.     This function is assumed never to fail. The string buffer is quite
  151.     large enough to hold a 32-bit value, so no errors should result using
  152.     this function.
  153.  
  154.  
  155.  
  156.  
  157. Requirements
  158. ~~~~~~~~~~~~
  159.  
  160. Obviously, you will need a C compiler to make any use of these functions.
  161. Config was written using DICE V2, but should work with any Amiga C
  162. compiler.
  163.  
  164. The sourcecode is not currently portable to other platforms, as it uses the
  165. list handling functions found in the exec.library.
  166.  
  167. The code should work with any version of the Amiga operating system, past
  168. present and future.
  169.  
  170.  
  171.  
  172.  
  173. Legal Stuff
  174. ~~~~~~~~~~~
  175.  
  176. Config and its associated files are not public domain. They may be
  177. distributed freely as long as no unreasonable charge is imposed. They may
  178. not be included within any commercial package without express written
  179. permission from the author; the exceptions from this are the AmiNet CDs and
  180. Fred Fish's collections. Config may only be distributed if all files
  181. contained within the original archive are present.
  182.  
  183. I do not accept responsibility for any damage done to your system or data
  184. lost, directly or indirectly, as a result from using this program or any of
  185. its associated files. You use the program entirely at your own risk. Of
  186. course if you *do* experience problems then I'll do what I can to sort them
  187. out, and please let me know so that I can try to cure them in a future
  188. release.
  189.  
  190.  
  191.  
  192.  
  193. History
  194. ~~~~~~~
  195.  
  196.     v1.0 (25.5.96)
  197.  
  198.         Initial release.
  199.  
  200.  
  201.  
  202. Contacting the author
  203. ~~~~~~~~~~~~~~~~~~~~~
  204.  
  205. Please do write to me if you like Config or if you have any problems with
  206. it or suggestions for a new version. I can't promise to reply quickly if
  207. you write via snail-mail, but I will do my best to always reply to email
  208. messages. I can be contacted at:
  209.  
  210.   InterNet
  211.      Adam@beachyhd.demon.co.uk
  212.  
  213.      http://www.pavilion.co.uk/rda/adam
  214.  
  215.  
  216.   FidoNet
  217.      Adam Dawes@2:441/93.5
  218.  
  219.  
  220.   SnailMail
  221.      Adam Dawes
  222.      47 Friar Road
  223.      Brighton
  224.      BN1 6NH
  225.      England
  226.  
  227.