Função GetPrivateProfileSectionNames (winbase.h)

  • Artigo

Recupera os nomes de todas as seções em um arquivo de inicialização.

Nota 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

DWORD GetPrivateProfileSectionNames(
  [out] LPTSTR  lpszReturnBuffer,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

Parâmetros

[out] lpszReturnBuffer

Um ponteiro para um buffer que recebe os nomes de seção associados ao arquivo nomeado. 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 lpszReturnBuffer , em caracteres.

[in] lpFileName

O nome do arquivo de inicialização. Se esse parâmetro for NULL, a função pesquisa o arquivo Win.ini. Se esse parâmetro não contiver um caminho completo para o arquivo, o sistema pesquisa o arquivo no diretório do Windows.

Valor retornado

O valor retornado especifica o número de caracteres copiados para o buffer especificado, não incluindo o caractere nulo de terminação. Se o buffer não for grande o suficiente para conter todos os nomes de seção associados ao arquivo de inicialização especificado, o valor retornado será igual ao tamanho especificado por nSize menos dois.

Comentários

Esta operação é atômica; nenhuma atualização para o arquivo de inicialização é permitida enquanto os nomes de seção estão sendo copiados para o buffer.

O sistema mapeia a maioria .ini referências de arquivo 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 de 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 nessa 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 sem nome (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 sem nome (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 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 fizer logon pela primeira vez após a instalação.
  • @ – esse caractere impede que as leituras acessem o arquivo de .ini no 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.

Requisitos

   
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 (incluir Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

GetPrivateProfileSection

WritePrivateProfileSection