The features which have been added to this version of Perl include support for the Registry, Event Logging, and OLE. Because of its size, OLE has been split off into a page of its own.
EventLog
The following Eventlog functions are closely mapped to the Win32 API,
for more in-depth explanations please consult the Win32 API
Documentation.
FLAGS is a bit flag that may be any combination of EVENTLOG_FORWARDS_READ, EVENTLOG_BACKWARDS_READ, EVENTLOG_SEQUENTIAL_READ, EVENTLOG_SEEK_READ. If performing a seek read, REC specifies the index of the record to retrieve (counting from 1, not 0.)
The Event Record header EVTHEADER binary structure can be unpacked to provide information about the Event Log Record in the following way:
( $length, $reserved, $recordnumber, $timegenerated, $timewritten, $eventid, $eventtype, $numstrings, $eventcategory, $reservedflags, $closingrecordnumber, $stringoffset, $usersidlength, $usersidoffset, $datalength, $dataoffset ) = unpack( 'l6s4l6', $header );
SOURCE, stores the name of the application which generated the event record. COMPUTER specifies the UNC name of the machine which generated the event record.
SID stores a security identifier structure. For more information regarding security descriptors, consult the Win32 API Documentation.
An array of message strings is returned in STRINGS in the form of a single string, delimited by null characters.
DATA holds any binary information associated with the returned Event Record.
EVENTTYPE may have any one of the values EVENTLOG_ERROR_TYPE, EVENTLOG_WARNING_TYPE or EVENTLOG_INFORMATION_TYPE.
CATEGORY specifies the event category, and is entirely determined by the calling application, as is EVENTID.
The RESERVED value must be NULL.
DATA contains any binary data that is to be associated with the event log record.
@STRINGS is an array of strings (scalars) that is to be supplied as the message for the eventlog.
Material provided within this document has been shamelessly plagiaried from the Microsoft Win32 Programmer's Reference, Volume 2, Chapter 32. Please consult the aforementioned source for complete and accurate information regarding the Windows NT Registry.
Because information stored in the registry controls almost every aspect of the system, we stronly advise against the novice Perl hacker playing around with the registry. It is extremely easy to damage Windows NT to the point that it is completely unbootable. Modifying the registry is not a task to be undertaken by the faint of heart.
You have been warned! :-).
We do not currently support the use of Unicode characters under NT Perl. The following functions all map to the ANSI Win32 API routines, not Unicode. Consequently, any and all Unicode strings passed as arguments (either supplied or returned) will be converted to ANSI 8-bit strings.
The following functions are implemented:
The RegCloseKey function releases the given key handle HKEY.
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.
Establishes a connection to a predefined registry handle HKEY on another computer COMPUTERNAME, storing the opened handle in PHKRESULT.
If COMPUTERNAME is NULL, the local computer name is used. Currently, the values HKEY_LOCAL_MACHINE and HKEY_USERS may be supplied for HKEY, an application cannot specify the HKEY_CLASSES_ROOT or HKEY_CURRENT_USER value for this parameter (they don't make sense on a remote computer).
Remarks
When a handle returned by RegConnectRegistry is no longer needed, it should be closed by calling RegCloseKey.
Creates the key named SUBKEY under the open key handle HKEY, and stores the opened handle for the new key in PHKRESULT. If the key already exists in the registry, the function opens it. This function is provided for compatibility with Windows 3.1. New applications should use the RegCreateKeyEx function.
HKEY identifies a currently open key or one of the predefined reserved handle values HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE and HKEY_USERS. The key opened or created by this function is a subkey of the key identified by HKEY.
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 lpszSubKey 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).
Creates the key named SUBKEY under the open key handle HKEY, storing the handle of the newly opened key in PHKRESULT. If the key already exists in the registry, the function opens it.
A NULL must be supplied for the RESERVED argument.
The CLASS string specifies the class (object-type) for the key.
A key can be created with one of two OPTIONS, REG_OPTION_VOLATILE and REG_OPTION_NON_VOLATILE. Volatile keys are stored in memory and are not preserved in between Windows NT sessions. Non-volatile keys are saved to disk and preserved when the system is restarted.
The SAM specifies the access mode in which the key is to be created. For a list of valid access modes, consult the file "NT.ph" in the Perl library.
SECURITY holds a security descriptor structure that defines security settings for the created key. Discussion of security issues is beyond the scope of this document, please consult the Win32 API documentation for information. Simply supplying a NULL value will direct Perl to supply the default security settings for key creation.
Remarks
The key that the RegCreateKeyEx function creates has no values. An application can use the RegSetValue or RegSetValueEx function to set key values.
The key identified by the hkey parameter must have been opened with KEY_CREATE_SUB_KEY access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.
An application cannot create a key under HKEY_USERS or HKEY_LOCAL_MACHINE.
An application can use RegCreateKeyEx to temporarily lock a portion of the registry. When the locking process creates a new key, it receives the disposition value REG_CREATED_NEW_KEY, indicating that it "owns" the lock. Another process attempting to create the same key receives the disposition value REG_OPENED_EXISTING_KEY, indicating that another process already owns the lock.
The RegDeleteKey function deletes the named SUBKEY under the HKEY. This function cannot delete a key that has subkeys. SUBKEY must be a subkey of the key identified by HKEY.
Remarks
If the function succeeds, RegDeleteKey removes the specified key from the registration database. The entire key, including all of its values, is removed.
To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. Do not use the RegCreateKey or RegOpenKey functions
Removes the named VALUE from the open registry key HKEY. If VALUE is NULL or empty, the value set by the RegSetValue function is removed.
Remarks
The key identified by the hkey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).
The RegEnumKey function enumerates subkeys of the specified open registry key HKEY, returning the name of the subkey indexed by ISUBKEY in SUBKEYNAME. The function retrieves the name of one subkey each time it is called. This function is provided for compatibility with Windows version 3.1. New Win32-based applications should use the RegEnumKeyEx function.
Because subkeys are not ordered, any new subkey will have an arbitrary index, meaning that this function may return subkeys in any order.
Remarks
To enumerate subkeys, an application should initially call the RegEnumKey function with the iSubKey parameter set to zero. The application should then increment the iSubKey parameter and call the RegEnumKey function until there are no more subkeys (until the function returns an error).
The application can also set iSubKey to the index of the last key on the first call to the function and decrement the index until the subkey with index 0 is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey.
While an application is using the RegEnumKey function, it should not make calls to any registration functions that might change the key being queried.
The key identitied by the hkey parameter must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ access includes KEY_ENUMERATE_SUB_KEYS access). To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.
The RegEnumKeyEx function enumerates subkeys of the open key HKEY, returning the SUBKEYNAME, CLASS and time of LASTWRITE for the key indexed by ISUBKEY. The function retrieves information about one subkey each time it is called. Unlike the RegEnumKey function, RegEnumKeyEx retrieves the class name of the subkey and the time it was last modified. A NULL must be supplied for the RESERVED parameter.
Remarks
To enumerate subkeys, an application should initially call the RegEnumKeyEx function with the iSubKey parameter set to zero. The application should then increment the iSubKey parameter and call RegEnumKeyEx until there are no more subkeys (until the function returns an error).
The application can also set iSubKey to the index of the last subkey on the first call to the function and decrement the index until the subkey with the index 0 is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey function.
While an application is using the RegEnumKeyEx function, it should not make calls to any registration functions that might change the key being enumerated.
The key identified by hkey must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ includes KEY_ENUMERATE_SUB_KEYS). Use the RegCreateKeyEx or RegOpenKeyEx function to open the key.
The RegEnumValue function enumerates the values for the key specified by HKEY. The function copies one value NAME and DATA block as well as the data TYPE for the key indexed by IVALUE. A NULL must be supplied for the RESERVED paramter.
For a list of valid data types, please consult the file "NT.ph" in the Perl library.
Remarks
To enumerate values, an application should initially call the RegEnumValue function with the iValue parameter set to zero. The application should then increment iValue and call the RegEnumValue function until there are no more values (until the function returns an error).
The application can also set iValue 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 ReqQueryInfoKey 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.
The RegFlushKey function writes all the attributes of the open key HKEY into the registry.
Remarks
It is not necessary to call RegFlushKey to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are also flushed to disk at system shutdown.
Unlike RegCloseKey, the RegFlushKey function returns only when all the data has been written to the registry.
The RegFlushKey function may also write out parts of or all of the other keys. Calling this function excessively can have a negative effect on an application's performance.
An application should only call RegFlushKey if it requires absolute certainty that registry changes are on disk. If you don't know whether a RegFlushKey call is required, it probably isn't.
Retreives a copy of the security descriptor protecting the open registry key HKEY. The requested security information is specified in SECURITY_INFORMATION, and the returned descriptor is stored in SECURITY_DESCRIPTOR.
Discussion of security issues is beyond the scope of this document, please consult the Win32 API documentation for more information about security descriptors, security modes, etc.
Remarks
To read the security descriptor for the specified key, the calling process must have been granted READ_CONTROL access when the key was opened, or it must be the owner of the key. (READ_CONTROL access is granted by the KEY_READ, KEY_WRITE, KEY_EXECUTE, and KEY_ALL_ACCESS access rights.) In addition, the caller must have the SE_SECURITY_NAME privilege to read the system access-control list (SACL).
The RegLoadKey function creates a subkey under HKEY_USER or HKEY_LOCAL_MACHINE and stores registration information from a specified FILE into that SUBKEY. This registration information is in the form of a hive. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy. A hive is backed by a single file and .LOG file. Under the FAT file system, the filename the hive is stored under may not have an extension.
Remarks
A call to RegLoadKey fails if the calling process does not have the SE_RESTORE_PRIVILEGE privilege.
If hkey is a handle returned by RegConnectRegistry, then the path specified in lpszFile is relative to the remote computer.
The RegOpenKey function opens the SUBKEYNAME under key HKEY, returning the handle of the opened key in PHKRESULT. This function is provided for compatibility with Windows version 3.1. New Win32-based applications should use the RegOpenKeyEx function.
Remarks
The RegOpenKey function uses the default security access mask to open a key. If opening the key requires a different mask, the function fails, returning ERROR_ACCESS_DENIED. An application should use the RegOpenKeyEx function to specify an access mask in this situation. Unlike the RegCreateKey function, RegOpenKey does not create the specified key if the key does not exist in the database.
The RegOpenKeyEx function opens SUBKEYNAME under HKEY with access mode SAM, returning the handle of the opened key in PHKRESULT.
Remarks
Unlike the RegCreateKeyEx function, the RegOpenKeyEx function does not create the specified key if the key does not exist in the registry.
The RegQueryInfoKey function retrieves information about a
specified registry key HKEY, including:
Remarks
A NULL must be supplied for the RESERVED argument.
The key identified by the hkey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).
The RegQueryValue function retrieves the value associated with the unnamed value for a specified key SUBKEYNAME under the key HKEY in the registry. Values in the Windows NT registry have name, type, and data components. This function retrieves the data for a key's first value that has a NULL name, and places the result in the DATA block. This function is provided for compatibility with Windows version 3.1. New Win32-based applications should use the RegQueryValueEx function.
Remarks
The key identified by the hkey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).
If the ANSI version of this function is used (either by explicitly calling RegQueryValue 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 specified by the lpszValue parameter.
The RegQueryValueEx function retrieves the TYPE and DATA for a specified VALUENAME associated with the open registry key HKEY.
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 RegQueryValueEx 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 lpbData.
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.
The RegReplaceKey function replaces the file backing a key and all its subkeys with another file, so that when the system is next started, the key and subkeys will have the values stored in the new file.
Remarks
The file specified by the lpszNewFile parameter remains open until the system is restarted.
A process must have the SE_RESTORE_NAME privilege to call this function.
If hkey is a handle returned by RegConnectRegistry, then the paths specified in lpszNewFile and lpszBackupFile are relative to the remote computer.
The RegRestoreKey function reads the registry information in a specified file and copies it over the specified key. This registry information may be in the form of a key and multiple levels of subkeys.
Remarks
If the calling process does not have the SE_RESTORE_NAME privilege or if any subkeys of the hkey parameter are open, ReqRestoreKey fails.
This function replaces the keys and values below the specified key with the keys and values that are subsidiary to the top-level key in the file, no matter what the name of the top-level key in the file might be. For example, hkey might identify a key A with subkeys B and C, while the lpszFile parameter specifies a file containing key X with subkeys Y and Z. After a call to RegRestoreKey, the registry would contain key A with subkeys Y and Z. The value entries of A would be replaced by the value entries of X.
The new information in the file specified by lpszFile overwrites the contents of the key specified by the hKey parameter, except for the key name.
If hkey represents a key in a remote computer, the path described by lpszFile is relative to the remote computer.
The RegSaveKey function saves the specified key HKEY and all of its subkeys and values to a new file called FILENAME, with security settings specified by SECURITY_ATTRIBUTES.
Remarks
If hkey represents a key on a remote computer, the path described by lpszFile is relative to the remote computer.
The caller of this function must possess the SeBackupPrivilege security privilege.
The RegSaveKey function saves only non-volatile keys. It does not save volatile keys. A key is made volatile or non-volatile at its creation; see RegCreateKeyEx.
The RegSetKeySecurity function sets the security of an open registry key.
Remarks
This function succeeds only if the following conditions are met:
* If the key's owner or group is being set, the caller must have WRITE_OWNER permission or have the SE_TAKE_OWNERSHIP_NAME privilege.
* If the key's discretionary access-control list (DACL) is being set, the caller must have WRITE_DAC permission or be the object's owner.
* If the key's system access-control list (SACL) is being set, the caller must have the SE_SECURITY_NAME privilege.
If hkey is one of the predefined keys, the predefined key should be closed with RegCloseKey. That ensures that the new security information is in effect the next time the predefined key is referenced.
The RegSetValue function associates a value with SUBKEYNAME under key HKEY. This value must be of type REG_SZ and cannot have a name. This function is provided for compatibility with Windows version 3.1. New Win32-based applications should use the RegSetValue Ex function, which allows an application to set any number of named values of any data type.
Remarks
If the key specified by the lpszSubKey parameter does not exist, the RegSetValue function creates it.
Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the configuration registry. This helps the registry perform efficiently.
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 the ANSI version of this function is used (either by explicitly calling RegSetValue or by not defining Unicode before including the WINDOWS.H file), the lpszData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.
The RegSetValueEx function stores VALUENAME - DATA pair with data type TYPE in the value field of an open registry key specified by HKEY.
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 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 TYPE 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 RegSetValueEx or by not defining Unicode before including the WINDOWS.H file), the data pointed to by the lpbData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.
Unloads the key and its children specified by SUBKEYNAME under HKEY from the registry.
Remarks
This function removes a hive from the registry but does not modify the file containing the registry information. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy.