ZurückInhaltWeiter


2. Die Registry API

Mit der Magic Funktion "Call UDP" können Windows API Funktionen aufgerufen werden. Um die Registry zu bearbeiten werden fünf Funktionen benötigt:

2.1 Der Schlüssel zur Registry

Die Basis der Registry wird über einen Schlüssel &H80000000 adressiert. Für ein Magic Longinteger ist dies der größte negative Wert :-2147483648.
Die einzelnen Sektionen haben einen festgelegten Offset, der auf den Basisschlüssel addiert wird:
 
Bedeutung Hexadezimal Magic
+0 HKEY_CLASSES_ROOT &H80000000 -2147483648
+1 HKEY_CURRENT_USER &H80000001 -2147483647
+2 HKEY_LOCAL_MACHINE &H80000002 -2147483646
+3 HKEY_USERS &H80000003 -2147483645
+4 HKEY_PERFORMANCE_DATA (nur WinNT) &H80000004 -2147483644
+5 HKEY_CURRENT_CONFIG &H80000005 -2147483643
+6 HKEY_DYN_DATA (nur Win95) &H80000006 -2147483642

2.2 Magic & Registry API

Für das einfache Lesen und Schreiben der Registry werden zwei Magic Programme benötigt. In Anlehnung an die Magic Ini Funktionen heißen sie:
  • GetReg
  • PutReg
Um einen Wert in der Registry zulesen oder zuschreiben, benötig man einen der Basis Schlüssel und einen Schlüsselnamen. Damit wird die Registry geöffnet. Beim Öffnen wird auch eine Berechtigung mit übergeben, mit der gesteuert wird, welcher Benutzer diesen Schlüssel anlegen darf (Bei Win95/98 wird das nicht ausgewertet, darum kann es böse Überraschungen geben, wenn das Programm später unter WinNT eingesetzt wird).

2.2.1 Programm Parameter

 
Parameter Name Attribute Picture Range
A p.HKey N 1 0 HKEY_CLASSES_ROOT
1 HKEY_CURRENT_USER
2 HKEY_LOCAL_MACHINE
3 HKEY_USERS
4 HKEY_PERFORMANCE_DATA (nur WinNT)
5 HKEY_CURRENT_CONFIG
6 HKEY_DYN_DATA (nur Win95)
B p.SubKeyName A 255  
C p.ValueName A 255  
D p.Value A 255  
E p.Result N N10  
F v.OpenKeyHandle N N10  
G v.KeyValueType N N10  

2.2.2 GetReg

Um einen Wert aus der Registry zulesen, benötig man einen der Basis Schlüssel, einen Schlüsselnamen und . Damit wird die Registry geöffnet. Das Ergebnis ist ein Handle auf den Schlüssel oder ein Ergebnis <>0, das dieser Schlüssel nicht existiert.
Zusammen mit dem Wertenamen kann dann der Wert gelesen werden.
Als Letztes muß der Handle wieder frei gegeben werden.

2.2.3 PutReg

Um einen Wert in die Registry zuschreiben, benötig man einen der Basis Schlüssel und einen Schlüsselnamen. Damit wird die Registry geöffnet. Das Ergebnis ist ein Handle auf den Schlüssel oder ein Ergebnis <>0. In diesem Fall muß der Schlüssel angelegt werden. Wird ein Schlüssel anlegt, bekommt man einen Handle auf den neuen Schlüssel.
Zusammen mit dem Wertenamen kann dann der Wert geschrieben werden.
Als Letztes muß der Handle wieder frei gegeben werden.

2.3 Magic Registry API Aufrufe

    Windows API Magic UDP Aufruf
  @advapi32.RegOpenKeyExA
    "RegOpenKeyExA" (
ByVal hKey As Long, 
ByVal lpSubKey As String, 
ByVal ulOptions As Long, 
ByVal samDesired As Long, 
phkResult As Long
) As Long
'4A44L4'
Einer der Basis Schlüssel
Names des Schlüssels
immer Null
Zugriffsrechte &HF003F
Der Handel des geöffneten Schlüssels
Error Code
  '@advapi32.RegCloseKey'
    "RegCloseKey" (
ByVal hKey As Long
) As Long
'44'
Der Handel des zuschließenden Schlüssels
Error Code
  '@advapi32.RegCreateKeyA'  
    "RegCreateKeyA" (
ByVal hKey As Long, 
ByVal lpSubKey As String, 
phkResult As Long
) As Long
'4AL4'
Einer der Basis Schlüssel
Names des Schlüssels
Der Handel des erstellten Schlüssels
Error Code
  '@advapi32.RegQueryValueExA'
    "RegQueryValueExA" (
ByVal hKey As Long, 
ByVal lpValueName As String, 
ByVal lpReserved As Long, 
lpType As Long, 
lpData As Any, 
lpcbData As Long
) As Long 
'4A4LAL4'
Der Handel eines geöffneten Schlüssels
Names des Wertes
immer 0
Typ des Wertes (Return)
Daten
Anzahl Bytes ( LEN(lpData) )
Error Code
  '@advapi32.RegSetValueExA'
    "RegSetValueExA" (
ByVal hKey As Long, 
ByVal lpValueName As String, 
ByVal Reserved As Long, 
ByVal dwType As Long, 
lpData As Any, 
ByVal cbData As Long
) As Long 
'4A44A44'
Der Handel eines geöffneten Schlüssels
Names des Wertes
immer 0
Typ des Wertes (1 = Alpha)
Daten
Anzahl Bytes ( LEN(lpData) )
Error Code

2.4 Registry API Beschreibung

  RegOpenKeyExA  
    The RegOpenKeyEx function opens the specified key. 
LONG RegOpenKeyEx( 
HKEY hKey, // handle of open key
LPCTSTR lpSubKey, // address of name of subkey to open
DWORD ulOptions, // reserved
REGSAM samDesired, // security access mask
PHKEY phkResult // address of handle of open key
);
Parameters
hKey
Identifies a currently open key or any of the following predefined reserved handle values. 
lpSubKey
Points to a null-terminated string containing the name of the subkey to open. If this parameter is NULL or a pointer to an empty string, the function will open a new handle of the key identified by the hKey parameter. In this case, the function will not close the handles previously opened.
ulOptions
Reserved; must be zero. 
samDesired
Specifies an access mask that describes the desired security access for the new key. This parameter can be a combination of the following values: 
Value Meaning 
KEY_ALL_ACCESS
KEY_CREATE_LINK Permission to create a symbolic link. 
KEY_CREATE_SUB_KEY Permission to create subkeys. 
KEY_ENUMERATE_SUB_KEYS Permission to enumerate subkeys. 
KEY_EXECUTE Permission for read access. 
KEY_NOTIFY Permission for change notification. 
KEY_QUERY_VALUE Permission to query subkey data. 
KEY_READ
KEY_SET_VALUE Permission to set subkey data. 
KEY_WRITE
phkResult
Points to a variable that receives the handle of the opened key. When you no longer need the returned handle, call the RegCloseKey function to close it. 
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
Remarks
Unlike the RegCreateKeyEx function, the RegOpenKeyEx function does not create the specified key if the key does not exist in the registry. 
QuickInfo
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Windows CE: Use version 1.0 and later.
Header: Declared in winreg.h.
Import Library: Link with advapi32.lib.
  RegCloseKey  
    The RegCloseKey function releases the handle of the specified key. 
LONG RegCloseKey( HKEY hKey // handle of key to close);
Parameters
hKey 
Identifies the open key to close. 
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
Remarks
The handle for a specified key should not be used after it has been closed, because it will no longer be valid. Key handles should not be left open any longer than necessary. 
The RegCloseKey function does not necessarily write information to the registry before returning; it can take as much as several seconds for the cache to be flushed to the hard disk. If an application must explicitly write registry information to the hard disk, it can use the RegFlushKey function. RegFlushKey, however, uses many system resources and should be called only when necessary. 
Windows CE: The RegCloseKey function always writes information to the registry before returning, eliminating the need to flush keys in the Windows CE registry. 
QuickInfo
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Windows CE: Use version 1.0 and later.
Header: Declared in winreg.h.
Import Library: Link with advapi32.lib.
  RegCreateKeyA  
    The RegCreateKey function creates the specified key. If the key already exists in the registry, the function opens it. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegCreateKeyEx function. 
LONG RegCreateKey( 
HKEY hKey, / handle of an open key
LPCTSTR lpSubKey, / address of name of subkey to open
PHKEY phkResult / address of buffer for opened handle
);
Parameters
hKey
Identifies a currently open key or one of the predefined reserved handle values.
The key opened or created by the RegCreateKey function is a subkey of the key identified by hKey.
lpSubKey
Points to a null-terminated string specifying the name of a key that this function opens or creates. This key must be a subkey of the key identified by the hKey parameter. 
If hKey is one of the predefined keys, lpSubKey may be NULL. In that case, the handle returned by using phkResult is the same hKey handle passed in to the function. 
phkResult
Points to a variable that receives the handle of the opened or created key. When you no longer need the returned handle, call the RegCloseKey function to close it. 
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
Remarks
An application can use the RegCreateKey function to create several keys at once. For example, an application can create a subkey four levels deep at the same time as the three preceding subkeys by specifying a string of the following form for the lpSubKey parameter: 
subkey1\subkey2\subkey3\subkey4 
The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access (KEY_WRITE access includes KEY_CREATE_SUB_KEY access). 
If the lpSubKey parameter is the address of an empty string, the function opens and then passes back the key identified by the hKey parameter. 
QuickInfo
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Windows CE: Unsupported.
Header: Declared in winreg.h.
Import Library: Link with advapi32.lib.
  RegQueryValueExA  
    The RegQueryValueEx function retrieves the type and data for a specified value name associated with an open registry key. 
LONG RegQueryValueEx( 
HKEY hKey, // handle of key to query
LPTSTR lpValueName, // address of name of value to query
LPDWORD lpReserved, // reserved
LPDWORD lpType, // address of buffer for value type
LPBYTE lpData, // address of data buffer
LPDWORD lpcbData // address of data buffer size
);
Parameters
hKey
Identifies a currently open key or any of the following predefined reserved handle values. 
lpValueName
Points to a null-terminated string containing the name of the value to be queried. 
lpReserved
Reserved; must be NULL. 
LpType
Points to a variable that receives the key's value type. 
lpData
Points to a buffer that receives the value's data. This parameter can be NULL if the data is not required. 
lpcbData
Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, this variable contains the size of the data copied to lpData. 
If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then lpcbData will also include the size of the terminating null character. 
The lpcbData parameter can be NULL only if lpData is NULL.
If the buffer specified by lpData parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbData. 
If lpData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData. This lets an application determine the best way to allocate a buffer for the value's data. 
Window NT: If hKey specifies HKEY_PERFORMANCE_DATA and the lpData buffer is too small, RegQueryValueEx returns ERROR_MORE_DATA but lpcbData does not return the required buffer size. This is because the size of the performance data can change from one call to the next. In this case, you must increase the buffer size and call RegQueryValueEx again passing the updated buffer size in the lpcbData parameter. Repeat this until the function succeeds. You need to maintain a separate variable to keep track of the buffer size, because the value returned by lpcbData is unpredictable. 


Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
Remarks
The key identified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. 
This function does not expand the environment-variable names in the value data when the value type is REG_EXPAND_SZ. The ExpandEnvironmentStrings function can be used to expand the environment-variable names. 
If the value data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, and the ANSI version of this function is used (either by explicitly calling RegQueryValueExA or by not defining UNICODE before including the WINDOWS.H file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer pointed to by lpData. 
Window NT: When calling the RegQueryValueEx function with hKey set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified object, the returned data structure sometimes has unrequested objects. Don't be surprised; this is normal behavior. When calling the RegQueryValueEx function, you should always expect to walk the returned data structure to look for the requested object.
QuickInfo
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Windows CE: Use version 1.0 and later.
Header: Declared in winreg.h.
Import Library: Link with advapi32.lib.
  RegEnumValueA  
    The RegEnumValue function enumerates the values for the specified open registry key. The function copies one indexed value name and data block for the key each time it is called. 
LONG RegEnumValue( 
HKEY hKey, // handle of key to query
DWORD dwIndex, // index of value to query
LPTSTR lpValueName, // address of buffer for value string
LPDWORD lpcbValueName, // address for size of value buffer
LPDWORD lpReserved, // reserved
LPDWORD lpType, // address of buffer for type code
LPBYTE lpData, // address of buffer for value data
LPDWORD lpcbData // address for size of data buffer
);
Parameters
hKey
Identifies a currently open key or any of the following predefined reserved handle values. 
dwIndex
Specifies the index of the value to retrieve. This parameter should be zero for the first call to the RegEnumValue function and then be incremented for subsequent calls. 
Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order. 
lpValueName
Points to a buffer that receives the name of the value, including the terminating null character. 
lpcbValueName
Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcbValueName contains the number of characters stored in the buffer. The count returned does not include the terminating null character. 
lpReserved
Reserved; must be NULL. 
LpType
Points to a variable that receives the type code for the value entry. The type code can be one of the following values.
lpData
Points to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required. 
lpcbData
Points to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if lpData is NULL. 
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
Remarks
To enumerate values, an application should initially call the RegEnumValue function with the dwIndex parameter set to zero. The application should then increment dwIndex and call the RegEnumValue function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS). 
The application can also set dwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0 is enumerated. To retrieve the index of the last value, use the RegQueryInfoKey function. 
While using RegEnumValue, an application should not call any registration functions that might change the key being queried. 
The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. 
To determine the maximum size of the name and data buffers, use the RegQueryInfoKey function. 
QuickInfo
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Windows CE: Use version 1.0 and later.
Header: Declared in winreg.h.
Import Library: Link with advapi32.lib.
  RegSetValueExA  
    The RegSetValueEx function stores data in the value field of an open registry key. It can also set additional value and type information for the specified key. 
LONG RegSetValueEx( 
KEY hKey, // handle of key to set value for
PCTSTR lpValueName, // address of value to set
DWORD Reserved, // reserved
DWORD dwType, // flag for value type
CONST BYTE *lpData, // address of value data
DWORD cbData // size of value data
);
Parameters
hKey
Identifies a currently open key or any of the following predefined reserved handle values. 
lpValueName
Points to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key. 
If this parameter is NULL or points to an empty string and the dwType parameter is the REG_SZ type, this function sets the same value the RegSetValue function would set. 


Reserved
Reserved; must be zero. 
dwType
Specifies the type of information to be stored as the value's data. 
lpData
Points to a buffer containing the data to be stored with the specified value name. 
cbData
Specifies the size, in bytes, of the information pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating null character. 
Return Values
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
Remarks
Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry. 
The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. 
If dwType is the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type and the ANSI version of this function is used (either by explicitly calling RegSetValueExA or by not defining UNICODE before including the WINDOWS.H file), the data pointed to by the lpData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry. 
QuickInfo
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Windows CE: Use version 1.0 and later.
Header: Declared in winreg.h.
Import Library: Link with advapi32.lib.

2.5 Zugriffstypen

The following are masks for the predefined standard access types  
  DELETE (0x00010000L) 
  READ_CONTROL (0x00020000L)  
  WRITE_DAC (0x00040000L)  
  WRITE_OWNER (0x00080000L)  
  SYNCHRONIZE (0x00100000L)  
  STANDARD_RIGHTS_REQUIRED (0x000F0000L)  
  STANDARD_RIGHTS_READ (READ_CONTROL)  
  STANDARD_RIGHTS_WRITE (READ_CONTROL)  
  STANDARD_RIGHTS_EXECUTE (READ_CONTROL)  
  STANDARD_RIGHTS_ALL (0x001F0000L)  
  SPECIFIC_RIGHTS_ALL (0x0000FFFFL)  
Registry Specific Access Rights.  
  KEY_QUERY_VALUE (0x0001)  
  KEY_SET_VALUE (0x0002)  
  KEY_CREATE_SUB_KEY (0x0004)  
  KEY_ENUMERATE_SUB_KEYS (0x0008)  
  KEY_NOTIFY (0x0010)  
  KEY_CREATE_LINK (0x0020)  
  KEY_READ ((STANDARD_RIGHTS_READ       |\
   KEY_QUERY_VALUE            |\
   KEY_ENUMERATE_SUB_KEYS     |\
   KEY_NOTIFY)                 \
   &                           \
   (~SYNCHRONIZE))
 
  KEY_WRITE ((STANDARD_RIGHTS_WRITE      |\
   KEY_SET_VALUE              |\
   KEY_CREATE_SUB_KEY)         \
   &                           \
   (~SYNCHRONIZE))
 
  KEY_EXECUTE ((KEY_READ)                   \
   &                           \
   (~SYNCHRONIZE))
 
  KEY_ALL_ACCESS ((STANDARD_RIGHTS_ALL        |\
   KEY_QUERY_VALUE            |\
   KEY_SET_VALUE              |\
   KEY_CREATE_SUB_KEY         |\
   KEY_ENUMERATE_SUB_KEYS     |\
   KEY_NOTIFY                 |\
   KEY_CREATE_LINK)            \
   &                           \
   (~SYNCHRONIZE))
 


ZurückInhaltWeiter