Função WriteProfileSectionA (winbase.h)

Substitui o conteúdo da seção especificada no arquivo Win.ini por chaves e valores especificados. Se Win.ini usar caracteres Unicode, a função gravará caracteres Unicode no arquivo. Caso contrário, a função grava caracteres ANSI.

Observação Essa função é fornecida apenas para compatibilidade com versões de 16 bits do Windows. Os aplicativos devem armazenar informações de inicialização no registro.

 

Sintaxe

BOOL WriteProfileSectionA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpString
);

Parâmetros

[in] lpAppName

O nome da seção. 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.

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 de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Observações

Chaves e valores no buffer de lpString consistem em uma ou mais cadeias de caracteresterminadas nulas, seguidas por um caractere nulo de final. Cada cadeia de caracteres tem o seguinte formulário: chave=cadeia de caracteres.

A função WriteProfileSection não diferencia maiúsculas de minúsculas; as cadeias de caracteres podem ser uma combinação de letras maiúsculas e minúsculas.

WriteProfileSection exclui as chaves e valores existentes da seção nomeada e insere os nomes e valores de chave no buffer apontado por 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, os comentários associados a chaves e valores pré-existentes no arquivo de inicialização provavelmente serão associados a chaves e valores incorretos.

Esta operação é atômica; nenhuma outra operação que leia ou escreva no arquivo de inicialização é 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

Quando a operação foi mapeada, a função WriteProfileSection 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 sem nome (mostrado como <Nenhum Nome>) que especificará 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 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 WriteProfileSection 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. 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

Consulte também

GetProfileSection

WritePrivateProfileSection