Função WritePrivateProfileStringA (winbase.h)
Copia uma cadeia de caracteres para a seção especificada de um arquivo de inicialização.
Sintaxe
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Parâmetros
[in] lpAppName
O nome da seção na 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 de minúsculas; a cadeia de caracteres pode ser qualquer combinação de letras maiúsculas e minúsculas.
[in] lpKeyName
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, a seção inteira, incluindo todas as entradas na seção, será excluída.
[in] lpString
Um cadeia de caracteresterminada nula a ser gravada no arquivo. Se esse parâmetro for NULL, a chave apontada pelo parâmetro lpKeyName será excluída.
[in] lpFileName
O nome do arquivo de inicialização.
Se o arquivo tiver sido criado usando caracteres Unicode, a função gravará caracteres Unicode no arquivo. Caso contrário, a função grava caracteres ANSI.
Valor de retorno
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 armazenada em cache do arquivo de inicialização acessado mais recentemente, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Observações
Uma seção no arquivo de inicialização deve ter o seguinte formulário:
[section]
key=string
.
.
.
Se o parâmetro lpFileName 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 lpFileName contiver um caminho completo e um nome de arquivo e o arquivo não existir, WritePrivateProfileString 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á modificado se um aplicativo modificar arquivos de inicialização do componente do sistema, como Control.ini, System.inie 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 sem nome (mostrado como <Nenhum Nome>) que especificará 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 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.
- Verifique se nenhum arquivo .ini do nome especificado existe no sistema.
- Verifique se há uma entrada de chave no registro que especifica o arquivo .ini. Essa entrada deve estar no caminho HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.
- Especifique um valor para esse .ini entrada de chave de arquivo que especifica uma seção. Ou seja, um aplicativo deve especificar um nome de seção, pois ele aparecerá em um arquivo .ini ou entrada do Registro. Aqui está um exemplo: [Minha Seção].
- Para arquivos do sistema, especifique o SYS para um valor adicionado.
- Para arquivos de aplicativo, especifique USR dentro do valor adicionado. Aqui está um exemplo: "Minha Seção: USR: Nome do Aplicativo\Seção". E, como a USR indica um mapeamento em HKEY_CURRENT_USER, o aplicativo também deve criar uma chave em HKEY_CURRENT_USER que especifica o nome do aplicativo listado no valor adicionado. Para o exemplo fornecido, isso seria "Nome do Aplicativo".
- Depois de seguir as etapas anteriores, um programa de instalação de aplicativo deve chamar WritePrivateProfileString com os três primeiros parâmetros definidos como NULL e o quarto parâmetro definido como o nome do arquivo INI. Por exemplo:
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" ); - Essa chamada faz com que o mapeamento de um arquivo .ini para o registro entre em vigor antes da próxima reinicialização do sistema. O sistema relê as informações de mapeamento na memória compartilhada. Um usuário não precisará reinicializar seu computador depois de instalar um aplicativo para que as invocações futuras do aplicativo vejam o mapeamento do arquivo .ini para o registro.
Exemplos
O código de exemplo a seguir ilustra as diretrizes anteriores e baseia-se em várias suposições:
- Há um aplicativo chamado Nome do Aplicativo.
- Esse aplicativo usa um arquivo .ini chamado AppName.ini.
- Há uma seção no arquivo .ini que queremos ter esta aparência:
[Section1] FirstKey = It all worked out okay. SecondKey = By golly, it works. ThirdKey = Another test. - O usuário não precisará reinicializar o sistema para que as invocações futuras do aplicativo vejam o mapeamento do arquivo .ini para o registro.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
int main()
{
TCHAR inBuf[80];
HKEY hKey1, hKey2;
DWORD dwDisposition;
LONG lRetCode;
TCHAR szData[] = TEXT("USR:App Name\\Section1");
// Create the .ini file key.
lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,
TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey1,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating appname.ini key (%d).\n", lRetCode);
return (0) ;
}
// Set a section value
lRetCode = RegSetValueEx ( hKey1,
TEXT("Section1"),
0,
REG_SZ,
(BYTE *)szData,
sizeof(szData));
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in setting Section1 value\n");
// Close the key
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Create an App Name key
lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,
TEXT("App Name"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey2,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating App Name key (%d).\n", lRetCode);
// Close the key
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Force the system to read the mapping into shared memory
// so that future invocations of the application will see it
// without the user having to reboot the system
WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );
// Write some added values
WritePrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("It all worked out OK."),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("SecondKey"),
TEXT("By golly, it works!"),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("ThirdKey"),
TEXT("Another test..."),
TEXT("appname.ini"));
// Test
GetPrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("Error: GPPS failed"),
inBuf,
80,
TEXT("appname.ini"));
_tprintf (TEXT("Key: %s\n"), inBuf);
// Close the keys
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
return(1);
}
Nota
O cabeçalho winbase.h define WritePrivateProfileString como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do 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 |