Compartilhar via


Função GetPrivateProfileString (winbase.h)

Recupera uma cadeia de caracteres da seção especificada 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 GetPrivateProfileString(
  [in]  LPCTSTR lpAppName,
  [in]  LPCTSTR lpKeyName,
  [in]  LPCTSTR lpDefault,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

Parâmetros

[in] lpAppName

O nome da seção que contém o nome da chave. Se esse parâmetro for NULL, a função GetPrivateProfileString copiará todos os nomes de seção no arquivo para o buffer fornecido.

[in] lpKeyName

O nome da chave cuja cadeia de caracteres associada deve ser recuperada. Se esse parâmetro for NULL, todos os nomes de chave na seção especificada pelo parâmetro lpAppName serão copiados para o buffer especificado pelo parâmetro lpReturnedString .

[in] lpDefault

Uma cadeia de caracteres padrão. Se a chave lpKeyName não puder ser encontrada no arquivo de inicialização, GetPrivateProfileString copiará a cadeia de caracteres padrão para o buffer lpReturnedString .

Se esse parâmetro for NULL, o padrão será uma cadeia de caracteres vazia, "".

Evite especificar uma cadeia de caracteres padrão com caracteres em branco à direita. A função insere um caractere nulo no buffer lpReturnedString para remover quaisquer espaços em branco à direita.

[out] lpReturnedString

Um ponteiro para o buffer que recebe a cadeia de caracteres recuperada.

[in] nSize

O tamanho do buffer apontado pelo parâmetro lpReturnedString , em 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 é o número de caracteres copiados para o buffer, não incluindo o caractere nulo de terminação.

Se nem lpAppName nem lpKeyName for NULL e o buffer de destino fornecido for muito pequeno para manter a cadeia de caracteres solicitada, a cadeia de caracteres será truncada e seguida por um caractere nulo e o valor retornado será igual a nSize menos um.

Se lpAppName ou lpKeyName for NULL e o buffer de destino fornecido for muito pequeno para manter todas as cadeias de caracteres, a última cadeia de caracteres será truncada e seguida por dois caracteres nulos . Nesse caso, o valor retornado é igual a nSize menos dois.

Caso o arquivo de inicialização especificado por lpFileName não seja encontrado ou contenha valores inválidos, chamar GetLastError retornará '0x2' (Arquivo Não Encontrado). Para recuperar informações de erro estendidas, chame GetLastError.

Comentários

A função GetPrivateProfileString pesquisa o arquivo de inicialização especificado em busca de uma chave que corresponda ao nome especificado pelo parâmetro lpKeyName no título da seção especificado pelo parâmetro lpAppName . Se encontrar a chave, a função copiará a cadeia de caracteres correspondente para o buffer. Se a chave não existir, a função copiará a cadeia de caracteres padrão especificada pelo parâmetro lpDefault . Uma seção no arquivo de inicialização deve ter o seguinte formulário:

[section]
key=string
      .
      .
      .

Se lpAppName for NULL, GetPrivateProfileString copiará todos os nomes de seção no arquivo especificado para o buffer fornecido. Se lpKeyName for NULL, a função copiará todos os nomes de chave na seção especificada para o buffer fornecido. Um aplicativo pode usar esse método para enumerar todas as seções e chaves em um arquivo. Em ambos os casos, cada cadeia de caracteres é seguida por um caractere nulo e a cadeia de caracteres final é seguida por um segundo caractere nulo . Se o buffer de destino fornecido for muito pequeno para manter todas as cadeias de caracteres, a última cadeia de caracteres será truncada e seguida por dois caracteres nulos .

Se a cadeia de caracteres associada a lpKeyName estiver entre aspas simples ou duplas, as marcas serão descartadas quando a função GetPrivateProfileString recuperar a cadeia de caracteres.

A função GetPrivateProfileString não diferencia maiúsculas de minúsculas; as cadeias de caracteres podem ser uma combinação de letras maiúsculas e minúsculas.

Para recuperar uma cadeia de caracteres do arquivo Win.ini, use a função GetProfileString .

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.

Exemplo

O exemplo a seguir demonstra o uso de GetPrivateProfileString.

// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

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

GetProfileString

WritePrivateProfileString