Função GetProfileStringA (winbase.h)
Recupera a cadeia de caracteres associada a uma chave na seção especificada do arquivo Win.ini.
Sintaxe
DWORD GetProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpDefault,
[out] LPSTR lpReturnedString,
[in] DWORD nSize
);
Parâmetros
[in] lpAppName
O nome da seção que contém a chave. Se esse parâmetro for NULL, a função 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, a função copiará todas as chaves na seção fornecida para o buffer fornecido. Cada cadeia de caracteres é seguida por um caractere de nulo e a cadeia de caracteres final é seguida por um segundo caractere de nulo.
[in] lpDefault
Uma cadeia de caracteres padrão. Se a chave
Evite especificar uma cadeia de caracteres padrão com caracteres em branco à direita. A função insere um
[out] lpReturnedString
Um ponteiro para um buffer que recebe a cadeia de caracteres.
[in] nSize
O tamanho do buffer apontado pelo parâmetro lpReturnedString, em caracteres.
Valor de retorno
O valor retornado é o número de caracteres copiados para o buffer, não incluindo o caractere nulo-terminating.
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.
Observações
Se a cadeia de caracteres associada ao parâmetro lpKeyName estiver entre aspas única ou dupla, as marcas serão descartadas quando a função GetProfileString retornar a cadeia de caracteres.
A função
Uma seção no arquivo Win.ini deve ter o seguinte formulário:
[section]
key=string
.
.
.
Um aplicativo pode usar a função GetPrivateProfileString para recuperar uma cadeia de caracteres de um arquivo de inicialização especificado.
O parâmetro lpDefault deve apontar para uma cadeia de caracteres válida, mesmo que a cadeia de caracteres esteja vazia (ou seja, mesmo que seu primeiro caractere seja um caractere de nulo).
Windows Server 2003 e Windows XP/2000: Chamadas para funções de perfil podem ser mapeadas para o registro em vez de para os arquivos de inicialização. Esse mapeamento ocorre quando o arquivo de inicialização e a seção são especificados no Registro sob as seguintes chaves:
Quando a operação foi mapeada, a função GetProfileString 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.
Nota
O cabeçalho winbase.h define GetProfileString 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 |