Função GetPrivateProfileStructW (winbase.h)

Artigo
11/20/2024

Recupera os dados associados a uma chave na seção especificada de um arquivo de inicialização. À medida que recupera os dados, a função calcula uma soma de verificação e a compara com a soma de verificação calculada pela função WritePrivateProfileStruct quando os dados foram adicionados ao arquivo.

Observação Essa função é fornecida apenas para compatibilidade com aplicativos baseados no Windows de 16 bits. Os aplicativos devem armazenar informações de inicialização no registro.

Sintaxe

BOOL GetPrivateProfileStructW(
  [in]  LPCWSTR lpszSection,
  [in]  LPCWSTR lpszKey,
  [out] LPVOID  lpStruct,
  [in]  UINT    uSizeStruct,
  [in]  LPCWSTR szFile
);

Parâmetros

[in] lpszSection

O nome da seção no arquivo de inicialização.

[in] lpszKey

O nome da chave cujos dados devem ser recuperados.

[out] lpStruct

Um ponteiro para o buffer que recebe os dados associados ao arquivo, seção e nomes de chave.

[in] uSizeStruct

O tamanho do buffer apontado pelo parâmetro lpStruct, em bytes.

[in] szFile

O nome do arquivo de inicialização. Se esse parâmetro não contiver um caminho completo para o arquivo, o sistema procurará o arquivo no diretório do Windows.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero.

Observações

Uma seção no arquivo de inicialização deve ter o seguinte formulário:

[section]
key=data
      .
      .
      .

O sistema mapeia a maioria das referências de arquivo .ini para o registro, usando o mapeamento definido sob a seguinte chave do Registro:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\CurrentVersion\IniFileMapping

Esse mapeamento provavelmente será modificado se um aplicativo modificar arquivos de inicialização do componente do sistema, como Control.ini, System.inie Winfile.ini. Nesses casos, a função recupera informações do registro, não do arquivo de inicialização; a alteração no local de armazenamento não tem efeito sobre o comportamento da função.

As funções de perfil usam as seguintes etapas para localizar informações de inicialização:

Procure no Registro o nome do arquivo de inicialização, digamos MyFile.ini, em IniFileMapping.
Procure o nome da seção especificado por lpAppName. Esse será um valor nomeado em myfile.iniou uma subchave de myfile.iniou não existirá.
Se o nome da seção especificado por lpAppName for um valor nomeado em myfile.ini, esse valor especificará onde no registro você encontrará as chaves da seção.
Se o nome da seção especificado por lpAppName for uma subchave de myfile.ini, os valores nomeados sob essa subchave especificarão onde, no Registro, você encontrará as chaves da seção. Se a chave que você está procurando não existir como um valor nomeado, haverá um valor não nomeado (mostrado como <Nenhum Nome>) que especifica o local padrão no registro em que você encontrará a chave.
Se o nome da seção especificado por lpAppName não existir como um valor nomeado ou como uma subchave em myfile.ini, haverá um valor sem nome (mostrado como <Nenhum Nome>) em myfile.ini que especifica o local padrão no registro em que você encontrará as chaves da seção.
Se não houver nenhuma subchave myfile.ini ou se ela não contiver uma entrada para o nome da seção, procure o MyFile.ini real no disco e leia seu conteúdo.

Ao examinar os valores no registro que especificam outros locais do Registro, há vários prefixos que alteram o comportamento do mapeamento de arquivo .ini:

! - esse caractere força todas as gravações a ir para o registro e para o arquivo .ini em disco.
# – esse caractere faz com que o valor do Registro seja definido como o valor no arquivo de .ini do Windows 3.1 quando um novo usuário fizer logon pela primeira vez após a instalação.
@ - esse caractere impede que qualquer leitura vá para o arquivo .ini em disco se os dados solicitados não forem encontrados no registro.
USR: - esse prefixo significa HKEY_CURRENT_USERe o texto após o prefixo é relativo a essa chave.
SYS: esse prefixo significa HKEY_LOCAL_MACHINE\SOFTWAREe o texto após o prefixo é relativo a essa chave.

Nota

O cabeçalho winbase.h define GetPrivateProfileStruct como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winbase.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

writePrivateProfileStruct

Compartilhar via