Compartir a través de


Función GetPrivateProfileString (winbase.h)

Recupera una cadena de la sección especificada en un archivo de inicialización.

Nota Esta función solo se proporciona por compatibilidad con aplicaciones basadas en Windows de 16 bits. Las aplicaciones deben almacenar información de inicialización en el Registro.
 

Sintaxis

DWORD GetPrivateProfileString(
  [in]  LPCTSTR lpAppName,
  [in]  LPCTSTR lpKeyName,
  [in]  LPCTSTR lpDefault,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

Parámetros

[in] lpAppName

Nombre de la sección que contiene el nombre de la clave. Si este parámetro es NULL, la función GetPrivateProfileString copia todos los nombres de sección del archivo en el búfer proporcionado.

[in] lpKeyName

Nombre de la clave cuya cadena asociada se va a recuperar. Si este parámetro es NULL, todos los nombres de clave de la sección especificada por el parámetro lpAppName se copian en el búfer especificado por el parámetro lpReturnedString .

[in] lpDefault

Cadena predeterminada. Si no se encuentra la clave lpKeyName en el archivo de inicialización, GetPrivateProfileString copia la cadena predeterminada en el búfer lpReturnedString .

Si este parámetro es NULL, el valor predeterminado es una cadena vacía, "".

Evite especificar una cadena predeterminada con caracteres en blanco finales. La función inserta un carácter null en el búfer lpReturnedString para quitar los espacios en blanco finales.

[out] lpReturnedString

Puntero al búfer que recibe la cadena recuperada.

[in] nSize

Tamaño del búfer al que apunta el parámetro lpReturnedString , en caracteres.

[in] lpFileName

Nombre del archivo de inicialización. Si este parámetro no contiene una ruta de acceso completa al archivo, el sistema busca el archivo en el directorio de Windows.

Valor devuelto

El valor devuelto es el número de caracteres copiados en el búfer, sin incluir el carácter nulo de terminación.

Si lpAppName ni lpKeyName son NULL y el búfer de destino proporcionado es demasiado pequeño para contener la cadena solicitada, la cadena se trunca y va seguida de un carácter nulo y el valor devuelto es igual a nSize menos uno.

Si lpAppName o lpKeyName es NULL y el búfer de destino proporcionado es demasiado pequeño para contener todas las cadenas, la última cadena se trunca y va seguida de dos caracteres NULL . En este caso, el valor devuelto es igual a nSize menos dos.

En caso de que no se encuentre el archivo de inicialización especificado por lpFileName o contenga valores no válidos, al llamar a GetLastError se devolverá "0x2" (archivo no encontrado). Para recuperar información de error extendida, llame a GetLastError.

Comentarios

La función GetPrivateProfileString busca en el archivo de inicialización especificado una clave que coincida con el nombre especificado por el parámetro lpKeyName en el encabezado de sección especificado por el parámetro lpAppName . Si encuentra la clave, la función copia la cadena correspondiente en el búfer. Si la clave no existe, la función copia la cadena de caracteres predeterminada especificada por el parámetro lpDefault . Una sección del archivo de inicialización debe tener el siguiente formato:

[section]
key=string
      .
      .
      .

Si lpAppName es NULL, GetPrivateProfileString copia todos los nombres de sección del archivo especificado en el búfer proporcionado. Si lpKeyName es NULL, la función copia todos los nombres de clave de la sección especificada en el búfer proporcionado. Una aplicación puede usar este método para enumerar todas las secciones y claves de un archivo. En cualquier caso, cada cadena va seguida de un carácter NULO y la cadena final va seguida de un segundo carácter NULO . Si el búfer de destino proporcionado es demasiado pequeño para contener todas las cadenas, la última cadena se trunca y va seguida de dos caracteres NULL .

Si la cadena asociada a lpKeyName se incluye entre comillas simples o dobles, las marcas se descartan cuando la función GetPrivateProfileString recupera la cadena.

La función GetPrivateProfileString no distingue mayúsculas de minúsculas; las cadenas pueden ser una combinación de letras mayúsculas y minúsculas.

Para recuperar una cadena del archivo Win.ini, use la función GetProfileString .

El sistema asigna la mayoría de .ini referencias de archivo al registro, utilizando la asignación definida en la siguiente clave del Registro:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping

Esta asignación es probable que si una aplicación modifica los archivos de inicialización del componente del sistema, como Control.ini, System.ini y Winfile.ini. En estos casos, la función recupera información del Registro, no del archivo de inicialización; el cambio en la ubicación de almacenamiento no tiene ningún efecto en el comportamiento de la función.

Las funciones de perfil usan los pasos siguientes para buscar información de inicialización:

  1. Busque en el Registro el nombre del archivo de inicialización en la clave IniFileMapping .
  2. Busque el nombre de sección especificado por lpAppName. Se trata de un valor con nombre bajo la clave que tiene el nombre del archivo de inicialización, o una subclave con este nombre, o bien el nombre no existirá como un valor o una subclave.
  3. Si el nombre de sección especificado por lpAppName es un valor con nombre, ese valor especifica dónde en el Registro encontrará las claves de la sección.
  4. Si el nombre de sección especificado por lpAppName es una subclave, los valores con nombre de esa subclave especifican dónde encontrará las claves de la sección en el Registro. Si la clave que busca no existe como un valor con nombre, habrá un valor sin nombre (que se muestra como <Sin nombre>) que especifica la ubicación predeterminada en el Registro donde encontrará la clave.
  5. Si el nombre de sección especificado por lpAppName no existe como un valor con nombre o como una subclave, habrá un valor sin nombre (que se muestra como <Sin nombre>) que especifica la ubicación predeterminada en el Registro donde encontrará las claves de la sección.
  6. Si no hay ninguna subclave o entrada para el nombre de sección, busque el archivo de inicialización real en el disco y lea su contenido.
Al examinar los valores del Registro que especifican otras ubicaciones del Registro, hay varios prefijos que cambian el comportamiento de la asignación de archivos .ini:
  • ! : este carácter obliga a todas las escrituras a ir al registro y al archivo .ini en el disco.
  • # : este carácter hace que el valor del Registro se establezca en el valor del archivo de .ini de Windows 3.1 cuando un nuevo usuario inicie sesión por primera vez después de la instalación.
  • @ : este carácter impide que las lecturas vayan al archivo .ini en el disco si los datos solicitados no se encuentran en el registro.
  • USR: : este prefijo significa HKEY_CURRENT_USER y el texto después del prefijo es relativo a esa clave.
  • SYS: : este prefijo significa HKEY_LOCAL_MACHINE\SOFTWAREy el texto después del prefijo es relativo a esa clave.

Ejemplo

En el ejemplo siguiente se muestra el uso de GetPrivateProfileString.

// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado winbase.h (incluye Windows.h)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

GetProfileString

WritePrivateProfileString