home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / i / inifn135.zip / INIFUNC.DOC < prev    next >
Text File  |  1993-03-05  |  13KB  |  436 lines
  1.  
  2.     INI file handler package
  3.  
  4.     (c) Copyright 1992, 1993 DAF, Inc.
  5.     All rights reserved.
  6.  
  7.  
  8.  
  9. What is an INI file ?
  10. =====================
  11.  
  12. INI files are used to store configuration information for application
  13. programs. They are ASCII text files that can be edited with text editors
  14. in plain ASCII mode (i.e. no formatting information enclosed). INI files
  15. are interpreted on a line-by-line basis. Empty lines are ignored.
  16.  
  17. INI files can contain information that has Boolean, numerical or text
  18. character, both individual values as well as one-dimensional arrays of
  19. values.
  20.  
  21. Information is stored in assignments of the form 'Keyword=Information'
  22. referred to herein as an Item. 'Keyword' represents an alpha-numeric
  23. identifier referred to herein as a Key.
  24.  
  25. INI files are separated into sections. Each section may contain any number
  26. of items, including none at all. Information is retrieved by referencing
  27. an item within a section. Thus, items in different sections may have the
  28. same key. An INI file section is identified by a line starting with the
  29. section name enclosed in square brackets in the leftmost column. The
  30. section's end is defined as either the next line starting with a square
  31. bracket or the end of the file.
  32.  
  33. Lines are interpreted until the first semicolon (';'), asterisk ('*') or
  34. crosshatch ('#') is reached. These characters are used to separate comments
  35. from INI information.
  36.  
  37.  
  38.  
  39. What does this package offer ?
  40. ==============================
  41.  
  42. This package offers functions to retrieve and manipulate information
  43. stored in INI files. These functions are written in C and use the
  44. 'standard I/O' package provided with virtually all C compilers today.
  45. The size of the INI files is not limited in any way, and runtime heap
  46. and stack memory requirements are minimal.
  47.  
  48. Information is retrieved from INI files by creating an INI handle and
  49. associating data items with it. After reading information from the INI
  50. file these items can be retrieved and changed, and the INI file can be
  51. updated to reflect changes.
  52.  
  53. Although this object-oriented approach takes up more space than the
  54. underlying set of functions based on 'C' structures and unions, it
  55. provides for type and boundary checking and makes applications less
  56. dependent on this package's internal workings.
  57.  
  58.  
  59.  
  60.  
  61. Data types
  62. ==========
  63.  
  64. Data types understood by this set of functions are Boolean, numerical and
  65. string types. The following is a list of the types and the kind of data
  66. area the functions work on.
  67.  
  68.     BOOL:        Boolean assignments in an INI file take on the form
  69.                 'Key=true' or 'Key=false'. 'True' and 'false'
  70.                 alternatively can be represented by '1' or 'y' and
  71.                 '0' or 'n', respectively. BOOL pointers point to
  72.                 signed C integer values. For most PC-based C compilers
  73.                 this means a 16bit integer.
  74.  
  75.     SHORT:        Short and unsigned short assignments have the form
  76.     USHORT:        'Key=Number', with Number being a decimal or
  77.                 hexadecimal number within the valid range for C 'short'
  78.                 or 'unsigned short' values. SHORT and USHORT
  79.                 data pointers address 'short' and 'unsigned short'
  80.                 values, respectively.
  81.  
  82.     LONG:        Long and unsigned long assignments have the form
  83.     ULONG:        'Key=Number', with Number being a decimal or
  84.                 hexadecimal number within the valid range for C 'long'
  85.                 or 'unsigned long' values. LONG and ULONG
  86.                 data pointers address 'long' and 'unsigned long'
  87.                 values, respectively.
  88.  
  89.     STRING:        String assignments have the form 'Key=String'. If
  90.                 'String' contains whitespace characters, commas or
  91.                 characters indicating INI file comments, it needs
  92.                 to be enclosed by quotes or double quotes. STRING
  93.                 data pointers address arrays of C 'char' values and
  94.                 arrays of pointers to arrays of 'char' values.
  95.  
  96.  
  97.  
  98.  
  99. INI file handle data type
  100. =========================
  101.  
  102. The data type used for handles referring to INI files is defined as a
  103. pointer to a void:
  104.  
  105.         typedef    void    *INIHNDL;
  106.  
  107. This void pointer actually addresses a control structure that is managed
  108. internally.
  109.  
  110.  
  111.  
  112.  
  113. Status codes
  114. ============
  115.  
  116. Functions that return an 'int' status value will return zero if successful
  117. or a combination of the following values in case of errors:
  118.  
  119.     IF_OK            0x0000    /* No error                                    */
  120.  
  121.     IF_BADRANGE        0x0001    /* Value out of range                        */
  122.     IF_BUSY            0x0002    /* Item exists already                        */
  123.     IF_NOMEM        0x0004    /* Out of memory                            */
  124.     IF_BADTYPE        0x0008    /* Bad type                                    */
  125.     IF_BADHNDL        0x0010    /* Bad handle                                */
  126.     IF_NOTFILLED    0x0020    /* Item was not filled by scan                */
  127.     IF_NOSECT        0x0040    /* Section not found in INI file            */
  128.     IF_BADKEY        0x0080    /* Unrecognized key                            */
  129.     IF_SYNTAX        0x0100    /* Bad syntax in INI file                    */
  130.     IF_TOOMANY        0x0200    /* Too many elements for item                */
  131.     IF_OPEN            0x0400    /* File not found                            */
  132.     IF_IOERR        0x0800    /* I/O error                                */
  133.     IF_LOST            0x1000    /* Update: lost original version of INI file*/
  134.  
  135.     IF_ERROR        0x1fff    /* All the error values                        */
  136.  
  137.  
  138.  
  139.  
  140.  
  141. INI handle constructor/destructor
  142. =================================
  143.  
  144. INIHNDL    CreateIniHandle(char *section);
  145.  
  146.     Purpose:    Creates an INI handle.
  147.     Arguments:    Pointer to string with the section name.
  148.     Returns:    Handle if successful, NULL otherwise (out of memory).
  149.  
  150.  
  151.  
  152. int        DeleteIniHandle(INIHNDL inihndl);
  153.  
  154.     Purpose:    Disposes an INI handle and all associated data.
  155.     Arguments:    INI handle
  156.     Returns:    Status
  157.  
  158.  
  159.  
  160. Functions to access and modify INI file information
  161. ===================================================
  162.  
  163. int        ReadIniInfo(INIHNDL inihndl, char *inifile);
  164.  
  165.     Purpose:    Read information from INI file to handle
  166.     Arguments:    INI handle, Name of file
  167.     Returns:    Status
  168.  
  169.  
  170.  
  171. int        WriteIniInfo(INIHNDL inihndl, char *inifile);
  172.  
  173.     Purpose:    Write information from INI handle to a file
  174.     Arguments:    INI handle, Name of file
  175.     Returns:    Status
  176.  
  177.  
  178.  
  179.  
  180. Functions to build and delete INI items
  181. =======================================
  182.  
  183. int        DeleteIniItem(INIHNDL inihndl, char *key);
  184.  
  185.     Purpose:    Delete item from handle
  186.     Arguments:    INI handle, key of item to be deleted
  187.     Returns:    Status
  188.  
  189.  
  190.  
  191. int        BuildBoolIniItem(INIHNDL inihndl, char *key, int defval);
  192.  
  193.     Purpose:    Build Boolean item
  194.     Arguments:    INI handle, key of item to be created, default value
  195.     Returns:    Status
  196.  
  197.  
  198.  
  199. int        BuildShortIniItem(INIHNDL inihndl, char *key, short defval, short minval, short maxval);
  200. int        BuildUshortIniItem(INIHNDL inihndl, char *key, ushort defval, ushort minval, ushort maxval);
  201. int        BuildLongIniItem(INIHNDL inihndl, char *key, long defval, long minval, long maxval);
  202. int        BuildUlongIniItem(INIHNDL inihndl, char *key, ulong defval, ulong minval, ulong maxval);
  203.  
  204.     Purpose:    Build numerical item
  205.     Arguments:    INI handle, key of item to be created, default value,
  206.                 minimum and maximum values
  207.     Returns:    Status
  208.  
  209.  
  210.  
  211. int        BuildStringIniItem(INIHNDL inihndl, char *key, int maxlen, char *defstr);
  212.  
  213.     Purpose:    Build string item
  214.     Arguments:    INI handle, key of item to be created, maximum length
  215.                 (including trailing 0), default string
  216.     Returns:    Status
  217.  
  218.  
  219.  
  220. int        BuildBoolsIniItem(INIHNDL inihndl, char *key, int num, int defval);
  221.  
  222.     Purpose:    Build array of Boolean values item
  223.     Arguments:    INI handle, key of item to be created, number of elements
  224.                 in array, default value
  225.     Returns:    Status
  226.  
  227.  
  228.  
  229. int        BuildShortsIniItem(INIHNDL inihndl, char *key, int num, short defval, short minval, short maxval);
  230. int        BuildUshortsIniItem(INIHNDL inihndl, char *key, int num, ushort defval, ushort minval, ushort maxval);
  231. int        BuildLongsIniItem(INIHNDL inihndl, char *key, int num, long defval, long minval, long maxval);
  232. int        BuildUlongsIniItem(INIHNDL inihndl, char *key, int num, ulong defval, ulong minval, ulong maxval);
  233.  
  234.     Purpose:    Build array of numerical values item
  235.     Arguments:    INI handle, key of item to be created, number of elements
  236.                 in array, default value, minimum and maximum values
  237.     Returns:    Status
  238.  
  239.  
  240.  
  241. int        BuildStringsIniItem(INIHNDL inihndl, char *key, int num, int maxlen, char *defstr);
  242.  
  243.     Purpose:    Build array of strings item
  244.     Arguments:    INI handle, key of item to be created, number of elements
  245.                 in array, maximum length (including trailing 0) per element,
  246.                 default string
  247.     Returns:    Status
  248.  
  249.  
  250.  
  251. Functions to retrieve data from INI items
  252. =========================================
  253.  
  254. int        GetBoolIniItem(INIHNDL inihndl, char *key, int *valptr);
  255.  
  256.     Purpose:    Get data from Boolean item
  257.     Arguments:    INI handle, key of item, pointer to Boolean variable
  258.     Returns:    Status
  259.  
  260.  
  261.  
  262. int        GetShortIniItem(INIHNDL inihndl, char *key, short *valptr);
  263. int        GetUshortIniItem(INIHNDL inihndl, char *key, ushort *valptr);
  264. int        GetLongIniItem(INIHNDL inihndl, char *key, long *valptr);
  265. int        GetUlongIniItem(INIHNDL inihndl, char *key, ulong *valptr);
  266.  
  267.     Purpose:    Get data from numerical item
  268.     Arguments:    INI handle, key of item, pointer to numerical variable
  269.     Returns:    Status
  270.  
  271.  
  272.  
  273. int        GetStringIniItem(INIHNDL inihndl, char *key, char *strptr);
  274.  
  275.     Purpose:    Get data from string item
  276.     Arguments:    INI handle, key of item, pointer to string buffer
  277.     Returns:    Status
  278.  
  279.  
  280.  
  281. int        GetBoolsIniItem(INIHNDL inihndl, char *key, int *valptr, int num);
  282.  
  283.     Purpose:    Get data from array of Boolean values item
  284.     Arguments:    INI handle, key of item, pointer to array of Boolean
  285.                 variables, number of elements to get
  286.     Returns:    Status
  287.  
  288.  
  289.  
  290. int        GetShortsIniItem(INIHNDL inihndl, char *key, short *valptr, int num);
  291. int        GetUshortsIniItem(INIHNDL inihndl, char *key, ushort *valptr, int num);
  292. int        GetLongsIniItem(INIHNDL inihndl, char *key, long *valptr, int num);
  293. int        GetUlongsIniItem(INIHNDL inihndl, char *key, ulong *valptr, int num);
  294.  
  295.     Purpose:    Get data from array of numerical values item
  296.     Arguments:    INI handle, key of item, pointer to array of numerical
  297.                 variables, number of elements to get
  298.     Returns:    Status
  299.  
  300.  
  301. int        GetStringsIniItem(INIHNDL inihndl, char *key, char **strptr, int num);
  302.  
  303.     Purpose:    Get data from array of strings item
  304.     Arguments:    INI handle, key of item, pointer to array of pointers
  305.                 to string buffers, number of elements to get
  306.     Returns:    Status
  307.  
  308.  
  309.  
  310. Functions to modify data of INI items
  311. =====================================
  312.  
  313. int        SetBoolIniItem(INIHNDL inihndl, char *key, int value);
  314.  
  315.     Purpose:    Set data of Boolean item
  316.     Arguments:    INI handle, key of item, Boolean value
  317.     Returns:    Status
  318.  
  319.  
  320.  
  321. int        SetShortIniItem(INIHNDL inihndl, char *key, short value);
  322. int        SetUshortIniItem(INIHNDL inihndl, char *key, ushort value);
  323. int        SetLongIniItem(INIHNDL inihndl, char *key, long value);
  324. int        SetUlongIniItem(INIHNDL inihndl, char *key, ulong value);
  325.  
  326.     Purpose:    Set data of numerical item
  327.     Arguments:    INI handle, key of item, numerical value
  328.     Returns:    Status
  329.  
  330.  
  331.  
  332. int        SetStringIniItem(INIHNDL inihndl, char *key, char *strptr);
  333.  
  334.     Purpose:    Set data of string item
  335.     Arguments:    INI handle, key of item, string to copy from
  336.     Returns:    Status
  337.  
  338.  
  339.  
  340. int        SetBoolsIniItem(INIHNDL inihndl, char *key, int *valptr, int num);
  341.  
  342.     Purpose:    Set data of array of Boolean values item
  343.     Arguments:    INI handle, key of item, pointer to array of Boolean
  344.                 values, number of elements to set
  345.     Returns:    Status
  346.  
  347.  
  348.  
  349. int        SetShortsIniItem(INIHNDL inihndl, char *key, short *valptr, int num);
  350. int        SetUshortsIniItem(INIHNDL inihndl, char *key, ushort *valptr, int num);
  351. int        SetLongsIniItem(INIHNDL inihndl, char *key, long *valptr, int num);
  352. int        SetUlongsIniItem(INIHNDL inihndl, char *key, ulong *valptr, int num);
  353.  
  354.     Purpose:    Set data of array of numerical values item
  355.     Arguments:    INI handle, key of item, pointer to array of numerical
  356.                 values, number of elements to set
  357.     Returns:    Status
  358.  
  359.  
  360.  
  361. int        SetStringsIniItem(INIHNDL inihndl, char *key, char **strptr, int num);
  362.  
  363.     Purpose:    Set data of array of strings item
  364.     Arguments:    INI handle, key of item, pointer to array of pointers
  365.                 to strings to copy, number of elements to set
  366.     Returns:    Status
  367.  
  368.  
  369.  
  370.  
  371. Using the functions
  372. ===================
  373.  
  374. In order to access or modify INI file information, the following steps
  375. need to be taken:
  376.  
  377.     1) Create INI handle
  378.  
  379.         INIHNDL        ih;
  380.  
  381.         if( (ih = CreateIniHandle("MySection")) == NULL ) {
  382.             // Error: out of memory
  383.             }
  384.  
  385.     2) Build item descriptions
  386.  
  387.         int        res;
  388.  
  389.         res = BuildLongIniItem(ih, "SomeLongValue", 0, 0, 99);
  390.         res |= BuildShortIniItem(ih, "SomeShortValue", 123, 100, 999);
  391.         ...
  392.  
  393.         if(res & IF_ERROR) {
  394.             // Error
  395.             DeleteIniHandle(ih);
  396.             // handle error case...
  397.             }
  398.  
  399.     3) Read INI file
  400.  
  401.         int        res;
  402.  
  403.         res = ReadIniInfo(ih, "MyApp.Ini");
  404.  
  405.         if(res & IF_ERROR) {
  406.             // Error
  407.             ...
  408.             }
  409.  
  410.     4) Get the data
  411.  
  412.         short    s;
  413.         long    l;
  414.  
  415.         res = GetLongIniItem(ih, "SomeLongValue", &l);
  416.         res |= GetShortIniItem(ih, "SomeShortValue", &s);
  417.         ...
  418.  
  419.         if(res & IF_ERROR) {
  420.             // Error
  421.             ...
  422.             }
  423.  
  424.     5) Modify and update information
  425.  
  426.         res = SetShortIniItem(ih, "SomeShortValue", 333);
  427.         res |= WriteIniInfo(ih, "MyApp.Ini");
  428.  
  429.         if(res & IF_ERROR) {
  430.             // Error
  431.             ...
  432.             }
  433.  
  434.  
  435.  
  436.