Função WriteProfileStringA (winbase.h)
Copia uma cadeia de caracteres para a seção especificada do arquivo Win.ini. Se Win.ini usar caracteres Unicode, a função gravará caracteres Unicode no arquivo. Caso contrário, a função gravará caracteres ANSI.
Sintaxe
BOOL WriteProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString
);
Parâmetros
[in] lpAppName
A seção para a qual a cadeia de caracteres deve ser copiada. Se a seção não existir, ela será criada. O nome da seção não diferencia maiúsculas de minúsculas; a cadeia de caracteres pode ser qualquer combinação de letras maiúsculas e minúsculas.
[in] lpKeyName
A chave a ser associada à cadeia de caracteres. Se a chave não existir na seção especificada, ela será criada. Se esse parâmetro for NULL, toda a seção, incluindo todas as entradas na seção, será excluída.
[in] lpString
Uma cadeia de caracteres terminada em nulo a ser gravada no arquivo. Se esse parâmetro for NULL, a chave apontada pelo parâmetro lpKeyName será excluída.
Retornar valor
Se a função copiar com êxito a cadeia de caracteres para o arquivo Win.ini, o valor retornado não será zero.
Se a função falhar ou se liberar a versão armazenada em cache de Win.ini, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Uma seção no arquivo Win.ini deve ter o seguinte formulário: cadeia decaracteres dechave=.
O sistema mantém uma versão armazenada em cache do mapeamento de arquivo do Registro mais recente para melhorar o desempenho. Se todos os parâmetros forem NULL, a função liberará o cache. Enquanto o sistema estiver editando a versão armazenada em cache do arquivo, os processos que editam o arquivo em si usarão o arquivo original até que o cache seja limpo.
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
Quando a operação foi mapeada, a função WriteProfileString grava informações no registro, não no 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.
Observação
O cabeçalho winbase.h define WriteProfileString 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 |