Função GetProfileStringA (winbase.h)

Recupera a cadeia de caracteres associada a uma chave na seção especificada do arquivo Win.ini.

Sintaxe

DWORD GetProfileStringA(
  [in]  LPCSTR lpAppName,
  [in]  LPCSTR lpKeyName,
  [in]  LPCSTR lpDefault,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize
);

Parâmetros

[in] lpAppName

O nome da seção que contém a chave. Se esse parâmetro for NULL, a função copiará todos os nomes de seção no arquivo para o buffer fornecido.

[in] lpKeyName

O nome da chave cuja cadeia de caracteres associada deve ser recuperada. Se esse parâmetro for NULL, a função copiará todas as chaves na seção fornecida para o buffer fornecido. Cada cadeia de caracteres é seguida por um caractere nulo e a cadeia de caracteres final é seguida por um segundo caractere nulo .

[in] lpDefault

Uma cadeia de caracteres padrão. Se a chave lpKeyName não puder ser encontrada no arquivo de inicialização, GetProfileString copiará a cadeia de caracteres padrão para o buffer lpReturnedString . Se esse parâmetro for NULL, o padrão será uma cadeia de caracteres vazia, "".

Evite especificar uma cadeia de caracteres padrão com caracteres em branco à direita. A função insere um caractere nulo no buffer lpReturnedString para remover quaisquer espaços em branco à direita.

[out] lpReturnedString

Um ponteiro para um buffer que recebe a cadeia de caracteres.

[in] nSize

O tamanho do buffer apontado pelo parâmetro lpReturnedString , em caracteres.

Retornar valor

O valor retornado é o número de caracteres copiados para o buffer, não incluindo o caractere de terminação nula.

Se nem lpAppName nem lpKeyName for NULL e o buffer de destino fornecido for muito pequeno para manter a cadeia de caracteres solicitada, a cadeia de caracteres será truncada e seguida por um caractere nulo e o valor retornado será igual a nSize menos um.

Se lpAppName ou lpKeyName for NULL e o buffer de destino fornecido for muito pequeno para manter todas as cadeias de caracteres, a última cadeia de caracteres será truncada e seguida por dois caracteres nulos . Nesse caso, o valor retornado é igual a nSize menos dois.

Comentários

Se a cadeia de caracteres associada ao parâmetro lpKeyName estiver entre aspas simples ou duplas, as marcas serão descartadas quando a função GetProfileString retornar a cadeia de caracteres.

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

Uma seção no arquivo Win.ini deve ter o seguinte formulário:

[section]
key=string
      .
      .
      .

Um aplicativo pode usar a função GetPrivateProfileString para recuperar uma cadeia de caracteres de um arquivo de inicialização especificado.

O parâmetro lpDefault deve apontar para uma cadeia de caracteres válida, mesmo que a cadeia de caracteres esteja vazia (ou seja, mesmo que seu primeiro caractere seja um caractere nulo ).

Windows Server 2003 e Windows XP/2000: As chamadas para funções de perfil podem ser mapeadas para o Registro em vez de para os arquivos de inicialização. Esse mapeamento ocorre quando o arquivo de inicialização e a seção são especificados no registro sob as seguintes chaves:

HKEY_LOCAL_MACHINE\Software\Microsoft\\ Windows NT CurrentVersion\IniFileMapping

Quando a operação foi mapeada, a função GetProfileString recupera informações do registro, não do 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.

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

Confira também

GetPrivateProfileString

Writeprofilestring