Función GetPrivateProfileSectionW (winbase.h)

Recupera todas las claves y valores de la sección especificada de un archivo de inicialización.

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

 

Sintaxis

DWORD GetPrivateProfileSectionW(
  [in]  LPCWSTR lpAppName,
  [out] LPWSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCWSTR lpFileName
);

Parámetros

[in] lpAppName

Nombre de la sección del archivo de inicialización.

[out] lpReturnedString

Puntero a un búfer que recibe los pares de nombre de clave y valor asociados a la sección con nombre. El búfer se rellena con una o varias cadenas terminadas en NULL; la última cadena va seguida de un segundo carácter NULL.

[in] nSize

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

El tamaño máximo de sección de perfil es de 32 767 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 especifica el número de caracteres copiados en el búfer, no incluido el carácter nulo de terminación. Si el búfer no es lo suficientemente grande como para contener todos los pares de nombre de clave y valor asociados a la sección con nombre, el valor devuelto es igual a nSize menos dos.

Observaciones

Los datos del búfer a los que apunta el lpReturnedString parámetro constan de una o varias cadenas terminadas en NULL, seguidas de un carácter NULO final. Cada cadena tiene el formato siguiente:

de cadena dede clave

La función GetPrivateProfileSection no distingue mayúsculas de minúsculas; la cadena a la que apunta el parámetro lpAppName puede ser una combinación de letras mayúsculas y minúsculas.

Esta operación es atómica; no se permiten actualizaciones del archivo de inicialización especificado mientras se copian los pares de nombre de clave y valor de la sección en el búfer al que apunta el parámetro lpReturnedString.

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

Esta asignación es probable si una aplicación modifica los archivos de inicialización de componentes del sistema, como Control.ini, System.iniy 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 localizar la 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. Este será 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. 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 la 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 en el 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_USERy 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.

Los comentarios (cualquier línea que comienza con un punto y coma) se quitan y no se devuelven en el búfer de lpReturnedString.

Nota

El encabezado winbase.h define GetPrivateProfileSection como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winbase.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll

Consulte también

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection