Função GetPrivateProfileStringW (winbase.h)
Recupera uma cadeia de caracteres da seção especificada em um arquivo de inicialização.
Sintaxe
DWORD GetPrivateProfileStringW(
[in] LPCWSTR lpAppName,
[in] LPCWSTR lpKeyName,
[in] LPCWSTR lpDefault,
[out] LPWSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCWSTR 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, essa função definirá errorno com um valor de '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:
- Procure no Registro o nome do arquivo de inicialização na chave IniFileMapping .
- 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.
- 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.
- 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.
- 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.
- 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.
- ! – 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;
}
Observação
O cabeçalho winbase.h define GetPrivateProfileString como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de