RTL_RUN_ONCE_INIT_FN función de devolución de llamada (ntddk.h)
La rutina runOnceInitialization de realiza una operación de inicialización única.
Sintaxis
ULONG /* LOGICAL */
NTAPI
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
typedef RTL_RUN_ONCE_INIT_FN *PRTL_RUN_ONCE_INIT_FN;
Parámetros
[in, out] RunOnce
Puntero a la estructura de inicialización única RTL_RUN_ONCE que el controlador pasó previamente como parámetro a la rutina de RtlRunOnceExecuteOnce que llamó a esta rutina de RunOnceInitialization.
[in, out] Parameter
El valor Parameter que el controlador pasó a la rutina de RtlRunOnceExecuteOnce que llamó a esta rutina de RunOnceInitialization.
[out] Context
Puntero a una variable PVOID en la que la rutina escribe los datos de inicialización.
Valor devuelto
La rutina RunOnceInitialization devuelve un valor distinto de cero para indicar que se ha realizado correctamente y devuelve cero para indicar un error.
Observaciones
Un controlador implementado RunOnceInitialization rutina realiza la inicialización específica del controlador y, a continuación, escribe los datos de inicialización en la ubicación de memoria a la que apunta el parámetro context . Los controladores usan la rutina de de RtlRunOnceExecuteOnce para realizar una llamada única a una rutina de RunOnceInitialization. El sistema operativo garantiza que no se llama a la rutina runOnceInitialization de dos veces para el mismo valor del parámetro RunOnce.
El sistema operativo reserva un pequeño número de bits de orden bajo en la ubicación a la que apunta el parámetro Context. La rutina RunOnceInitial ization del controlador debe establecer estos bits reservados en cero en el valor de salida que escribe en *Context. La constante RTL_RUN_ONCE_CTX_RESERVED_BITS definida en Ntddk.h especifica el número de bits de orden bajo que están reservados. Actualmente, RTL_RUN_ONCE_CTX_RESERVED_BITS se define como dos, lo que significa que el controlador debe establecer los dos bits menos significativos del valor PVOID al que apunta Context en cero.
Ejemplos
Para definir un runOnceInitialization rutina de devolución de llamada, primero debe proporcionar una declaración de función que identifique el tipo de rutina de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.
Por ejemplo, para definir un RunOnceInitialization rutina de devolución de llamada denominada MyRunOnceInitialization, use el tipo RTL_RUN_ONCE_INIT_FN tal como se muestra en este ejemplo de código:
RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;
A continuación, implemente la rutina de devolución de llamada de la siguiente manera:
_Use_decl_annotations_
ULONG
MyRunOnceInitialization(
PRTL_RUN_ONCE RunOnce,
PVOID Parameter,
PVOID *Context
)
{
// Function body
}
El tipo de función RTL_RUN_ONCE_INIT_FN se define en el archivo de encabezado Wdm.h. Para identificar con mayor precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación _Use_decl_annotations_ a la definición de función. La anotación _Use_decl_annotations_ garantiza que se usen las anotaciones que se aplican al tipo de función RTL_RUN_ONCE_INIT_FN en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de rol de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, vea Anotación del comportamiento de la función.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Los controladores pueden implementar la rutina RunOnceInitialization solo en Windows Vista y versiones posteriores de Windows. |
| de la plataforma de destino de | Escritorio |
| encabezado de | ntddk.h (incluya Ntddk.h, Ntifs.h) |
| irQL | Se llama a irQL <= APC_LEVEL. |