Função WritePrivateProfileStringA (winbase.h)
Copia uma cadeia de caracteres na 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 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] 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 dentro da seção, será excluída.
[in] lpString
Uma cadeia de caracteres terminada em nulo 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 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 será diferente de zero.
Se a função falhar ou se 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.
Comentários
Uma seção no arquivo de inicialização deve ter o seguinte formato:
[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 arquivo no diretório do Windows. 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 .ini referências de arquivo 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 de 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 nessa 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 sem nome (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 especifica o local padrão no registro em que você encontrará as chaves da seção.
- Se não houver 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 fizer logon pela primeira vez após a instalação.
- @ – esse caractere impede que as leituras acessem o arquivo de .ini no 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.
- 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, como seria exibido em um arquivo de .ini ou entrada do Registro. Aqui está um exemplo: [Minha Seção].
- Para arquivos do sistema, especifique 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 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 agregado. 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 o computador depois de instalar um aplicativo para que 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 se baseia 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 desejamos 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);
}
Observação
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 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 (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |