Partilhar via

Classe CRegKey

  • Artigo

Essa classe fornece métodos para manipular entradas no Registro do sistema.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

class CRegKey

Membros

Construtores públicos

Nome Descrição
CRegKey::CRegKey O construtor .
CRegKey::~CRegKey O destruidor.

Métodos públicos

Nome Descrição
CRegKey::Attach Chame esse método para anexar um HKEY ao objeto CRegKey ao definir o identificador do membro m_hKey para hKey.
CRegKey::Close Chame esse método para liberar o identificador m_hKey do membro e defini-lo como NULL.
CRegKey::Create Chame esse método para criar a chave especificada, se ela não existir como uma subchave de hKeyParent.
CRegKey::DeleteSubKey Chame esse método para remover a chave especificada do registro.
CRegKey::DeleteValue Chame esse método para remover um campo de valor de m_hKey.
CRegKey::Detach Chame esse método para desanexar o identificador m_hKey do membro do objeto CRegKey e definir m_hKey como NULL.
CRegKey::EnumKey Chame esse método para enumerar as subchaves da chave aberta do registro.
CRegKey::Flush Chame esse método para gravar todos os atributos da chave aberta do registro no registro.
CRegKey::GetKeySecurity Chame esse método para recuperar uma cópia do descritor de segurança que protege a chave aberta do registro.
CRegKey::NotifyChangeKeyValue Esse método notifica o chamador sobre alterações nos atributos ou conteúdo da chave aberta do registro.
CRegKey::Open Chame esse método para abrir a chave especificada e definir m_hKey como o identificador dessa chave.
CRegKey::QueryBinaryValue Chame esse método para recuperar os dados binários para um nome de valor especificado.
CRegKey::QueryDWORDValue Chame esse método para recuperar os dados DWORD para um nome de valor especificado.
CRegKey::QueryGUIDValue Chame esse método para recuperar os dados de GUID para um nome de valor especificado.
CRegKey::QueryMultiStringValue Chame esse método para recuperar os dados de cadeia de caracteres múltipla para um nome de valor especificado.
CRegKey::QueryQWORDValue Chame esse método para recuperar os dados QWORD para um nome de valor especificado.
CRegKey::QueryStringValue Chame esse método para recuperar os dados de cadeias de caracteres para um nome de valor especificado.
CRegKey::QueryValue Chame esse método para recuperar os dados do campo de valor especificado de m_hKey. Versões anteriores desse método não têm mais suporte e são marcadas como ATL_DEPRECATED.
CRegKey::RecurseDeleteKey Chame esse método para remover a chave especificada do registro e remover explicitamente as subchaves.
CRegKey::SetBinaryValue Chame esse método para definir o valor binário da chave do registro.
CRegKey::SetDWORDValue Chame esse método para definir o valor DWORD da chave do registro.
CRegKey::SetGUIDValue Chame esse método para definir o valor de GUID da chave do registro.
CRegKey::SetKeySecurity Chame esse método para definir a segurança da chave do registro.
CRegKey::SetKeyValue Chame esse método para armazenar dados em um campo de valor especificado de uma chave especificada.
CRegKey::SetMultiStringValue Chame esse método para definir o valor de cadeia de caracteres múltipla da chave do registro.
CRegKey::SetQWORDValue Chame esse método para definir o valor QWORD da chave do registro.
CRegKey::SetStringValue Chame esse método para definir o valor de cadeias de caracteres da chave do registro.
CRegKey::SetValue Chame esse método para armazenar dados no campo de valor especificado de m_hKey. Versões anteriores desse método não têm mais suporte e são marcadas como ATL_DEPRECATED.

Operadores públicos

Nome Descrição
CRegKey::operator HKEY Converte um objeto CRegKey em um HKEY.
CRegKey::operator = Operador de atribuição.

Membros de Dados Públicos

Nome Descrição
CRegKey::m_hKey Contém um identificador da chave do registro associada ao objeto CRegKey.
CRegKey::m_pTM Ponteiro para o objeto CAtlTransactionManager

Comentários

CRegKey fornece métodos para criar e excluir chaves e valores no registro do sistema. O registro contém um conjunto específico de definições de instalação para componentes do sistema, como números de versão de software, mapeamentos lógicos para físicos de hardware instalado e objetos COM.

CRegKey fornece uma interface de programação para o registro do sistema para um determinado computador. Por exemplo, para abrir uma chave específica do registro, chame CRegKey::Open. Para recuperar ou modificar um valor de dados, chame CRegKey::QueryValue ou CRegKey::SetValue, respectivamente. Para fechar uma chave, chame CRegKey::Close.

Ao fechar uma chave, os dados do registro são gravados (liberados) no disco rígido. Esse processo pode demorar vários segundos. Se o aplicativo precisar gravar explicitamente dados do Registro no disco rígido, você poderá chamar a função RegFlushKey do Win32. No entanto, RegFlushKey usa muitos recursos do sistema e deve ser chamado somente quando absolutamente necessário.

Importante

Todos os métodos que permitem que o chamador especifique um local do registro têm o potencial de ler dados que não são confiáveis. Os métodos usam RegQueryValueEx devem levar em consideração que essa função não manipula explicitamente cadeias de caracteres que são encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

Requisitos

Cabeçalho: atlbase.h

CRegKey::Attach

Chame esse método para anexar um HKEY ao objeto CRegKey ao definir o identificador do membro m_hKey para hKey.

void Attach(HKEY hKey) throw();

Parâmetros

hKey
O identificador de uma chave do registro.

Comentários

Attach afirmará se m_hKey não for NULL.

CRegKey::Close

Chame esse método para liberar o identificador m_hKey do membro e defini-lo como NULL.

LONG Close() throw();

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS; caso contrário, retornará um valor de erro.

CRegKey::Create

Chame esse método para criar a chave especificada, se ela não existir como uma subchave de hKeyParent.

LONG Create(
    HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    LPTSTR lpszClass = REG_NONE,
    DWORD dwOptions = REG_OPTION_NON_VOLATILE,
    REGSAM samDesired = KEY_READ | KEY_WRITE,
    LPSECURITY_ATTRIBUTES lpSecAttr = NULL,
    LPDWORD lpdwDisposition = NULL) throw();

Parâmetros

hKeyParent
O identificador de uma chave aberta.

lpszKeyName
Especifica o nome de uma chave a ser criada ou aberta. Esse nome precisa ser uma subchave de hKeyParent.

lpszClass
Especifica a classe da chave a ser criada ou aberta. O valor padrão é REG_NONE.

dwOptions
Opções para a chave. O valor padrão é REG_OPTION_NON_VOLATILE. Para obter uma lista de possíveis valores e descrições, confira RegCreateKeyEx no SDK do Windows.

samDesired
O acesso de segurança da chave. O valor padrão é KEY_READ | KEY_WRITE. Para obter uma lista de possíveis valores e descrições, confira RegCreateKeyEx.

lpSecAttr
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que indica se o identificador da chave pode ser herdado por um processo filho. Por padrão, esse parâmetro é NULL (o que significa que o identificador não pode ser herdado).

lpdwDisposition
[out] Se não for NULL, recuperará REG_CREATED_NEW_KEY (se a chave não existir e tiver sido criada) ou REG_OPENED_EXISTING_KEY (se a chave existir e for aberta).

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS e abrirá a chave. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Create define o m_hKey membro como o identificador dessa chave.

CRegKey::CRegKey

O construtor .

CRegKey() throw();
CRegKey(CRegKey& key) throw();
explicit CRegKey(HKEY hKey) throw();
CRegKey(CAtlTransactionManager* pTM) throw();

Parâmetros

key
Uma referência a um objeto CRegKey.

hKey
Um identificador de uma chave do registro.

pTM
Ponteiro para o objeto CAtlTransactionManager

Comentários

Cria um novo objeto CRegKey. O objeto pode ser criado de um objeto CRegKey existente ou de um identificador para uma chave do registro.

CRegKey::~CRegKey

O destruidor.

~CRegKey() throw();

Comentários

O destruidor é libera m_hKey.

CRegKey::DeleteSubKey

Chame esse método para remover a chave especificada do registro.

LONG DeleteSubKey(LPCTSTR lpszSubKey) throw();

Parâmetros

lpszSubKey
Especifica o nome da chave a ser excluída. Esse nome precisa ser uma subchave de m_hKey.

Valor de retorno

Se for bem-sucedido, retornará ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

DeleteSubKey só pode excluir uma chave que não tenha subchave. Se a chave tiver subchaves, chame RecurseDeleteKey em vez disso.

CRegKey::DeleteValue

Chame esse método para remover um campo de valor de m_hKey.

LONG DeleteValue(LPCTSTR lpszValue) throw();

Parâmetros

lpszValue
Especifica o campo de valor a ser removido.

Valor de retorno

Se for bem-sucedido, retornará ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

CRegKey::Detach

Chame esse método para desanexar o identificador m_hKey do membro do objeto CRegKey e definir m_hKey como NULL.

HKEY Detach() throw();

Valor de retorno

O HKEY associado ao objeto CRegKey.

CRegKey::EnumKey

Chame esse método para enumerar as subchaves da chave aberta do registro.

LONG EnumKey(
    DWORD iIndex,
    LPTSTR pszName,
    LPDWORD pnNameLength,
    FILETIME* pftLastWriteTime = NULL) throw();

Parâmetros

iIndex
O índice de subchave. Esse parâmetro deve ser zero para a primeira chamada e incrementado para chamadas subsequentes

pszName
Ponteiro para um buffer que recebe o nome da subchave, incluindo o caractere nulo de terminação. Somente o nome da subchave é copiado para o buffer, não para a hierarquia de chave completa.

pnNameLength
Ponteiro para uma variável que especifica o tamanho, em TCHARs, do buffer especificado pelo parâmetro pszName. Esse tamanho deve incluir o caractere nulo de terminação. Quando o método retorna, a variável apontada por pnNameLength contém o número de caracteres armazenados no buffer. A contagem retornada não inclui o caractere nulo de terminação.

pftLastWriteTime
Ponteiro para uma variável que recebe a hora em que a subchave enumerada foi gravada pela última vez.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Para enumerar as subchaves, chame CRegKey::EnumKey com um índice de zero. Incremente o valor do índice e repita até que o método retorne ERROR_NO_MORE_ITEMS. Para obter mais informações, consulte RegEnumKeyEx no SDK do Windows.

CRegKey::Flush

Chame esse método para gravar todos os atributos da chave aberta do registro no registro.

LONG Flush() throw();

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Para obter mais informações, consulte RegEnumFlush no SDK do Windows.

CRegKey::GetKeySecurity

Chame esse método para recuperar uma cópia do descritor de segurança que protege a chave aberta do registro.

LONG GetKeySecurity(
    SECURITY_INFORMATION si,
    PSECURITY_DESCRIPTOR psd,
    LPDWORD pnBytes) throw();

Parâmetros

si
O valor SECURITY_INFORMATION que indica as informações de segurança solicitadas.

psd
Um ponteiro para um buffer que recebe uma cópia do descritor de segurança solicitado.

pnBytes
O tamanho, em bytes, do buffer apontado por psd.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Para obter mais informações, consulte RegGetKeySecurity.

CRegKey::m_hKey

Contém um identificador da chave do registro associada ao objeto CRegKey.

HKEY m_hKey;

CRegKey::m_pTM

Ponteiro para um objeto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Comentários

CRegKey::NotifyChangeKeyValue

Esse método notifica o chamador sobre alterações nos atributos ou conteúdo da chave aberta do registro.

LONG NotifyChangeKeyValue(
    BOOL bWatchSubtree,
    DWORD dwNotifyFilter,
    HANDLE hEvent,
    BOOL bAsync = TRUE) throw();

Parâmetros

bWatchSubtree
Especifica um sinalizador que indica se deve relatar alterações na chave especificada e em todas as subchaves ou somente na chave especificada. Se esse parâmetro for TRUE, o método relatará alterações na chave e em suas subchaves. Se o parâmetro for FALSE, o método relatará alterações apenas na chave.

dwNotifyFilter
Especifica um conjunto de sinalizadores que controlam quais alterações devem ser relatadas. Esse parâmetro pode ser uma combinação dos seguintes valores:

Valor Significado
REG_NOTIFY_CHANGE_NAME Notifique o chamador se uma subchave for adicionada ou excluída.
REG_NOTIFY_CHANGE_ATTRIBUTES Notifique o chamador de alterações nos atributos da chave, como as informações do descritor de segurança.
REG_NOTIFY_CHANGE_LAST_SET Notifique o chamador de alterações para um valor da chave. Isso pode incluir a adição ou exclusão de um valor ou a alteração de um valor existente.
REG_NOTIFY_CHANGE_SECURITY Notifique o chamador de alterações ao descritor de segurança da chave.

hEvent
Identificador de um evento. Se o parâmetro bAsync for TRUE, o método retornará imediatamente e as alterações serão relatadas sinalizando esse evento. Se bAsync for FALSE, hEvent será ignorado.

bAsync
Especifica um sinalizador que indica como o método relata alterações. Se esse parâmetro for TRUE, o método retornará imediatamente e relatará alterações sinalizando o evento especificado. Quando esse parâmetro é FALSE, o método não retorna até que ocorra uma alteração. Se hEvent não especificar um evento válido, o bAsync parâmetro não poderá ser TRUE.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Observação

Esse método não notificará o chamador se a chave especificada for excluída.

Para obter mais detalhes e um programa de exemplo, confira RegNotifyChangeKeyValue.

CRegKey::Open

Chame esse método para abrir a chave especificada e definir m_hKey como o identificador dessa chave.

LONG Open(
    HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    REGSAM samDesired = KEY_READ | KEY_WRITE) throw();

Parâmetros

hKeyParent
O identificador de uma chave aberta.

lpszKeyName
Especifica o nome de uma chave a ser criada ou aberta. Esse nome precisa ser uma subchave de hKeyParent.

samDesired
O acesso de segurança da chave. O valor padrão é KEY_ALL_ACCESS. Para obter uma lista de possíveis valores e descrições, confira RegCreateKeyEx no SDK do Windows.

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS. Caso contrário, um valor de erro não zero definido em WINERROR.H.

Comentários

Se o parâmetro lpszKeyName for NULL ou apontar para uma cadeia de caracteres vazia, Open abrirá um novo identificador da chave identificada por hKeyParent, mas não fechará nenhum identificador aberto anteriormente.

Ao contrário de CRegKey::Create, Open não criará a chave especificada se ela não existir.

CRegKey::operator HKEY

Converte um objeto CRegKey em um HKEY.

operator HKEY() const throw();

CRegKey::operator =

Operador de atribuição.

CRegKey& operator= (CRegKey& key) throw();

Parâmetros

key
A chave a ser verificada.

Valor de retorno

Retorna uma referência à nova chave.

Comentários

Esse operador se desanexa key do objeto atual e o atribui ao objeto CRegKey.

CRegKey::QueryBinaryValue

Chame esse método para recuperar os dados binários para um nome de valor especificado.

LONG QueryBinaryValue(
    LPCTSTR pszValueName,
    void* pValue,
    ULONG* pnBytes) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado.

pValue
Um ponteiro para um buffer que recebe os dados do valor.

pnBytes
Ponteiro para uma variável que especifica o tamanho, em bytes, do buffer que apontado pelo parâmetro pValue. Quando o método retorna, essa variável contém o tamanho dos dados copiados para o buffer.

Valor de retorno

Se o método for bem-sucedido, retornará ERROR_SUCCESS. Se o método não ler um valor, ele retornará um código de erro não zero definido em WINERROR.H. Se os dados referenciados não forem do tipo REG_BINARY, ERROR_INVALID_DATA é retornado.

Comentários

Esse método usa RegQueryValueEx e confirma que o tipo correto de dados é retornado. Confira RegQueryValueEx para saber mais.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis. Além disso, a função RegQueryValueEx usada por esse método não manipula explicitamente cadeias de caracteres encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

CRegKey::QueryDWORDValue

Chame esse método para recuperar os dados DWORD para um nome de valor especificado.

LONG QueryDWORDValue(
    LPCTSTR pszValueName,
    DWORD& dwValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado.

dwValue
Ponteiro para um buffer que recebe o DWORD.

Valor de retorno

Se o método for bem-sucedido, retornará ERROR_SUCCESS. Se o método não ler um valor, ele retornará um código de erro não zero definido em WINERROR.H. Se os dados referenciados não forem do tipo REG_DWORD, ERROR_INVALID_DATA é retornado.

Comentários

Esse método usa RegQueryValueEx e confirma que o tipo correto de dados é retornado. Confira RegQueryValueEx para saber mais.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis. Além disso, a função RegQueryValueEx usada por esse método não manipula explicitamente cadeias de caracteres encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

CRegKey::QueryGUIDValue

Chame esse método para recuperar os dados de GUID para um nome de valor especificado.

LONG QueryGUIDValue(
    LPCTSTR pszValueName,
    GUID& guidValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado.

guidValue
Um ponteiro para uma variável que recebe o GUID.

Valor de retorno

Se o método for bem-sucedido, retornará ERROR_SUCCESS. Se o método não ler um valor, ele retornará um código de erro não zero definido em WINERROR.H. Se os dados referenciados não forem um GUID válido, ERROR_INVALID_DATA é retornado.

Comentários

Esse método usa CRegKey::QueryStringValue e converte a cadeia de caracteres em um GUID usando CLSIDFromString.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis.

CRegKey::QueryMultiStringValue

Chame esse método para recuperar os dados de cadeia de caracteres múltipla para um nome de valor especificado.

LONG QueryMultiStringValue(
    LPCTSTR pszValueName,
    LPTSTR pszValue,
    ULONG* pnChars) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado.

pszValue
Ponteiro para um buffer que recebe a cadeia de caracteres múltipla. Uma cadeia de caracteres múltipla é uma matriz de cadeias de caracteres terminadas em NULL, terminadas com dois caracteres nulos.

pnChars
O tamanho, em pszValue, do buffer apontado por TCHARs. Quando o método retorna, pnChars contém o tamanho, em TCHARs, da cadeia de caracteres múltipla recuperada, incluindo um caractere nulo de terminação.

Valor de retorno

Se o método for bem-sucedido, retornará ERROR_SUCCESS. Se o método não ler um valor, ele retornará um código de erro não zero definido em WINERROR.H. Se os dados referenciados não forem do tipo REG_MULTI_SZ, ERROR_INVALID_DATA é retornado.

Comentários

Esse método usa RegQueryValueEx e confirma que o tipo correto de dados é retornado. Confira RegQueryValueEx para saber mais.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis. Além disso, a função RegQueryValueEx usada por esse método não manipula explicitamente cadeias de caracteres encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

CRegKey::QueryQWORDValue

Chame esse método para recuperar os dados QWORD para um nome de valor especificado.

LONG QueryQWORDValue(
    LPCTSTR pszValueName,
    ULONGLONG& qwValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado.

qwValue
Ponteiro para um buffer que recebe o QWORD.

Valor de retorno

Se o método for bem-sucedido, retornará ERROR_SUCCESS. Se o método não ler um valor, ele retornará um código de erro não zero definido em WINERROR.H. Se os dados referenciados não forem do tipo REG_QWORD, ERROR_INVALID_DATA é retornado.

Comentários

Esse método usa RegQueryValueEx e confirma que o tipo correto de dados é retornado. Confira RegQueryValueEx para saber mais.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis. Além disso, a função RegQueryValueEx usada por esse método não manipula explicitamente cadeias de caracteres encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

CRegKey::QueryStringValue

Chame esse método para recuperar os dados de cadeias de caracteres para um nome de valor especificado.

LONG QueryStringValue(
    LPCTSTR pszValueName,
    LPTSTR pszValue,
    ULONG* pnChars) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado.

pszValue
Ponteiro para um buffer que recebe os dados de cadeia de caracteres.

pnChars
O tamanho, em TCHARs, do buffer apontado por pszValue. Quando o método retorna, pnChars contém o tamanho, em TCHARs, da cadeia de caracteres recuperada, incluindo um caractere nulo de terminação.

Valor de retorno

Se o método for bem-sucedido, retornará ERROR_SUCCESS. Se o método não ler um valor, ele retornará um código de erro não zero definido em WINERROR.H. Se os dados referenciados não forem do tipo REG_SZ, ERROR_INVALID_DATA é retornado. Se o método retornar ERROR_MORE_DATA, pnChars será igual a zero, não o tamanho do buffer necessário em bytes.

Comentários

Esse método usa RegQueryValueEx e confirma que o tipo correto de dados é retornado. Confira RegQueryValueEx para saber mais.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis. Além disso, a função RegQueryValueEx usada por esse método não manipula explicitamente cadeias de caracteres encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

CRegKey::QueryValue

Chame esse método para recuperar os dados do campo de valor especificado de m_hKey. Versões anteriores desse método não têm mais suporte e são marcadas como ATL_DEPRECATED.

LONG QueryValue(
    LPCTSTR pszValueName,
    DWORD* pdwType,
    void* pData,
    ULONG* pnBytes) throw();

ATL_DEPRECATED LONG QueryValue(
    DWORD& dwValue,
    LPCTSTR lpszValueName);

ATL_DEPRECATED LONG QueryValue(
    LPTSTR szValue,
    LPCTSTR lpszValueName,
    DWORD* pdwCount);

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome do valor a ser consultado. Se pszValueName for NULL ou uma cadeia de caracteres vazia, "", o método recuperará o tipo e os dados para o valor não nomeado ou padrão da chave, se houver.

pdwType
Ponteiro para uma variável que recebe um código que indica o tipo de dados armazenados no valor especificado. O parâmetro pdwType poderá ser NULL se o código de tipo não for necessário.

pData
Um ponteiro para um buffer que recebe os dados do valor. O parâmetro pode ser NULL se os dados não forem obrigatórios.

pnBytes
Ponteiro para uma variável que especifica o tamanho, em bytes, do buffer que apontado pelo parâmetro pData. Quando o método retorna, essa variável contém o tamanho dos dados copiados para pData.

dwValue
Os dados numéricos do campo de valor.

lpszValueName
Especifica o campo de valor a ser consultado.

szValue
Os dados de cadeia de caracteres do campo de valor.

pdwCount
O tamanho dos dados da cadeia de caracteres. Seu valor é inicialmente definido como o tamanho do buffer szValue.

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS. Caso contrário, um código de erro não zero definido em WINERROR.H.

Comentários

As duas versões originais de QueryValue não têm mais suporte e são marcadas como ATL_DEPRECATED. O compilador emitirá um aviso se esses formulários forem usados.

O método restante chama RegQueryValueEx.

Importante

Esse método permite que o chamador especifique qualquer local do registro, lendo potencialmente dados que não são confiáveis. Além disso, a função RegQueryValueEx usada por esse método não manipula explicitamente cadeias de caracteres encerradas em nulo. Ambas as condições devem ser verificadas pelo código de chamada.

CRegKey::RecurseDeleteKey

Chame esse método para remover a chave especificada do registro e remover explicitamente as subchaves.

LONG RecurseDeleteKey(LPCTSTR lpszKey) throw();

Parâmetros

lpszKey
Especifica o nome da chave a ser excluída. Esse nome precisa ser uma subchave de m_hKey.

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS. Caso contrário, um valor de erro não zero definido em WINERROR.H.

Comentários

Se a chave tiver subchaves, você precisará chamar esse método para excluir a chave.

CRegKey::SetBinaryValue

Chame esse método para definir o valor binário da chave do registro.

LONG SetBinaryValue(
    LPCTSTR pszValueName,
    const void* pValue,
    ULONG nBytes) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente, o método o adicionará à chave.

pValue
Ponteiro para um buffer que contém os dados a serem armazenados com o nome do valor especificado.

nBytes
Especifica o tamanho, em bytes, das informações apontadas pelo parâmetro pValue.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Esse método usa RegSetValueEx para gravar o valor no registro.

CRegKey::SetDWORDValue

Chame esse método para definir o valor DWORD da chave do registro.

LONG SetDWORDValue(LPCTSTR pszValueName, DWORD dwValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente, o método o adicionará à chave.

dwValue
Os dados DWORD a serem armazenados com o nome do valor especificado.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Esse método usa RegSetValueEx para gravar o valor no registro.

CRegKey::SetGUIDValue

Chame esse método para definir o valor de GUID da chave do registro.

LONG SetGUIDValue(LPCTSTR pszValueName, REFGUID guidValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente, o método o adicionará à chave.

guidValue
Referência ao GUID a ser armazenada com o nome do valor especificado.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Esse método usa CRegKey::SetStringValue e converte o GUID em uma cadeia de caracteres usando StringFromGUID2.

CRegKey::SetKeyValue

Chame esse método para armazenar dados em um campo de valor especificado de uma chave especificada.

LONG SetKeyValue(
    LPCTSTR lpszKeyName,
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL) throw();

Parâmetros

lpszKeyName
Especifica o nome da chave a ser criada ou aberta. Esse nome precisa ser uma subchave de m_hKey.

lpszValue
Especifica os dados a serem armazenados. Esse parâmetro precisa ser diferente de NULL.

lpszValueName
Especifica o campo de valor a ser definido. Se um campo de valor com esse nome ainda não existir na chave, ele será adicionado.

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS. Caso contrário, um código de erro não zero definido em WINERROR.H.

Comentários

Chame esse método para criar ou abrir a chave lpszKeyName e armazenar os dados lpszValue no campo de valor lpszValueName.

CRegKey::SetKeySecurity

Chame esse método para definir a segurança da chave do registro.

LONG SetKeySecurity(SECURITY_INFORMATION si, PSECURITY_DESCRIPTOR psd) throw();

Parâmetros

si
Especifica os componentes do descritor de segurança a ser definido. O valor ser uma combinação dos seguintes valores:

Valor Significado
DACL_SECURITY_INFORMATION Define a lista de controle de acesso discricionário (DACL) da chave. A chave precisa ter acesso WRITE_DAC ou o processo de chamada precisa ser o proprietário do objeto.
GROUP_SECURITY_INFORMATION Define o SID (identificador de segurança do grupo primário) da chave. A chave precisa ter acesso WRITE_OWNER ou o processo de chamada precisa ser o proprietário do objeto.
OWNER_SECURITY_INFORMATION Define o SID proprietário da chave. A chave precisa ter acesso WRITE_OWNER ou o processo de chamada precisa ser o proprietário do objeto ou ter o privilégio SE_TAKE_OWNERSHIP_NAME habilitado.
SACL_SECURITY_INFORMATION Especifica a SACL (lista de controle de acesso do sistema) da chave. A chave precisa ter acesso ACCESS_SYSTEM_SECURITY. A maneira correta de obter esse acesso é habilitar o SE_SECURITY_NAME privilégio no token de acesso atual do chamador, abrir o identificador de ACCESS_SYSTEM_SECURITY acesso e desabilitar o privilégio.

psd
Ponteiro para uma estrutura SECURITY_DESCRIPTOR que especifica os atributos de segurança a serem definidos para a chave especificada.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Define os atributos de segurança da chave. Confira RegSetKeySecurity para saber mais.

CRegKey::SetMultiStringValue

Chame esse método para definir o valor de cadeia de caracteres múltipla da chave do registro.

LONG SetMultiStringValue(LPCTSTR pszValueName, LPCTSTR pszValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente, o método o adicionará à chave.

pszValue
Ponteiro para os dados da cadeia de caracteres múltipla a serem armazenados com o nome do valor especificado. Uma cadeia de caracteres múltipla é uma matriz de cadeias de caracteres terminadas em NULL, terminadas com dois caracteres nulos.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Esse método usa RegSetValueEx para gravar o valor no registro.

CRegKey::SetQWORDValue

Chame esse método para definir o valor QWORD da chave do registro.

LONG SetQWORDValue(LPCTSTR pszValueName, ULONGLONG qwValue) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente, o método o adicionará à chave.

qwValue
Os dados QWORD a serem armazenados com o nome do valor especificado.

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Esse método usa RegSetValueEx para gravar o valor no registro.

CRegKey::SetStringValue

Chame esse método para definir o valor de cadeias de caracteres da chave do registro.

LONG SetStringValue(
    LPCTSTR pszValueName,
    LPCTSTR pszValue,
    DWORD dwType = REG_SZ) throw();

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente, o método o adicionará à chave.

pszValue
Ponteiro para os dados da cadeia de caracteres a serem armazenados com o nome do valor especificado.

dwType
O tipo de cadeia de caracteres para gravar o registro: REG_SZ (padrão) ou REG_EXPAND_SZ (para cadeia de caracteres múltipla).

Valor de retorno

Se o método obtiver êxito, o valor retornado será ERROR_SUCCESS. Se o método falhar, o valor retornado será um código de erro não zero definido em WINERROR.H.

Comentários

Esse método usa RegSetValueEx para gravar o valor no registro.

CRegKey::SetValue

Chame esse método para armazenar dados no campo de valor especificado de m_hKey. Versões anteriores desse método não têm mais suporte e são marcadas como ATL_DEPRECATED.

LONG SetValue(
    LPCTSTR pszValueName,
    DWORD dwType,
    const void* pValue,
    ULONG nBytes) throw();

static LONG WINAPI SetValue(
    HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL);

ATL_DEPRECATED LONG SetValue(
    DWORD dwValue,
    LPCTSTR lpszValueName);

ATL_DEPRECATED LONG SetValue(
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL,
    bool bMulti = false,
    int nValueLen = -1);

Parâmetros

pszValueName
Ponteiro para uma cadeia de caracteres contendo o nome do valor a definir. Se um valor com esse nome ainda não estiver presente na chave, o método o adicionará à chave. Se pszValueName for NULL ou uma cadeia de caracteres vazia, "", o método definirá o tipo e os dados para o valor não nomeado ou padrão da chave.

dwType
Especifica um código que indica o tipo de dados apontados pelo parâmetro pValue.

pValue
Ponteiro para um buffer que contém os dados a serem armazenados com o nome do valor especificado.

nBytes
Especifica o tamanho, em bytes, das informações apontadas pelo parâmetro pValue. Se os dados forem do tipo REG_SZ, REG_EXPAND_SZou REG_MULTI_SZ, nBytes precisam incluir o tamanho do caractere nulo de terminação.

hKeyParent
O identificador de uma chave aberta.

lpszKeyName
Especifica o nome de uma chave a ser criada ou aberta. Esse nome precisa ser uma subchave de hKeyParent.

lpszValue
Especifica os dados a serem armazenados. Esse parâmetro precisa ser diferente de NULL.

lpszValueName
Especifica o campo de valor a ser definido. Se um campo de valor com esse nome ainda não existir na chave, ele será adicionado.

dwValue
Especifica os dados a serem armazenados.

bMulti
Se for falso, indica que a cadeia de caracteres é do tipo REG_SZ. Se verdadeiro, indica que a cadeia de caracteres é uma cadeia de caracteres múltipla do tipo REG_MULTI_SZ.

nValueLen
Se bMulti é verdadeiro, nValueLen tetorna o comprimento da cadeia de caracteres lpszValue em caracteres. Se bMulti for falso, um valor de -1 indica que o método calculará o comprimento automaticamente.

Valor de retorno

Se tiver êxito, retornará ERROR_SUCCESS. Caso contrário, um código de erro não zero definido em WINERROR.H.

Comentários

As duas versões originais de SetValue são marcadas como ATL_DEPRECATED e não devem mais ser usadas. O compilador emitirá um aviso se esses formulários forem usados.

O terceiro método chama RegSetValueEx.

Confira também

Exemplo de DCOM
Visão geral da aula