Функция 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 |
[in] samDesired
Маска, указывающая права доступа для создаваемого ключа. Дополнительные сведения см. в разделе "Безопасность и права доступа реестра".
[in, optional] lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES, которая определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Если lpSecurityAttributesnull, то дескриптор нельзя наследовать.
Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового ключа. Если lpSecurityAttributesNULL, ключ получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для ключа наследуются от прямого родительского ключа.
[out] phkResult
Указатель на переменную, которая получает дескриптор открытого или созданного ключа. Если ключ не является одним из предопределенных разделов реестра, вызовите функцию RegCloseKey
[out, optional] lpdwDisposition
Указатель на переменную, которая получает одно из следующих значений ликвидации.
| Ценность | Значение |
|---|---|
|
Ключ не существовал и был создан. |
|
Ключ существовал и был просто открыт без изменения. |
Если lpdwDispositionNULL, данные о ликвидации не возвращаются.
[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 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winreg.h (включая Windows.h) |
| библиотеки |
Advapi32.lib |
| DLL | Advapi32.dll |
См. также
Обзор реестра