Função WritePrivateProfileStructA (winbase.h)

Copia dados em uma chave na seção especificada de um arquivo de inicialização. À medida que copia os dados, a função calcula uma soma de verificação e os acrescenta ao final dos dados. A função GetPrivateProfileStruct usa a soma de verificação para garantir a integridade dos dados.

Nota 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 WritePrivateProfileStructA(
  [in] LPCSTR lpszSection,
  [in] LPCSTR lpszKey,
  [in] LPVOID lpStruct,
  [in] UINT   uSizeStruct,
  [in] LPCSTR szFile
);

Parâmetros

[in] lpszSection

O nome da seção para a qual a cadeia de caracteres será copiada. Se a seção não existir, ela será criada. O nome da seção é independente de maiúsculas e minúsculas, a cadeia de caracteres pode ser qualquer combinação de letras maiúsculas e minúsculas.

[in] lpszKey

O nome da chave a ser associada a uma 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 chaves e entradas dentro da seção, será excluída.

[in] lpStruct

Os dados a serem copiados. Se esse parâmetro for NULL, a chave será excluída.

[in] uSizeStruct

O tamanho do buffer apontado pelo parâmetro lpStruct , em bytes.

[in] szFile

O nome do arquivo de inicialização. Se esse parâmetro for NULL, as informações serão copiadas para o arquivo Win.ini.

Se o arquivo tiver sido criado usando caracteres Unicode, a função gravará caracteres Unicode no arquivo. Caso contrário, a função gravará caracteres ANSI.

Retornar valor

Se a função copiar com êxito a cadeia de caracteres para o arquivo de inicialização, o valor retornado não será zero.

Se a função falhar ou se ela liberar a versão em cache do arquivo de inicialização acessado mais recentemente, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Uma seção no arquivo de inicialização deve ter o seguinte formulário:

[section]
key=string
      .
      .
      .

Se o parâmetro szFile não contiver um caminho completo e um nome de arquivo para o arquivo, WritePrivateProfileString pesquisa o diretório do Windows para o arquivo. Se o arquivo não existir, essa função criará o arquivo no diretório do Windows.

Se szFile contiver um caminho completo e um nome de arquivo e o arquivo não existir, WriteProfileString criará o arquivo. O diretório especificado já deve existir.

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.

Observação

O cabeçalho winbase.h define WritePrivateProfileStruct 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

GetPrivateProfileString

Writeprofilestring