Función WritePrivateProfileStructA (winbase.h)
Copia los datos en una clave de la sección especificada de un archivo de inicialización. A medida que copia los datos, la función calcula una suma de comprobación y la anexa al final de los datos. La función GetPrivateProfileStruct usa la suma de comprobación para garantizar la integridad de los datos.
Sintaxis
BOOL WritePrivateProfileStructA(
[in] LPCSTR lpszSection,
[in] LPCSTR lpszKey,
[in] LPVOID lpStruct,
[in] UINT uSizeStruct,
[in] LPCSTR szFile
);
Parámetros
[in] lpszSection
Nombre de la sección a la que se copiará la cadena. Si la sección no existe, se creará. El nombre de la sección es independiente de mayúsculas y minúsculas, la cadena puede ser cualquier combinación de letras mayúsculas y minúsculas.
[in] lpszKey
Nombre de la clave que se va a asociar a una cadena. Si la clave no existe en la sección especificada, se crea. Si este parámetro es NULL, se elimina toda la sección, incluidas todas las claves y entradas de la sección.
[in] lpStruct
Datos que se van a copiar. Si este parámetro es NULL, se elimina la clave.
[in] uSizeStruct
Tamaño del búfer al que apunta el parámetro lpStruct , en bytes.
[in] szFile
Nombre del archivo de inicialización. Si este parámetro es NULL, la información se copia en el archivo Win.ini.
Si el archivo se creó con caracteres Unicode, la función escribe caracteres Unicode en el archivo. De lo contrario, la función escribe caracteres ANSI.
Valor devuelto
Si la función copia correctamente la cadena en el archivo de inicialización, el valor devuelto es distinto de cero.
Si se produce un error en la función o si vacía la versión almacenada en caché del archivo de inicialización al que se ha accedido más recientemente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Comentarios
Una sección del archivo de inicialización debe tener el siguiente formato:
[section]
key=string
.
.
.
Si el parámetro szFile no contiene una ruta de acceso completa y un nombre de archivo para el archivo, WritePrivateProfileString busca en el directorio de Windows el archivo. Si el archivo no existe, esta función crea el archivo en el directorio de Windows.
Si szFile contiene una ruta de acceso completa y un nombre de archivo y el archivo no existe, WriteProfileString crea el archivo. El directorio especificado ya debe existir.
El sistema mantiene una versión almacenada en caché de la asignación de archivos del Registro más reciente para mejorar el rendimiento. Si todos los parámetros son NULL, la función vacía la memoria caché. Mientras el sistema edita la versión almacenada en caché del archivo, los procesos que editan el propio archivo usarán el archivo original hasta que se haya borrado la memoria caché.
El sistema asigna la mayoría de .ini referencias de archivo 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 del componente del sistema, como Control.ini, System.ini y Winfile.ini. En este caso, la función escribe información en el Registro, no en el 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:
- Busque en el Registro el nombre del archivo de inicialización en la clave IniFileMapping .
- 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 subclave.
- 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.
- Si el nombre de sección especificado por lpAppName es una subclave, los valores con nombre de esa subclave especifican dónde en el registro encontrará las claves de la sección. Si la clave que está buscando no existe como un valor con nombre, habrá un valor sin nombre (mostrado como <Sin nombre>) que especifique la ubicación predeterminada en el registro donde encontrará la clave.
- 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 (mostrado como <Sin nombre>) que especifique la ubicación predeterminada en el registro donde encontrará las claves de la sección.
- 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.
- ! : este carácter obliga a todas las escrituras a ir tanto al Registro como 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 inicia 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.
Nota
El encabezado winbase.h define WritePrivateProfileStruct 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
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 (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |