Функция RegCreateKeyTransactedA (winreg.h)
Создает указанный раздел реестра и связывает его с транзакцией. Если ключ уже существует, функция открывает его. Обратите внимание, что в именах ключей регистр не учитывается.
Приложения, которые выполняют резервное копирование или восстановление состояния системы, включая системные файлы и кусты реестра, должны использовать службу теневого копирования томов вместо функций реестра.
Синтаксис
LSTATUS RegCreateKeyTransactedA(
[in] HKEY hKey,
[in] LPCSTR lpSubKey,
DWORD Reserved,
[in, optional] LPSTR lpClass,
[in] DWORD dwOptions,
[in] REGSAM samDesired,
[in, optional] const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[out] PHKEY phkResult,
[out, optional] LPDWORD lpdwDisposition,
[in] HANDLE hTransaction,
PVOID pExtendedParemeter
);
Параметры
[in] hKey
Дескриптор открытого раздела реестра. Вызывающий процесс должен иметь KEY_CREATE_SUB_KEY доступ к ключу. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.
Доступ для создания ключа проверяется по дескриптору безопасности раздела реестра, а не по маске доступа, указанной при получении дескриптора. Таким образом, даже если ключ hKey был открыт с помощью samDesired KEY_READ, его можно использовать в операциях, создающих ключи, если это разрешено дескриптором безопасности.
Этот дескриптор возвращается функцией RegCreateKeyTransacted или RegOpenKeyTransacted или может быть одним из следующих предопределенных ключей:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_USERS
[in] lpSubKey
Имя подраздела, открываемого или создаваемого этой функцией. Указанный подраздел должен быть подразделом ключа, определяемого параметром hKey ; В дереве реестра может быть до 32 уровней. Дополнительные сведения об именах ключей см. в разделе Структура реестра.
Если lpSubKey является указателем на пустую строку, phkResult получает новый дескриптор ключа, указанного в hKey.
Этот параметр не может иметь значение NULL.
Reserved
Этот параметр зарезервирован и должен быть равен нулю.
[in, optional] lpClass
Пользовательский класс этого ключа. Этот параметр можно игнорировать. Этот параметр может принимать значение NULL.
[in] dwOptions
Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Если этот флаг установлен, функция игнорирует параметр samDesired и пытается открыть ключ с доступом, необходимым для резервного копирования или восстановления ключа. Если для вызывающего потока включено разрешение SE_BACKUP_NAME, ключ открывается с ACCESS_SYSTEM_SECURITY и KEY_READ права доступа. Если в вызывающем потоке включена привилегия SE_RESTORE_NAME, ключ открывается с ACCESS_SYSTEM_SECURITY и KEY_WRITE права доступа. Если включены обе привилегии, ключ имеет объединенные права доступа для обоих привилегий. Дополнительные сведения см. в разделе Выполнение с особыми привилегиями. |
|
Этот ключ не является переменным; это значение по умолчанию. Эти сведения хранятся в файле и сохраняются при перезапуске системы. Функция RegSaveKey сохраняет ключи, которые не являются переменными. |
|
Все ключи, созданные функцией, являются переменными. Информация хранится в памяти и не сохраняется при выгрузке соответствующего куста реестра. Для HKEY_LOCAL_MACHINE это происходит при завершении работы системы. Для разделов реестра, загруженных функцией RegLoadKey , это происходит при выполнении соответствующего regUnLoadKey . Функция RegSaveKey не сохраняет переменные ключи. Этот флаг игнорируется для уже существующих ключей. |
[in] samDesired
Маска, указывающая права доступа для создаваемого ключа. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.
[in, optional] lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращенный дескриптор наследоваться дочерними процессами. Если lpSecurityAttributes имеет значение NULL, дескриптор не может быть унаследован.
Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового ключа. Если lpSecurityAttributes имеет значение NULL, ключ получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для ключа наследуются от его прямого родительского ключа.
[out] phkResult
Указатель на переменную, которая получает дескриптор открытого или созданного ключа. Если раздел не является одним из предопределенных разделов реестра, вызовите функцию RegCloseKey после завершения использования дескриптора.
[out, optional] lpdwDisposition
Указатель на переменную, которая получает одно из следующих значений перед ликвидацией.
| Значение | Значение |
|---|---|
|
Ключ не существует и был создан. |
|
Ключ существовал и был просто открыт без изменения. |
Если lpdwDisposition имеет значение NULL, сведения о ликвидации не возвращаются.
[in] hTransaction
Дескриптор активной транзакции. Этот дескриптор возвращается функцией CreateTransaction .
pExtendedParemeter
Этот параметр зарезервирован и должен иметь значение NULL.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение представляет собой ненулевой код ошибки, определенный в Winerror.h. Чтобы получить общее описание ошибки, можно использовать функцию FormatMessage с флагом FORMAT_MESSAGE_FROM_SYSTEM.
Комментарии
При создании ключа с помощью этой функции выполняются последующие операции с ключом. Если операция без транзакций выполняется с ключом до фиксации транзакции, выполняется откат транзакции. После фиксации или отката транзакции необходимо повторно открыть ключ с помощью RegCreateKeyTransacted или RegOpenKeyTransacted с активным дескриптором транзакции, чтобы выполнить дополнительные операции. Дополнительные сведения о транзакциях см. в разделе Диспетчер транзакций ядра.
Обратите внимание, что последующие операции с подразделами этого ключа не выполняются автоматически. Таким образом, RegDeleteKeyEx не выполняет транзакцию удаления. Вместо этого используйте функцию RegDeleteKeyTransacted для выполнения транзакции операции удаления.
Ключ, создаваемый функцией RegCreateKeyTransacted , не имеет значений. Приложение может использовать функцию RegSetValueEx для задания значений ключа.
Функция RegCreateKeyTransacted создает все отсутствующие ключи по указанному пути. Приложение может воспользоваться этим поведением для создания нескольких ключей одновременно. Например, приложение может создать подраздел с четырьмя уровнями глубины одновременно с тремя предыдущими подразделами, указав строку следующей формы для параметра lpSubKey :
subkey1\subkey2\subkey3\subkey4
Обратите внимание, что такое поведение приведет к созданию нежелательных ключей, если существующий ключ в пути написан неправильно.
Приложение не может создать ключ, который является прямым дочерним элементом HKEY_USERS или HKEY_LOCAL_MACHINE. Приложение может создавать подразделы на более низких уровнях HKEY_USERS или HKEY_LOCAL_MACHINE деревьев.
Примечание
Заголовок winreg.h определяет RegCreateKeyTransacted в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows Vista [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winreg.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |