Função GetPrivateProfileStringA (winbase.h)
Recupera uma cadeia de caracteres da seção especificada em um arquivo de inicialização.
Sintaxe
DWORD GetPrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpDefault,
[out] LPSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCSTR 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
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
[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.
Valor de retorno
O valor retornado é o número de caracteres copiados para o buffer, não incluindo a terminação caractere de nulo.
Se nem
Se lpAppName ou lpKeyName estiver 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.
Observações
A função
[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 de nulo e a cadeia de caracteres final é seguida por um segundo caractere de 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 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 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 sem nome (mostrado como <Nenhum Nome>) que especificará 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 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.
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;
}
Nota
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 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 |