Win\Registry - Windows Registry Access Library ============================================== File: Win\Registry - Update: 1.02 Author: J.G.Harston - Date: 16-Jul-2008 The registry is a repository of data maintained by Windows, which an application can use to hold configuration or other information from one session to the next. The registry has a hierarchical structure, not unlike a filing system. Analogous with directories are keys, which identify locations within the registry. Within each key there can be a number of named values (analogous with files) each of which can contain data. The Win\Registry library provides functions to read and write values in any part of the registry, whereas the simpler Win\Reg library provides functions to read and write strings to the user area of the registry. Win\Reg should be used in preference to Win\Registry if it is sufficient for your needs. Note that writing to the registry is potentially dangerous and can leave your system unusable. DEFPROCRegistry_Init ==================== PROCRegistry_Init sets up certain variables that the other Registry functions require. It should be called once before any other Registry functions are called. Some of these are the values used to refer to certain registry hives, and registry value types: reg_hkcr% HKEY_CLASSES_ROOT reg_hkcu% HKEY_CURRENT_USER reg_hklm% HKEY_LOCAL_MACHINE reg_hku% HKEY_USERS reg_hkpd% HKEY_PERFORMANCE_DATA reg_hkcc% HKEY_CURRENT_CONFIG reg_hkdd% HKEY_DYN_DATA reg_hkpn% HKEY_PERFORMANCE_NLSTEXT reg_hkpt% HKEY_PERFORMANCE_TEXT reg_NONE% 0 No registry entry found reg_SZ% 1 Simple string reg_EXPAND_SZ% 2 Simple string with expandable components reg_BINARY% 3 Block of binary data reg_DWORD% 4 Integer reg_MULTI_SZ% 7 Multiple strings The vast majority of normal registry access will be to the HKEY_CURRENT_USER hive, specified with reg_hkcu%. DEFPROCRegistry_WrInt(hk%,Key$,Item$,Value%) DEFPROCRegistry_WrStr(hk%,Key$,Item$,Value$,Type%) DEFPROCRegistry_Wr( hk%,Key$,Item$,Value%,Len%,Type%) ======================================================= These functions write a value to the specified registry item Item$ in the registry key Key$. The item will be created if it does not already exist. If the key already exists it is overwritten. If Item$="", then the key's default value will be written. Registry_WrInt() passes and writes an integer value. Registry_WrStr() passes the value as a string. That string can hold any value type, as specified by Type%. Registry_Wr() passes the integer value or the address of the string or data block values. For example, PROCRegistry_WrStr(reg_hkcu%, \ \ "Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders", \ \ "Personal", \ \ "H:\Docs", \ \ reg_SZ%) sets the 'My Documents' pathname to the simple string "H:\Docs". PROCRegistry_WrInt(reg_hkcu%, \ \ "Software\Microsoft\Internet Explorer\Toolbar", \ \ "Locked", \ \ 1) sets the Internet Explorer toolbar locked setting to 1. Microsoft recommend that data items larger than 2048 bytes in length should be stored in a file, and the pathname of the file stored in the registry. NOTE: PROCRegistry_Wr() is not implemented in the current library. DEFFNRegistry_RdInt(hk%,Key$,Item$) DEFFNRegistry_RdStr(hk%,Key$,Item$) DEFFNRegistry_Rd( hk%,Key$,Item$) =================================== Registry_RdStr() and Registry_Rd() read the specified registry item, returning it as a string holding the value data. Registry_RdInt() returns the value as an integer. If Item$="", then the key's default value is read. It is the responsibility of the programmer to read the value as the correct type. If a value is read as the wrong type the returned value may be meaningless. The type of a registry entry can be found with Registry_Info(). If the read type is not a simple string (type reg_SZ%, 1), then it is highly unlikely that the returned string is suitable for displaying. It is purely a block of data up to 64K in length. A return value of zero or "" indicates that the specified item either does not exist, or it exists and its value is zero or "". If you need to know if an item actually exists, use Registry_Info(). For example: docs$=FNRegistry_RdStr(reg_cu%, \ \ "Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders", \ \ "Personal") will read the pathname that 'My Documents' defaults to. status%=FNRegistry_RdInt(reg_hkcu%, \ \ "Software\Microsoft\Internet Explorer\Toolbar", \ \ "Locked") will find Internet Explorer's toolbar locked setting. DEFFNRegistry_Info(hk%,Key$,Item$) ================================== Registry_Info() examines the registry to see if the specified item exists and what it's entry type is. It returns the entry type, or zero if the entry does not exist. For example: found%=FNRegistry_Info(reg_cu%, \ \ "Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders", \ \ "Personal") DEFPROCRegistry_Del(hk%,Key$,Item$) =================================== Registry_Del() deletes an registry entry. If Item$="", then the whole key and all its values will be deleted. A key must have no subkeys for it to be deleted. For example: PROCRegistry_Del(reg_hkcu%, \ \ "Software\J.G.Harston\MakeImage", \ \ "Startup") deletes the MakeImage startup registry entry. DEFFNRegistry_Vals(hk%,Key$,RETURN index%) DEFFNRegistry_Keys(hk%,Key$,RETURN index%) ========================================== Registry_Vals() and Registry_Keys() scan through the specified registry key returning the names of the values or the subkeys within it. The first call should be made with index% set to zero. It will be updated by each call to the value required to fetch the next entry. When there are no more entries to fetch, the functions return "". Registry entries are not necessarily returned in any particular order. For example: PROCRegistry_Init K$="Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" index%=0 REPEAT item$=FNRegistry_Vals(reg_hkcu%, K$, index%) IF item$<>"" THEN type% =FNRegistry_Info(reg_hkcu%, K$, item$) value$=FNRegistry_Rd( reg_hkcu%, K$, item$) PRINT "Item: ";item$;TAB(22); PRINT "Type: ";type%;TAB(31); PRINT "Size: ";LENvalue$;TAB(41); IF type%=1 OR type%=2:PRINT "Value: ";LEFT$(value$,20);:IFLENvalue$>20:PRINT"..."; PRINT ENDIF UNTIL item$="" END lists all the registry values in the Explorer folders key. Naming consistancy ================== Programs should ensure that the registry keys they use follow a consistant naming structure. This should be 'Software\Publisher\Application', for example: Software\Microsoft\Windows Software\R T Russell\BBC BASIC for Windows Software\J.G.Harston\MakeIndex Software should not normally have any reason to write to locations outside the HK_CURRENT_USER part of the registry. Disclaimer ========== Writing to the registry is potentially dangerous and can leave your system unusable. The Win\Registry library is provided "as-is" and is Copyright (C) J.G.Harston. No responsibility can or will be taken for any loss, damage, etc, whatsoever through its use. The Win\Registry library may be freely used and redistributed in any BBC BASIC for Windows program. Please acknowledge its use in any documentation. The library is based on code in Appendix E of the BBC BASIC for Windows manual and on code in the MSDN Programmers' Reference. References ========== R.T.Russell, Appendix E, BBC BASIC for Windows Manual. MSDN Programmers' Reference. Version History =============== 0.10 18-May-2006 Initial draft based on Reg library. 1.00 12-Aug-2007 Initial release. 1.01 13-Aug-2007 Debugged and tested first release, documentation completed. 1.02 18-Jul-2008 Registry_Rd() always returns string if asked for string.