home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IPROFILE.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  14KB  |  272 lines
  1. #ifndef _IPROFILE_
  2. #define _IPROFILE_
  3. /*******************************************************************************
  4. * FILE NAME: iprofile.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   This file contains the declaration(s) of the class(es):                    *
  8. *     IProfile - Class providing interface to OS/2 .ini files.                 *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   Licensed Materials - Property of IBM                                       *
  12. *   (C) Copyright IBM Corporation 1992, 1993                                   *
  13. *   All Rights Reserved                                                        *
  14. *   US Government Users Restricted Rights - Use, duplication, or               *
  15. *   disclosure                                                                 *
  16. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  17. *                                                                              *
  18. *******************************************************************************/
  19. #ifndef _IVBASE_
  20.   #include <ivbase.hpp>
  21. #endif
  22. #ifndef  _IHANDLE_
  23.   #include <ihandle.hpp>
  24. #endif
  25. #ifndef  _ISTRING_
  26.   #include <istring.hpp>
  27. #endif
  28.  
  29. /*----------------------------------------------------------------------------*/
  30. /* Align classes on four byte boundary.                                       */
  31. /*----------------------------------------------------------------------------*/
  32. #pragma pack(4)
  33.  
  34. class IProfile : public IVBase {
  35. typedef IVBase
  36.   Inherited;
  37. /*******************************************************************************
  38. | The IProfile class's objects represent profile data sets (.ini files).       |
  39. | They provide functions to query and set persistent application data based    |
  40. | on application-defined keys.                                                 |
  41. |                                                                              |
  42. | The profile data set stores information by two keys.  The first key is the   |
  43. | application name, which is stored as a string.  The second key is the key    |
  44. | name, which is stored as either a string or an integer.  Profile data can    |
  45. | be stored as text, binary and integer by the keys.                           |
  46. |                                                                              |
  47. | Example:                                                                     |
  48. |                                                                              |
  49. |    IProfile* pProf = new IProfile("MySystem");                               |
  50. |    pProf->setDefaultApplicationName("MyApp");                                |
  51. |                                                                              |
  52. |    //To write data                                                           |
  53. |    pProf->addOrReplaceElementWithKey("My_Name",    //key is My_Name          |
  54. |                                      "Kevin");     //text data               |
  55. |    pProf->addOrReplaceElementWithKey("My_Age",     //key is My_Age           |
  56. |                                      25);          //integer data            |
  57. |    //To read data                                                            |
  58. |    IString myName = pProf->elementWithKey("My_Name"); //read text date       |
  59. |    long    myAge  = pProf->integerWithKey("My_Name"); //read text date       |
  60. *******************************************************************************/
  61. public:
  62. /*------------------------- Constructors/Destructor ----------------------------
  63. | You can construct instances of this class from the name of the profile data  |
  64. | set.                                                                         |
  65. |                                                                              |
  66. | NOTE: You can only open six data sets at one time.  This is a system         |
  67. |       restriction.                                                           |
  68. ------------------------------------------------------------------------------*/
  69.   IProfile ( const char      *profileName );
  70.   IProfile ( const IProfile& aProfile );
  71.  
  72. virtual
  73.   ~IProfile ( );
  74.  
  75. /*-------------------------------- Assignment ----------------------------------
  76. | This operator is used for assignment:                                        |
  77. |   operator = - Assignment operator used to track references to the resource. |
  78. ------------------------------------------------------------------------------*/
  79. IProfile
  80.  &operator = ( const IProfile &aProfile );
  81.  
  82. /*----------------------------- Special Profiles -------------------------------
  83.   There are two special instances of this class corresponding to the "system"
  84.   and "user" profiles.  These objects are obtained using the following static
  85.   functions:
  86.     systemProfile - Returns the system profile.
  87.     userProfile   - Returns the user profile.
  88. ------------------------------------------------------------------------------*/
  89. static IProfile
  90.   systemProfile ( ),
  91.   userProfile   ( );
  92.  
  93. /*-------------------------------- Accessors -----------------------------------
  94. | These functions provide a means of getting the profile information of        |
  95. | instances of this class:                                                     |
  96. |   name                 - Returns the profile file name.                      |
  97. |   handle               - Returns the profile handle.                         |
  98. |   numberOfKeys         - Returns the number of keys for the application      |
  99. |                          name.                                               |
  100. |   numberOfApplications - Returns the number of application names in the      |
  101. |                          profile.                                            |
  102. ------------------------------------------------------------------------------*/
  103. IString
  104.   name ( ) const;
  105.  
  106. IProfileHandle
  107.   handle() const;
  108.  
  109. unsigned long
  110.   numberOfKeys         ( const char *applName = 0 ) const,
  111.   numberOfApplications ( ) const;
  112.  
  113. /*----------------------------- Application Name -------------------------------
  114. | These functions control the default "application name" component of the      |
  115. | keys used to access the profile.  This application name will be used by      |
  116. | default for all reads and writes to the profile.                             |
  117. |   defaultApplicationName    - Returns the current default application name.  |
  118. |   setDefaultApplicationName - Sets the default application name.  All        |
  119. |                               subsequent calls with a null application name  |
  120. |                               will use this default name.                    |
  121. ------------------------------------------------------------------------------*/
  122. const IString&
  123.   defaultApplicationName ( ) const;
  124.  
  125. IProfile
  126.   &setDefaultApplicationName ( const char *applName );
  127.  
  128. /*----------------------------- Reading/Writing --------------------------------
  129. | The following function read and write application data for a given           |
  130. | appName/keyName:                                                             |
  131. |   elementWithKey               - Reads the application data and returns it   |
  132. |                                  as an IString.                              |
  133. |   integerWithKey               - Reads the application data and returns it   |
  134. |                                  as a long integer.                          |
  135. |   addOrReplaceElementWithKey   - Writes the argument number, text or binary  |
  136. |                                  data.  Text and binary is passed as         |
  137. |                                  IString.                                    |
  138. |   deleteElementWithKey         - Removes the data at a given application     |
  139. |                                  and key pair.                               |
  140. |   deleteElementWithApplication - Removes data for all keys for the argument  |
  141. |                                  application name.                           |
  142. ------------------------------------------------------------------------------*/
  143. IString
  144.   elementWithKey ( const char *key,
  145.                    const char *applName = 0 ) const;
  146.  
  147. long
  148.   integerWithKey ( const char *key,
  149.                    const char *applName = 0 ) const;
  150.  
  151. IProfile
  152.  &addOrReplaceElementWithKey ( const char *key,
  153.                                const IString& data,
  154.                                const char *applName = 0 ),
  155.  
  156.  &addOrReplaceElementWithKey ( const char *key,
  157.                                long        data,
  158.                                const char *applName = 0 );
  159.  
  160. IProfile
  161.  &deleteElementWithKey ( const char *key,
  162.                          const char *applName = 0 ),
  163.  
  164.  &deleteElementWithApplication ( const char *applName = 0 );
  165.  
  166. /*--------------------------------- Testing ------------------------------------
  167. | The following functions test whether a given application name and/or key     |
  168. | exist in the profile:                                                        |
  169. |   containsApplication - Returns true if the profile contains data for the    |
  170. |                         argument application name.                           |
  171. |   containsKeyName     - Returns true if the profile contains data for the    |
  172. |                         argument application and key pair.                   |
  173. ------------------------------------------------------------------------------*/
  174. Boolean
  175.   containsApplication ( const char *applName ) const,
  176.   containsKeyName     ( const char *key,
  177.                         const char *applName = 0 ) const;
  178.  
  179. class Cursor : public IVBase {
  180. /*******************************************************************************
  181. * The IProfile::Cursor nested class is used to iterate over the appliction     *
  182. * names or keys in a profile.                                                  *
  183. *******************************************************************************/
  184. public:
  185. /*-------------------------- Constructor/Destructor ----------------------------
  186. | You can construct an instance of IProfile::Cursor for the following          |
  187. | purposes:                                                                    |
  188. |    - To create a cursor to iterate over the application names.  This         |
  189. |      instance is constructed from a reference to the profile.                |
  190. |    - To create a cursor to iterate over the keys.  This instance is          |
  191. |      constructed from a reference to the profile with an application name.   |
  192. |                                                                              |
  193. | NOTE: The cursor object is invalidated to the current state of application   |
  194. |       names or key names in the profile file.                                |
  195. ------------------------------------------------------------------------------*/
  196.   Cursor ( IProfile   &profile);
  197.   Cursor ( IProfile   &profile,
  198.            const char *applName);
  199.   ~Cursor ( );
  200.  
  201. /*-------------------------------- Overrides -----------------------------------
  202. | The nested Cursor class overrides the following functions to                 |
  203. | provide the appropriate cursor behavior:                                     |
  204. |   setToFirst    - Resets the position to the first application or key.       |
  205. |   setToNext     - Advances the position to the next application or key.      |
  206. |   setToPrevious - Backs up the position to the previous application or key.  |
  207. |   setToLast     - Sets the position to the last application or key.          |
  208. |   isValid       - Returns true if the cursor is not off the end.  If         |
  209. |                   checkFile is set to true, isValid checks to see if the     |
  210. |                   file application and key information has been changed by   |
  211. |                   another application while your application still has it    |
  212. |                   open.                                                      |
  213. |   invalidate    - Marks the cursor as invalid.                               |
  214. ------------------------------------------------------------------------------*/
  215. Boolean
  216.   setToFirst    ( ),
  217.   setToNext     ( ),
  218.   setToPrevious ( ),
  219.   setToLast     ( ),
  220.   isValid       ( Boolean checkFile = false ) const;
  221.  
  222. void
  223.   invalidate    ( );
  224.  
  225. private: /*------------------------ PRIVATE ----------------------------------*/
  226. unsigned
  227.   pos;
  228. IString
  229.   strCl,
  230.   applNameCl;
  231. IProfileHandle
  232.   hProfileCl;
  233. void
  234.   initCursor ( const IProfileHandle &hProfile,
  235.                const char            *appName  );
  236. friend class IProfile;
  237. };  //Cursor
  238.  
  239. /*---------------------- Enumerating Applications/Keys -------------------------
  240.     applicationOrKeyAt - Returns the application name or key at the argument
  241.                          cursor.
  242. ------------------------------------------------------------------------------*/
  243. IString
  244.   applicationOrKeyAt ( const Cursor &cursor ) const;
  245.  
  246. /*------------------------ PRIVATE ----------------------------------*/
  247. private:
  248.   IProfile ( const IProfileHandle& profile );
  249.  
  250. unsigned long
  251.   length( const char *keyName,
  252.           const char *applName = 0 ) const;
  253.  
  254. IProfileHandle
  255.   hIni;
  256. IString
  257.   defApplName,
  258.   profileName;
  259.  
  260. }; // class IProfile
  261.  
  262. /*----------------------------------------------------------------------------*/
  263. /* Resume compiler default packing.                                           */
  264. /*----------------------------------------------------------------------------*/
  265. #pragma pack()
  266.  
  267. #ifndef I_NO_INLINES
  268.   #include <iprofile.inl>
  269. #endif
  270.  
  271. #endif // _IPROFILE_
  272.