Função WritePrivateProfileSectionA (winbase.h)
Substitui as chaves e os valores da seção especificada em um arquivo de inicialização.
Sintaxe
BOOL WritePrivateProfileSectionA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Parâmetros
[in] lpAppName
O nome da seção na qual os dados são gravados. Esse nome de seção normalmente é o nome do aplicativo de chamada.
[in] lpString
Os novos nomes de chave e valores associados que devem ser gravados na seção nomeada. Essa cadeia de caracteres é limitada a 65.535 bytes.
[in] lpFileName
O nome do arquivo de inicialização. Se esse parâmetro não contiver um caminho completo para o arquivo, a função pesquisa o diretório do Windows para o arquivo. Se o arquivo não existir e lpFileName não contiver um caminho completo, a função criará o arquivo no diretório do Windows.
Se o arquivo existir e tiver sido criado usando caracteres Unicode, a função gravará caracteres Unicode no arquivo. Caso contrário, a função criará um arquivo usando caracteres ANSI.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Comentários
Os dados no buffer apontados pelo parâmetro lpString consistem em uma ou mais cadeias de caracteres terminadas em nulo, seguidas por um caractere nulo final. Cada cadeia de caracteres tem o seguinte formulário:
Chave=String
A função WritePrivateProfileSection não diferencia maiúsculas de minúsculas; a cadeia de caracteres apontada pelo parâmetro lpAppName pode ser uma combinação de letras maiúsculas e minúsculas.
Se nenhum nome de seção corresponder à cadeia de caracteres apontada pelo parâmetro lpAppName , WritePrivateProfileSection criará a seção no final do arquivo de inicialização especificado e inicializará a nova seção com os pares de nome e valor de chave especificados.
WritePrivateProfileSection exclui as chaves e os valores existentes para a seção nomeada e insere os nomes e valores de chave no buffer apontado pelo parâmetro lpString . A função não tenta correlacionar nomes de chave antigos e novos; se os novos nomes aparecerem em uma ordem diferente dos nomes antigos, todos os comentários associados a chaves e valores pré-existintes no arquivo de inicialização provavelmente serão associados a chaves e valores incorretos.
Esta operação é atômica; nenhuma operação que leia ou escreva no arquivo de inicialização especificado é permitida enquanto as informações estão sendo gravadas.
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
Esse mapeamento provavelmente será se um aplicativo modificar arquivos de inicialização do componente do sistema, como Control.ini, System.ini e Winfile.ini. Nesse caso, a função 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 WritePrivateProfileSection 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