Функция 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

Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
REG_OPTION_BACKUP_RESTORE
0x00000004L
Если этот флаг установлен, функция игнорирует параметр samDesired и пытается открыть ключ с доступом, необходимым для резервного копирования или восстановления ключа. Если для вызывающего потока включено разрешение SE_BACKUP_NAME, ключ открывается с ACCESS_SYSTEM_SECURITY и KEY_READ права доступа. Если в вызывающем потоке включена привилегия SE_RESTORE_NAME, ключ открывается с ACCESS_SYSTEM_SECURITY и KEY_WRITE права доступа. Если включены обе привилегии, ключ имеет объединенные права доступа для обоих привилегий. Дополнительные сведения см. в разделе Выполнение с особыми привилегиями.
REG_OPTION_NON_VOLATILE
0x00000000L
Этот ключ не является переменным; это значение по умолчанию. Эти сведения хранятся в файле и сохраняются при перезапуске системы. Функция RegSaveKey сохраняет ключи, которые не являются переменными.
REG_OPTION_VOLATILE
0x00000001L
Все ключи, созданные функцией, являются переменными. Информация хранится в памяти и не сохраняется при выгрузке соответствующего куста реестра. Для HKEY_LOCAL_MACHINE это происходит при завершении работы системы. Для разделов реестра, загруженных функцией RegLoadKey , это происходит при выполнении соответствующего regUnLoadKey . Функция RegSaveKey не сохраняет переменные ключи. Этот флаг игнорируется для уже существующих ключей.

[in] samDesired

Маска, указывающая права доступа для создаваемого ключа. Дополнительные сведения см. в разделе Безопасность раздела реестра и права доступа.

[in, optional] lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , которая определяет, может ли возвращенный дескриптор наследоваться дочерними процессами. Если lpSecurityAttributes имеет значение NULL, дескриптор не может быть унаследован.

Элемент lpSecurityDescriptor структуры задает дескриптор безопасности для нового ключа. Если lpSecurityAttributes имеет значение NULL, ключ получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для ключа наследуются от его прямого родительского ключа.

[out] phkResult

Указатель на переменную, которая получает дескриптор открытого или созданного ключа. Если раздел не является одним из предопределенных разделов реестра, вызовите функцию RegCloseKey после завершения использования дескриптора.

[out, optional] lpdwDisposition

Указатель на переменную, которая получает одно из следующих значений перед ликвидацией.

Значение Значение
REG_CREATED_NEW_KEY
0x00000001L
Ключ не существует и был создан.
REG_OPENED_EXISTING_KEY
0x00000002L
Ключ существовал и был просто открыт без изменения.
 

Если 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

См. также раздел

RegCloseKey

RegDeleteKeyTransacted

RegOpenKeyTransacted

RegSaveKey

Функции реестра

Общие сведения о реестре

SECURITY_ATTRIBUTES