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

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

IProfile

AIX Considerations

OS/2 Considerations

Windows Considerations

IProfile - Member Functions and Data by Group

Constructors & Destructor

Default Application Name

Profile Information

Reading and Writing Data

Special Profiles

Testing

IProfile - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data