Como usar a API do Registro para salvar e recuperar configuração

Traduções deste artigo Traduções deste artigo
ID do artigo: 145679 - Exibir os produtos aos quais esse artigo se aplica.
Expandir tudo | Recolher tudo

Neste artigo

Sumário

Embora o Visual Basic inclui as funções GetSetting e SaveSetting para salvar e recuperar informações do Registro, essas funções operam somente em uma seção específica do Registro, o Visual Basic e configurações de programas VBA da chave raiz HKEY_CURRENT_USER.

Este artigo descreve o uso de funções de API do Windows de 32 bits, que pode ser usado para definir e recuperar valores de qualquer lugar no registro. Os tópicos e referências de função neste artigo podem ser generalizadas para o programa de 16 bits do Registro.

As funções de API de 32 bits também incluem suporte para segurança, embora seja uma visão geral sobre a segurança do fora do escopo deste artigo.

Observação: As funções GetSetting e SaveSetting não fazem parte da biblioteca de função do VBA. Entretanto, o código de exemplo abaixo ainda se aplica a aplicativos de 32 bits que implementam o VBA.

Mais Informações

Informações gerais do registro

O registro é usado por aplicativos e o Windows para armazenar dados de configuração. Ele é uma substituição para o grande número de arquivos INI proliferated em máquinas do Windows 3.x e que também são usados intensamente por OLE.

O registro é organizado usando uma série de chaves e valores parecidos com uma árvore hierárquica. Cada chave, começando com uma das seis chaves raiz predefinidas, pode ter subchaves e valores associados a ele. As chaves são unidades organizacionais e de nomes e aparecem em editores de registro do Windows como pastas de arquivos. Valores são entradas de dados e aparecem como entradas de texto no painel à direita da janela Editor do Registro. Chaves não precisam ter quaisquer valores associados, mas podem ter muitos. Cada valor tem um tipo de dados associado. Os dois tipos de dados de registro mais comumente usadas são REG_SZ, uma cadeia terminada com nulo; e REG_DWORD, um número de 32 bits.

O processo básico usado para gravar ou ler a partir de um local no registro é o mesmo. Para fazer referência a qualquer determinada chave ou valor, você deve ter um identificador para a chave. Depois que esse identificador é obtido, valores e subchaves da chave que este identificador se refere a podem ser ler, definir ou listados (enumerados).

Dado um local no registro, para obter um identificador para essa chave, você deve começar com uma das seis chaves predefinidas (HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG e HKEY_DYN_DATA) e percorrer a árvore do registro até que a tecla desejada seja atingida. Programas de usuário com mais freqüência leitura e gravação de HKEY_CURRENT_USER e HKEY_LOCAL_MACHINE. Se as teclas sendo desviadas já existirem, você pode usar uma série de chamadas para as funções RegOpenKey ou RegOpenKeyEx. Se as chaves precisam ser criados, as funções RegCreateKey e RegCreateKeyEx fazer o trabalho.

Com o identificador para a chave desejada, as funções usadas para lista, definir e recuperar informações podem ser chamadas. Em todos os casos, as funções com o sufixo ex funcionará somente em plataformas de 32 bits. Funções sem o sufixo podem funcionar em versões de 32 bits e 16 bits do Windows. Tenha em mente que nem todas as funções do registro sem o sufixo 'Ex' são funções fornecidas para compatibilidade de 16 bits. O sufixo ex só foi adicionado quando os recursos de funções de 16 bits foram expandidos. Funções que são totalmente nova e específicos para plataformas de 32 bits não possuem uma extensão de ex.

As funções RegSetValue e RegSetValueEx permitem que as configurações de um valor a ser modificado enquanto RegQueryValue e RegQueryValueEx recuperar a configuração atual de um valor. As limitações do não-ex, versões de 16 bits dessas APIs são muito evidentes aqui. Ao usar a função de RegSetValue de 16 bits não é possível para nomear um valor e, devido a isso, RegSetValue não pode ser usado para associar mais de um valor a cada chave. Além disso, todos os valores gravados com RegSetValue têm um tipo de dados de REG_SZ. Essas limitações inerentes com o registro de 16 bits. RegSetValueEx permite a criação de um número vários de valores com qualquer tipo de dados disponíveis.

Como a gravação para um local específico do registro

Após determinar quais funções você precisará usar para seu projeto, a cópia o relevante declara do código no final deste artigo a um módulo básico. Os dois Visual Basic procedimentos incluídos (SetValueEx e QueryValueEx) são invólucros para as funções RegSetValueEx e RegQueryValueEx API e simplificam seu uso. As notas abaixo criar usar dessas funções do Visual Basic; no entanto, você é livres para fazer chamadas diretamente para a API se desejar.

Criar/modificar chaves e valores:

Com as declarações e os procedimentos disponíveis, você pode criar e abrir chaves e adicionar, modificar e ler valores. As três seções a seguir explicam como criar uma chave, definir ou modificar um valor e consultar um valor.

Criando uma nova chave:

Criando uma nova chave é tão simples quanto usando o procedimento a seguir. CreateNewKey obtém o nome da chave para criar e a constante que representa a chave predefinida para criar a chave em. A chamada para RegCreateKeyEx não tirar proveito dos mecanismos de segurança permitidos, mas pode ser modificada para fazer isso. Uma discussão sobre segurança de registro está fora do escopo deste artigo.
   Private Sub CreateNewKey (sNewKeyName As String, lPredefinedKey As Long)
       Dim hNewKey As Long         'handle to the new key
       Dim lRetVal As Long         'result of the RegCreateKeyEx function

       lRetVal = RegCreateKeyEx(lPredefinedKey, sNewKeyName, 0&, _
                 vbNullString, REG_OPTION_NON_VOLATILE, KEY_ALL_ACCESS, _
                 0&, hNewKey, lRetVal)
       RegCloseKey (hNewKey)
   End Sub
				

Com esse procedimento uma chamada de:
   CreateNewKey "TestKey", HKEY_LOCAL_MACHINE
				

criará uma chave chamada TestKey imediatamente em HKEY_LOCAL_MACHINE.

Chamada CreateNewKey assim:
      CreateNewKey "TestKey\SubKey1\SubKey2", HKEY_LOCAL_MACHINE
				

criará aninhados em três chaves começando com TestKey imediatamente em HKEY_CURRENT_USER, SubKey1 subordinado a TestKey e SubKey3 em SubKey2.

Um valor de configuração/modificação:

Criar e definir um valor de uma chave especificada podem ser feitos com o seguinte procedimento curto. SetKeyValue leva a chave que o valor será associado, o nome do valor, a configuração do valor e tipo do valor (o SetValueEx função somente suporta REG_SZ e REG_DWORD, mas isso pode ser modificado se necessário). Especificando um novo valor para um sValueName existente irá modificar a configuração atual desse valor.
   Private Sub SetKeyValue (sKeyName As String, sValueName As String, _
   vValueSetting As Variant, lValueType As Long)
       Dim lRetVal As Long         'result of the SetValueEx function
       Dim hKey As Long         'handle of open key

       'open the specified key
       lRetVal = RegOpenKeyEx(HKEY_CURRENT_USER, sKeyName, 0, _
                                 KEY_SET_VALUE, hKey)
       lRetVal = SetValueEx(hKey, sValueName, lValueType, vValueSetting)
       RegCloseKey (hKey)
   End Sub
				

Uma chamada de:
   SetKeyValue "TestKey\SubKey1", "StringValue", "Hello", REG_SZ
				

criará um valor do tipo REG_SZ chamado "StringValue" com a configuração de "Hello". Esse valor será associado com a chave SubKey1 de "TestKey."

Nesse caso, "TestKey" é uma subchave de HKEY_CURRENT_USER, mas isso pode ser modificado alterando a RegOpenKeyEx chamada. Essa chamada falhará se "TestKey\SubKey1" não existe. Para evitar esse problema, use uma chamada para RegCreateKeyEx em vez de uma chamada para RegOpenKeyEx. RegCreateKeyEx abrirá uma chave especificada se ele já existir.

Consultar um valor:

O procedimento a seguir pode ser usado para verificar a configuração de um valor existente. QueryValue obtém o nome da chave e o nome de um valor associado com essa chave e exibe uma caixa de mensagem com o valor correspondente. Ele usa uma chamada para a função de wrapper do QueryValueEx definida abaixo, suporta apenas tipos REG_SZ e REG_DWORD.
   Private Sub QueryValue (sKeyName As String, sValueName As String)
       Dim lRetVal As Long         'result of the API functions
       Dim hKey As Long         'handle of opened key
       Dim vValue As Variant      'setting of queried value

       lRetVal = RegOpenKeyEx(HKEY_CURRENT_USER, sKeyName, 0, _
   KEY_QUERY_VALUE, hKey)
       lRetVal = QueryValueEx(hKey, sValueName, vValue)
       MsgBox vValue
       RegCloseKey (hKey)
   End Sub
				

Com esse procedimento, uma chamada de:
   QueryValue "TestKey\SubKey1", "StringValue"
				

será exibida uma caixa de mensagem com a configuração atual do valor "StringValue" e supõe que exista "StringValue" na chave "TestKey\SubKey1".

Se o valor que você consulta não existe QueryValue irá retornar um código de erro de 2 - 'ERROR_BADKEY'.

Observações adicionais:

Os exemplos acima usam as versões de 32 bits estendidas das funções do registro exclusivamente. Essas funções permite que mais de um valor a ser associado a cada chave. Conforme discutido acima, o RegSetValue de 16 bits e RegQueryValue agir em um único valor associado com a chave atual (que é sempre do tipo REG_SZ). Essas funções aparecer no editor o 32 bits do registro com um nome de < NO NOME >. Para definir, modificar ou consultar este valor associado especial, um deve usar as funções de registro de 16 bits. Leitura e gravação do registro em um ambiente de 16 bits é muito mais simples do que em um ambiente de 32 bits. O mesmo procedimento básico é seguido: abrir uma chave e obter um identificador e, em seguida, chamar sua função de modificação com esse identificador, mas não consideração precisa ser feita para vários valores associados ou para tipos de dados de valor diferente. Um aplicativo de 16 bits pode criar e modificar chaves e valores com as declarações das funções RegCreateKey, RegOpenKey, RegQueryValue, RegSetValue e RegCloseKey.

Em alguns casos, não é necessário para os valores a ser associado uma chave. Um aplicativo somente precisará saber se uma determinada chave ou valor existe e não se preocupar com sobre a natureza dos valores da chave. Em uma situação assim, as funções RegEnumKey RegEnumKeyEx e RegEnumValue podem ser usadas para determinar se uma determinada chave ou valor existe. Para obter mais informações sobre essas funções consulte Referência API Text Viewer e/ou a API do Windows.

Função de API e declaração de constante

   Option Explicit

   Public Const REG_SZ As Long = 1
   Public Const REG_DWORD As Long = 4

   Public Const HKEY_CLASSES_ROOT = &H80000000
   Public Const HKEY_CURRENT_USER = &H80000001
   Public Const HKEY_LOCAL_MACHINE = &H80000002
   Public Const HKEY_USERS = &H80000003

   Public Const ERROR_NONE = 0
   Public Const ERROR_BADDB = 1
   Public Const ERROR_BADKEY = 2
   Public Const ERROR_CANTOPEN = 3
   Public Const ERROR_CANTREAD = 4
   Public Const ERROR_CANTWRITE = 5
   Public Const ERROR_OUTOFMEMORY = 6
   Public Const ERROR_ARENA_TRASHED = 7
   Public Const ERROR_ACCESS_DENIED = 8
   Public Const ERROR_INVALID_PARAMETERS = 87
   Public Const ERROR_NO_MORE_ITEMS = 259

   Public Const KEY_QUERY_VALUE = &H1
   Public Const KEY_SET_VALUE = &H2
   Public Const KEY_ALL_ACCESS = &H3F

   Public Const REG_OPTION_NON_VOLATILE = 0

   Declare Function RegCloseKey Lib "advapi32.dll" _
   (ByVal hKey As Long) As Long
   Declare Function RegCreateKeyEx Lib "advapi32.dll" Alias _
   "RegCreateKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, _
   ByVal Reserved As Long, ByVal lpClass As String, ByVal dwOptions _
   As Long, ByVal samDesired As Long, ByVal lpSecurityAttributes _
   As Long, phkResult As Long, lpdwDisposition As Long) As Long
   Declare Function RegOpenKeyEx Lib "advapi32.dll" Alias _
   "RegOpenKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, _
   ByVal ulOptions As Long, ByVal samDesired As Long, phkResult As _
   Long) As Long
   Declare Function RegQueryValueExString Lib "advapi32.dll" Alias _
   "RegQueryValueExA" (ByVal hKey As Long, ByVal lpValueName As _
   String, ByVal lpReserved As Long, lpType As Long, ByVal lpData _
   As String, lpcbData As Long) As Long
   Declare Function RegQueryValueExLong Lib "advapi32.dll" Alias _
   "RegQueryValueExA" (ByVal hKey As Long, ByVal lpValueName As _
   String, ByVal lpReserved As Long, lpType As Long, lpData As _
   Long, lpcbData As Long) As Long
   Declare Function RegQueryValueExNULL Lib "advapi32.dll" Alias _
   "RegQueryValueExA" (ByVal hKey As Long, ByVal lpValueName As _
   String, ByVal lpReserved As Long, lpType As Long, ByVal lpData _
   As Long, lpcbData As Long) As Long
   Declare Function RegSetValueExString Lib "advapi32.dll" Alias _
   "RegSetValueExA" (ByVal hKey As Long, ByVal lpValueName As String, _
   ByVal Reserved As Long, ByVal dwType As Long, ByVal lpValue As _
   String, ByVal cbData As Long) As Long
   Declare Function RegSetValueExLong Lib "advapi32.dll" Alias _
   "RegSetValueExA" (ByVal hKey As Long, ByVal lpValueName As String, _
   ByVal Reserved As Long, ByVal dwType As Long, lpValue As Long, _
   ByVal cbData As Long) As Long
				

Funções de Wrapper QueryValueEx e SetValueEx:
   Public Function SetValueEx(ByVal hKey As Long, sValueName As String, _
   lType As Long, vValue As Variant) As Long
       Dim lValue As Long
       Dim sValue As String
       Select Case lType
           Case REG_SZ
               sValue = vValue & Chr$(0)
               SetValueEx = RegSetValueExString(hKey, sValueName, 0&, _
                                              lType, sValue, Len(sValue))
           Case REG_DWORD
               lValue = vValue
               SetValueEx = RegSetValueExLong(hKey, sValueName, 0&, _
   lType, lValue, 4)
           End Select
   End Function

   Function QueryValueEx(ByVal lhKey As Long, ByVal szValueName As _
   String, vValue As Variant) As Long
       Dim cch As Long
       Dim lrc As Long
       Dim lType As Long
       Dim lValue As Long
       Dim sValue As String

       On Error GoTo QueryValueExError

       ' Determine the size and type of data to be read
       lrc = RegQueryValueExNULL(lhKey, szValueName, 0&, lType, 0&, cch)
       If lrc <> ERROR_NONE Then Error 5

       Select Case lType
           ' For strings
           Case REG_SZ:
               sValue = String(cch, 0)

   lrc = RegQueryValueExString(lhKey, szValueName, 0&, lType, _
   sValue, cch)
               If lrc = ERROR_NONE Then
                   vValue = Left$(sValue, cch-1)
               Else
                   vValue = Empty
               End If
           ' For DWORDS
           Case REG_DWORD:
   lrc = RegQueryValueExLong(lhKey, szValueName, 0&, lType, _
   lValue, cch)
               If lrc = ERROR_NONE Then vValue = lValue
           Case Else
               'all other data types not supported
               lrc = -1
       End Select

   QueryValueExExit:
       QueryValueEx = lrc
       Exit Function

   QueryValueExError:
       Resume QueryValueExExit
   End Function
				

Referências

O Windows 95 User Interface, capítulo 10 - "Usando o registro" de programação

Para referências de função: qualquer guia à API do Win32 ou Win16.

Propriedades

ID do artigo: 145679 - Última revisão: quinta-feira, 15 de julho de 2004 - Revisão: 1.2
A informação contida neste artigo aplica-se a:
  • Microsoft Visual Basic 5.0 Professional Edition
  • Microsoft Visual Basic 6.0 Professional Edition
  • Microsoft Visual Basic 5.0 Enterprise Edition
  • Microsoft Visual Basic Enterprise Edition for Windows 6.0
  • Microsoft Visual Basic 4.0 Standard Edition
  • Microsoft Visual Basic 4.0 Professional Edition
  • Microsoft Visual Basic 4.0 Professional Edition
  • Microsoft Visual Basic 4.0 de 16 bits Enterprise Edition
  • Microsoft Visual Basic 4.0 de 32 Bits Enterprise Edition
  • Microsoft Visual Basic for Applications 5.0
  • Microsoft Visual Basic for Applications 6.0
Palavras-chave: 
kbmt kbcode kbhowto kbtophit KB145679 KbMtpt
Tradução automática
IMPORTANTE: Este artigo foi traduzido por um sistema de tradução automática (também designado por Machine Translation ou MT), não tendo sido portanto traduzido ou revisto por pessoas. A Microsoft possui artigos traduzidos por aplicações (MT) e artigos traduzidos por tradutores profissionais, com o objetivo de oferecer em português a totalidade dos artigos existentes na base de dados de suporte. No entanto, a tradução automática não é sempre perfeita, podendo conter erros de vocabulário, sintaxe ou gramática. A Microsoft não é responsável por incoerências, erros ou prejuízos ocorridos em decorrência da utilização dos artigos MT por parte dos nossos clientes. A Microsoft realiza atualizações freqüentes ao software de tradução automática (MT). Obrigado.
Clique aqui para ver a versão em Inglês deste artigo: 145679

Submeter comentários

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com