### IProfile

  The IProfile class represents profile data sets. This class provides functions to query and set persistent application data based on application-defined keys.

  The profile data set stores information using the following two keys:

  - Application name, which is stored as a string
  - Key name, which is stored as either a string or an integer
  Profile data can be stored in text, binary, or integer format.

#### AIX Considerations

  The objects representing profile data sets are Xrm database files.

  The profile data set stores information using the following two keys:

  - Application name, which is stored as a string
  - Key name, which is stored as a string
  Both of these names must be stored as strings with no embedded spaces. You cannot store key names as integers. You can store the profile data itself as text and integer values using the keys.

#### OS/2 Considerations

  The objects representing profile data sets are initialization (.ini) files.
  Note: The number of .ini files that OS/2 Presentation Manager lets you open at one time varies depending on system limitations.

#### Windows Considerations

  Profile data is stored in the Windows registry instead of an initialization file. The registry preserves case information but ignores the case in all operations. Thus, application names and key names are not case sensitive.

### IProfile - Member Functions and Data by Group

### Constructors & Destructor

Use these members to construct, copy, assign, and destruct objects of this class. You can construct objects of this class by using the name of the profile data set or by using the copy constructor to copy one profile to another.

~IProfile

      public:
      virtual ~IProfile()

  This destructor closes the profile data set.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IProfile

  Overload 1

      public:
      IProfile(const IProfile& aProfile)

  aProfile
    Reference to an existing profile object.

  Create a profile object using a reference to an existing profile object. Use this constructor if you want to make a copy of an existing profile object.

Exception

  IAccessError | The IProfile object was not constructed. The profile name may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IProfile(const char* profileName)

  profileName
    Pointer to the profile name.

  Create a profile object with the specified profile name.

Exception

  IInvalidParameter | The IProfile object was not constructed. The profile name is missing.
  IAccessError | The IProfile object was not constructed. The profile name may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator =

      public:
      IProfile& operator =(const IProfile& aProfile)

  Assigns the member data of an object of this class to another object of this class.

Exception

  IAccessError | The IProfile object was not assigned. The profile name may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Default Application Name

Use these members to get or set the default application name. The default application name is a component of the keys that are used to access the profile. This name is used by default for all reads and writes to the profile.

defaultApplicationName

      public:
      virtual IString defaultApplicationName() const

  Returns the default application name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setDefaultApplicationName

      public:
      virtual IProfile&
        setDefaultApplicationName( const char* applName )

  Sets the default application name. All subsequent calls that do not supply an application name to functions of this class use this default name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Profile Information

Use these members to access general profile information.

applicationOrKeyAt

      public:
      virtual IString
        applicationOrKeyAt( const Cursor& cursor ) const

  Returns the application name or key at the specified cursor.

Exception

  IInvalidParameter | The application name or key was not returned. The cursor is invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

disableKeyMapping

      public:
      static void disableKeyMapping()

  Disables the mapping of special characters for the Win32 registry.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

enableKeyMapping

      public:
      static void enableKeyMapping(bool mapKey = true)

  Enables the mapping of characters that would be otherwise illegal (* and ?) in Win32 registry keys. IProfile converts them to and from special characters, which you might see if you edit the registry directly.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

handle

      public:
      virtual IProfileHandle handle() const

  Returns the profile handle.

Supported Platforms

  Windows | OS/2 | AIX
  No | Yes | Yes

name

      public:
      virtual IString name() const

  Returns the profile's name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  In AIX, the name returned includes the path.

numberOfApplications

      public:
      virtual unsigned long numberOfApplications() const

  Returns the number of application names in the profile.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

numberOfKeys

      public:
      virtual unsigned long
        numberOfKeys( const char* applName = 0 ) const

  Returns the number of keys for the application name.

Exception

  IInvalidParameter | The number of keys was not returned. The application name is missing and a default has not been specified.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Reading and Writing Data

Use these members to read or write application data for an application.

addOrReplaceElementWithKey

  Writes the specified numeric, text, or binary data. You must specify text and binary data as an IString.

  Overload 1

      public:
      virtual IProfile&
        addOrReplaceElementWithKey( const char* key,
                                    const IString& data,
                                    const char* applName = 0 )

  key
    Pointer to a key name.
  data
    Reference to an IString that contains text or binary data to use for a write.
  applName
    Pointer to an application name. If you do not supply a name, the default application name is used.

  Use this version of the function if your data is in a text or binary format.

Exception

  IInvalidParameter | The application data was not written. The key name is missing.
  IInvalidParameter | The application data was not written. The application name is missing and a default has not been specified.
  IAccessError | The application data was not written. The application name or key may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  AIX does not support the writing of binary data.

Windows Considerations

  Storing data larger than two kilobytes is not recommended due to performance and size restrictions. For data larger than two kilobytes, applications should store the data as a file and store the file name in the profile.

  Overload 2

      public:
      virtual IProfile&
        addOrReplaceElementWithKey( const char* key,
                                    long data,
                                    const char* applName = 0 )

  key
    Pointer to a key name.
  data
    Long integer numeric to use for a write.
  applName
    Pointer to an application name. If you do not supply a name, the default application name is used.

  Use this version of the function if your data is numeric.

Exception

  IInvalidParameter | The application data was not written. The key name is missing.
  IInvalidParameter | The application data was not written. The application name is missing and a default has not been specified.
  IAccessError | The application data was not written. The application name or key may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  AIX does not support the writing of binary data.

containsKeyName

      public:
      virtual bool
        containsKeyName( const char* key,
                         const char* applName = 0 )

  If the profile contains data for the specified application and key pair, true is returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

deleteElementWithApplication

      public:
      virtual IProfile&
        deleteElementWithApplication( const char* applName = 0 )

  Removes the data for all keys for the specified application name.

Exception

  IInvalidParameter | The application data was not removed. The application name is missing and a default has not been specified.
  IAccessError | The application data was not removed. The application name may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

deleteElementWithKey

      public:
      virtual IProfile&
        deleteElementWithKey( const char* key,
                              const char* applName = 0 )

  Removes the data at the specified application and key name pair.

Exception

  IInvalidParameter | The application data was not removed. The key name is missing.
  IInvalidParameter | The application data was not removed. The application name is missing and a default has not been specified.
  IAccessError | The application data was not removed. The application name or key may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

deleteProfile

      public:
      static void deleteProfile(const char* profileName)

  Removes the specified profile from the system.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

OS/2 Considerations
  Use IProfile::deleteProfile() instead of profile.deleteProfile() ( i.e. without an IProfile object ) or the IProfile destructor will recreate the .ini file just deleted.

elementWithKey

      public:
      virtual IString
        elementWithKey( const char* key,
                        const char* applName = 0 )

  Reads the application data and returns it as an IString.

Exception

  IInvalidParameter | The application data was not read. The key name is missing.
  IInvalidParameter | The application data was not read. The application name is missing and a default has not been specified.
  IAccessError | The application data was not read. The application name or key may be invalid.
  IInvalidRequest | The application data was not read. The application name or key may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

integerWithKey

      public:
      virtual long
        integerWithKey( const char* key,
                        const char* applName = 0 )

  Reads the application data and returns it as a long integer.

Exception

  IInvalidParameter | The application data was not read. The key name is missing.
  IInvalidParameter | The application data was not read. The application name is missing and a default has not been specified.
  IAccessError | The application data was not read. The application name or key may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isKeyMappingEnabled

      public:
      static bool isKeyMappingEnabled()

  Returns true is key mapping is enabled.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

### Special Profiles

Use these members to return the special objects of this class that correspond to the system and user profiles.

systemProfile

      public:
      static IProfile systemProfile()

  Returns the system profile.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

userProfile

      public:
      static IProfile userProfile()

  Returns the user profile.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

### Testing

Use these members to test a profile for an application name or an application and key name pair.

containsApplication

      public:
      virtual bool
        containsApplication( const char* applName ) const

  If the profile contains data for the specified application name, true is returned.

Exception

  IInvalidParameter | The profile query was not returned. The application name is missing.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IProfile - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None