Derived from: None
Declared in: PRegistry.h
This class is used to help you to store preferences for your program. The idea to this class is taken from Windows 95 and NT. I think this is one of the great ideas Microsoft has made, so I took the idea and created this class to handle it.
The registry is build like a directory with subdirectories and files, but the directories are named keys and the files and named values. An entry can both be a key or value. The root is called "/", just like the root in the filesystem. If you want to access some subkeys, you just add the names in the path, e.g. "/key1/mykey/".
All the values are also named and they can have some different types. The types are: String, number, signed number and data. There are functions to create a value for each type.
The common use is to create one instance of the class in shared memory and then use this instance to store and read the preferences.
PRegistry(void); throw (PSystemException);
The constructor will create and initialize the root key and make the class ready to use.
~PRegistry()
~PRegistry(void);
Will clean up all memory used.
CloseKey()
void CloseKey(void *handle); throw (PFileException);
Will close the key you have opened with the OpenKey() function. The argument is the handle you got from the OpenKey() function.
CopyKey()
void CopyKey(PString source, PString destination, PRegistry *destReg = NULL); throw (PFileException);
This function will copy a key into another key. It takes all the subkeys and entries inside the source key and copy them inside the destination key. Make sure the destination key is created before you call this function. The last argument is the registry where the destination key is stored. If this is NULL, it's the same registy as the source key, which is the this object.
CreateData()
void CreateData(void *handle, PString name, const void *dataAdr, uint32 size); throw (PFileException);
This function will create a value in the opened key with the type data. The arguments are the handle you got from the OpenKey() function, the name of the new value, a pointer to the data and the size of the data in bytes. If the value already exists, it will be overwritten. If you try to create a value with the same name as a key, a PFileException will be thrown.
CreateKey()
void CreateKey(void *handle, PString name); throw (PFileException);
With this function you can create a new key in the key you have opened with the OpenKey() function. The arguments are the handle you got from the OpenKey() function and the name of the new key. If the key already exists, nothing will happend. To create a key which already exists, is not taken as an error.
CreateNumber()
void CreateNumber(void *handle, PString name, int32 num); throw (PFileException);
This function will create a value in the opened key with the type number. The arguments are the handle you got from the OpenKey() function, the name of the new value and the number you want to store. If the value already exists, it will be overwritten. If you try to create a value with the same name as a key, a PFileException will be thrown.
CreateString()
void CreateString(void *handle, PString name, PString str); throw (PFileException);
This function will create a value in the opened key with the type string. The arguments are the handle you got from the OpenKey() function, the name of the new value and the string data. If the value already exists, it will be overwritten. If you try to create a value with the same name as a key, a PFileException will be thrown.
Exists()
bool Exists(void *handle, PString name); throw (PFileException);
This function will search through the opened key to see if the name exists in it. The name can both be the name of a key or value. If it found the name, it will return true, else it will return false.
GetData()
void *GetData(void *handle, PString name, uint32 *size); throw (PFileException);
This function will return a pointer to the data block stored in the value you give. The arguments are the handle you got from the OpenKey() function, the name of the value you want the data from and a pointer to store the size of the data in. If the value couldn't be found or if it's a key, a PFileException will be thrown.
void *GetNextKey(void *handle, PString &name); throw (PFileException);
Use this function when you want to enumerate the current opened key after subkeys. You has to first call the InitKeyEnum() function. It will return a new handle to use the next time you call this function or NULL if the returned information is the last entry. The arguments are the handle you got from the InitKeyEnum() function and a reference to a PString where to store the key name. This function will skip values, so it will only be keys which are returned. Here is a little example to show how to use this function:
PString name; void *handle; handle = reg.InitKeyEnum(openHandle); while (handle != NULL) { handle = reg.GetNextKey(handle, name); // Work on the data }
void *GetNextValue(void *handle, PString &name, void **buffer, uint32 *size, PRegKind *type); throw (PFileException);
Use this function when you want to enumerate the current opened key after values. You has to first call the InitValueEnum() function. It will return a new handle to use the next time you call this function or NULL if the returned information is the last entry. The arguments are the handle you got from the InitValueEnum() function, a reference to a PString where to store the value name, a pointer to a void * where it stores the pointer to the data, a pointer to store the size of the data in and a pointer to store the type of the data in. The type can be pData, pNumber or pString. This function will skip subkeys, so it will only be values which are returned. Here is a little example to show how to use this function:
void *buffer; uint32 size; PRegistry::PRegKind type; PString name; void *handle; handle = reg.InitValueEnum(openHandle); while (handle != NULL) { handle = reg.GetNextValue(handle, name, &buffer, &size, &type); // Work on the data }
GetNumber()
int32 GetNumber(void *handle, PString name); throw (PFileException);
This function will return the number stored in the value you give. The arguments are the handle you got from the OpenKey() function and the name of the value you want the number from. If the value couldn't be found or if it's a key, a PFileException will be thrown.
GetString()
PString GetString(void *handle, PString name); throw(PFileException);
This function will return the string stored in the value you give. The arguments are the handle you got from the OpenKey() function and the name of the value you want the string from. If the value couldn't be found or if it's a key, a PFileException will be thrown.
void *InitKeyEnum(void *handle); throw (PFileException);
When you want to enumerate the current opened key after subkeys, you first have to call this function. It will initialize and return a handle you has to use with the GetNextKey() function or NULL if the current key is empty. The argument is the handle you got from the OpenKey() function.
void *InitValueEnum(void *handle); throw (PFileException);
When you want to enumerate the current opened key after values, you first have to call this function. It will initialize and return a handle you has to use with the GetNextValue() function or NULL if the current key is empty. The argument is the handle you got from the OpenKey() function.
LoadReg()
void LoadReg(PString company, PString program, PString fileName); throw (PFileException);
With this function you can load the whole registry into the memory from the disk. This function will you probally only call once and that is after you have created the instance of this class. The arguments is the name of your company, the name of your program and the filename of the file to load without any path.
The first two arguments are used to create a directory in the users settings directory. Let's say the users directory are stored at this location: /boot/home/config/settings. You give in as company the string "Polycode" and as program name the string "APlayer". There will then be created two directories in the users settings directory, so your config file will be loaded from /boot/home/config/settings/Polycode/APlayer/.
The reason that there are created two directories, is that if you have more than one program, all your programs settings will be stored under your company name and all the settings for each program will be stored under the program name.
void *OpenKey(PString path); throw (PFileException);
This function will try to open the key with the path you give. The path has to start and end with a slash, e.g. "/" for the root or "/key/MyKey/" for the subkey "MyKey". Notice that the path is case sentitive. If the key couldn't be opened, a PFileException will be thrown, else a handle is returned which you have to use to all the other registry calls you made.
RemoveKey()
void RemoveKey(void *handle, PString name); throw (PFileException);
This function will remove a key from the opened key and all its entries. If the key couldn't be found or the key is opened, an PFileException will be thrown. The arguments are the handle you got from the OpenKey() function and the name of the key you want to remove.
RemoveKeyEntries()
void RemoveKeyEntries(void *handle, PString name); throw (PFileException);
This function will remove all the entries from a key in the opened key. If the key couldn't be found, a PFileException will be thrown. The arguments are the handle you got from the OpenKey() function and the name of the key you want to remove the entries from.
RemoveValue()
void RemoveValue(void *handle, PString name); throw (PFileException);
This function will remove a value from the opened key. The value can be any type. If the value couldn't be found, a PFileException will be thrown. The arguments are the handle you got from the OpenKey() function and the name of the value you want to remove.
SaveReg()
void SaveReg(PString company, PString program, PString fileName); throw (PFileException);
This function will save the whole registry to the disk. Do only call this function when the user presses the save button in your preferences window or you really want to flush the data to disk. The arguments is the name of your company, the name of your program and the filename of the file to load without any path.
The first two arguments are used to create a directory in the users settings directory. Let's say the users directory are stored at this location: /boot/home/config/settings. You give in as company the string "Polycode" and as program name the string "APlayer". There will then be created two directories in the users settings directory, so your config file will be loaded from /boot/home/config/settings/Polycode/APlayer/.
The reason that there are created two directories, is that if you have more than one program, all your programs settings will be stored under your company name and all the settings for each program will be stored under the program name.