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:

1. Procure no Registro o nome do arquivo de inicialização na chave IniFileMapping .
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.

Ao examinar os valores no registro que especificam outros locais do Registro, há vários prefixos que alteram o comportamento do mapeamento de arquivo .ini:

• ! – 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.

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

GetPrivateProfileSection

RegCreateKeyEx

Regsetvalueex

WriteProfileSection