Función ExGetFirmwareEnvironmentVariable (wdm.h)
La rutina ExGetFirmwareEnvironmentVariable obtiene el valor de la variable de entorno del firmware del sistema especificada.
Sintaxis
NTSTATUS ExGetFirmwareEnvironmentVariable(
[in] PUNICODE_STRING VariableName,
[in] LPGUID VendorGuid,
[out, optional] PVOID Value,
[in, out] PULONG ValueLength,
[out, optional] PULONG Attributes
);
Parámetros
[in] VariableName
Puntero a una estructura de UNICODE_STRING que contiene el nombre de la variable de entorno especificada.
[in] VendorGuid
Puntero a un GUID que identifica al proveedor asociado a la variable de entorno especificada. Las variables de entorno se agrupan en espacios de nombres en función de sus GUID de proveedor. Es posible que algunas plataformas de hardware no admitan GUID de proveedor. En estas plataformas, todas las variables se agrupan en un solo espacio de nombres común y se omite el parámetro VendorGuid .
[out, optional] Value
Puntero a un búfer asignado por el autor de la llamada al que la rutina escribe el valor de la variable de entorno especificada.
[in, out] ValueLength
Puntero a una ubicación que contiene el tamaño del búfer. En la entrada, la ubicación a la que apunta este parámetro contiene el tamaño, en bytes, del búfer value proporcionado por el autor de la llamada. Antes de salir, la rutina escribe en esta ubicación el tamaño, en bytes, del valor de la variable. Si la rutina devuelve STATUS_SUCCESS, el valor de salida *ValueLength es el número de bytes de datos escritos en el búfer Valor . Si la rutina devuelve STATUS_BUFFER_TOO_SMALL, *ValueLength es el tamaño de búfer necesario.
[out, optional] Attributes
Puntero a una ubicación en la que la rutina escribe los atributos de la variable de entorno especificada. Este parámetro es opcional y se puede establecer en NULL si el autor de la llamada no necesita los atributos. Para obtener más información, vea la sección Comentarios.
Valor devuelto
ExGetFirmwareEnvironmentVariable devuelve STATUS_SUCCESS si se realiza correctamente. Los valores devueltos posibles incluyen los siguientes códigos de estado de error.
| Código devuelto | Descripción |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Los recursos del sistema disponibles no son suficientes para completar la operación solicitada. |
| STATUS_BUFFER_TOO_SMALL | El búfer valor es demasiado pequeño. |
| STATUS_VARIABLE_NOT_FOUND | La variable solicitada no existe. |
| STATUS_INVALID_PARAMETER | Uno de los parámetros no es válido. |
| STATUS_NOT_IMPLEMENTED | Esta rutina no se admite en esta plataforma. |
| STATUS_UNSUCCESSFUL | El firmware devolvió un error no reconocido. |
Comentarios
Las variables de entorno de firmware del sistema contienen valores de datos que se pasan entre el entorno de firmware de arranque implementado en la plataforma de hardware y los cargadores del sistema operativo y otro software que se ejecuta en el entorno de firmware.
El conjunto de variables de entorno de firmware que está disponible en una plataforma de hardware depende del firmware de arranque. El firmware también especifica la ubicación de estas variables de entorno. Por ejemplo, en una plataforma basada en UEFI, NVRAM contiene variables de entorno de firmware que especifican la configuración de arranque del sistema. Para obtener información sobre variables específicas usadas, vea Unified Extensible Firmware Interface Specification en el sitio web de UEFI . Para obtener más información sobre UEFI y Windows, consulte UEFI y Windows.
Las variables de entorno de firmware no se admiten en una plataforma heredada basada en BIOS. Las llamadas a ExGetFirmwareEnvironmentVariable siempre producen un error en una plataforma heredada basada en BIOS; También producen un error si Windows se instaló con el BIOS heredado en una plataforma que admite bios heredado y UEFI. Para identificar estas condiciones, use primero uuidgen o una herramienta similar para generar un GUID único aleatorio estáticamente. A continuación, llame a esta rutina para buscar un nombre de variable específico, proporcionando ese GUID como parámetro VendorGuid .
En una plataforma heredada basada en BIOS, o en una plataforma que admita BIOS heredado y UEFI, pero en la que Windows se instaló con el BIOS heredado, la función producirá un error con STATUS_NOT_IMPLEMENTED. En una plataforma basada en UEFI, se producirá un error específico del firmware, como STATUS_VARIABLE_NOT_FOUND, para indicar que el espacio de nombres GUID ficticio no existe.
Si el autor de la llamada especifica un parámetro Attributes distinto de NULL, la rutina escribe los atributos de la variable de entorno de firmware del sistema especificada en la ubicación a la que apunta Attributes. La versión 2.3.1 de la especificación UEFI define los siguientes atributos para las variables de entorno de firmware.
| Nombre de la variable | Valor |
|---|---|
| EFI_VARIABLE_NON_VOLATILE | 0x00000001 |
| EFI_VARIABLE_BOOTSERVICE_ACCESS | 0x00000002 |
| EFI_VARIABLE_RUNTIME_ACCESS | 0x00000004 |
| EFI_VARIABLE_HARDWARE_ERROR_RECORD | 0x00000008 |
| EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS | 0x00000010 |
| EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS | 0x00000020 |
| EFI_VARIABLE_APPEND_WRITE | 0x00000040 |
Estos valores de atributo se definen como bits de marca. El valor escrito en la variable ULONG a la que apunta Attributes es cero o el OR bit a bit de uno o varios atributos de la tabla anterior. Para obtener más información, consulte la especificación UEFI en el sitio web de UEFI .
Si crea un almacén de datos de copia de seguridad, puede usar esta función para guardar toda la configuración de arranque de la plataforma para que se puedan restaurar llamando a la rutina ExSetFirmwareEnvironmentVariable si es necesario.
ExGetFirmwareEnvironmentVariable es el equivalente en modo kernel de la función GetFirmwareEnvironmentVariable de Win32.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible a partir de Windows 8. |
| Plataforma de destino | Universal |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
Consulte también
ExSetFirmwareEnvironmentVariable