Função GetPrivateProfileSection (winbase.h)

  • Artigo

Recupera todas as chaves e valores da seção especificada de um arquivo de inicialização.

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

Sintaxe

DWORD GetPrivateProfileSection(
  [in]  LPCTSTR lpAppName,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

Parâmetros

[in] lpAppName

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

[out] lpReturnedString

Um ponteiro para um buffer que recebe o nome da chave e os pares de valor associados à seção nomeada. O buffer é preenchido com uma ou mais cadeias de caracteres terminadas em nulo; a última cadeia de caracteres é seguida por um segundo caractere nulo.

[in] nSize

O tamanho do buffer apontado pelo parâmetro lpReturnedString , em caracteres.

O tamanho máximo da seção de perfil é de 32.767 caracteres.

[in] lpFileName

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.

Retornar valor

O valor retornado especifica o número de caracteres copiados para o buffer, sem incluir o caractere nulo de terminação. Se o buffer não for grande o suficiente para conter todos os pares de nome e valor de chave associados à seção nomeada, o valor retornado será igual a nSize menos dois.

Comentários

Os dados no buffer apontados pelo parâmetro lpReturnedString consistem em uma ou mais cadeias de caracteres terminadas em nulo, seguidas por um caractere nulo final. Cada cadeia de caracteres tem o seguinte formato:

Chave=String

A função GetPrivateProfileSection não diferencia maiúsculas de minúsculas; a cadeia de caracteres apontada pelo parâmetro lpAppName pode ser uma combinação de letras maiúsculas e minúsculas.

Esta operação é atômica; nenhuma atualização para o arquivo de inicialização especificado é permitida enquanto o nome da chave e os pares de valor da seção estão sendo copiados para o buffer apontado pelo parâmetro lpReturnedString .

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

Esse mapeamento provavelmente será se um aplicativo modificar arquivos de inicialização do componente do sistema, como Control.ini, System.ini e 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:

  1. Procure no Registro o nome do arquivo de inicialização na chave IniFileMapping .
  2. Procure o nome da seção especificado por lpAppName. Esse será um valor nomeado sob a chave que tem o nome do arquivo de inicialização ou uma subchave com esse nome ou o nome não existirá como um valor ou subchave.
  3. Se o nome da seção especificado por lpAppName for um valor nomeado, esse valor especificará onde, no Registro, você encontrará as chaves da seção.
  4. Se o nome da seção especificado por lpAppName for uma subchave, 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.
  5. Se o nome da seção especificado por lpAppName não existir como um valor nomeado ou como uma subchave, haverá um valor não nomeado (mostrado como <Nenhum Nome>) que especifica o local padrão no registro em que você encontrará as chaves da seção.
  6. Se não houver nenhuma subchave ou entrada para o nome da seção, procure o arquivo de inicialização 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 no 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 faz logon pela primeira vez após a instalação.
  • @ – esse caractere impede que as leituras acessem o arquivo .ini em disco se os dados solicitados não forem encontrados no registro.
  • USR: - esse prefixo significa HKEY_CURRENT_USER e 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.
Os comentários (qualquer linha que começa com um ponto e vírgula) são removidos e não retornados no buffer lpReturnedString .

Requisitos

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

Confira também

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection