EVT_SERCX_APPLY_CONFIG funzione di callback (sercx.h)

La funzione di callback dell'evento EvtSerCxApplyConfig indica al driver del controller seriale di applicare un elenco di impostazioni di configurazione all'hardware del controller seriale.

Sintassi

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

NTSTATUS EvtSercxApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

Parametri

[in] Device

Handle WDFDEVICE per l'oggetto dispositivo framework che rappresenta il controller seriale.

[in] ConnectionParameters

Puntatore alla struttura dei parametri di connessione. Questa funzione deve eseguire il cast di questo parametro nel tipo di puntatore appropriato, analizzare la struttura dei dati per ottenere le impostazioni di configurazione e applicare queste impostazioni all'hardware del controller seriale. La struttura dei parametri di connessione è definita dal fornitore della piattaforma hardware ed è opaca sia per l'estensione del framework seriale (SerCx) che per il sistema operativo.

Valore restituito

La funzione EvtSerCxApplyConfig restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, restituisce un codice di stato di errore appropriato.

Commenti

SerCx chiama questa funzione durante l'inizializzazione del controller seriale per assicurarsi che l'hardware sia in uno stato iniziale valido. Questa funzione viene inoltre chiamata ogni volta che un client invia una richiesta di controllo di I /O IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION al controller.

SerCx ottiene questi parametri di configurazione dal descrittore di risorse ACPI per il dispositivo del controller seriale. Il formato di dati usato dal firmware ACPI per archiviare queste impostazioni di configurazione deve essere lo stesso formato di dati previsto dal driver del controller seriale.

Quando un client invia una richiesta di IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION a una porta seriale gestita da SerCx, SerCx determina se il driver del controller seriale per la porta seriale supporta il callback EvtSerCxApplyConfig e se il descrittore di risorse ACPI per la porta seriale fornisce le impostazioni di connessione predefinite. In caso contrario, SerCx completa la richiesta con il codice di stato degli errori STATUS_NOT_SUPPORTED. In caso contrario, SerCx passa i parametri di connessione alla funzione di callback EvtSerCxApplyConfig del driver. Dopo aver restituito il callback, SerCx completa la richiesta e usa il valore restituito dal callback come codice di stato per la richiesta.

Se un driver del controller seriale deve ottenere i parametri di connessione predefiniti alla volta diversi da un callback EvtSerCxApplyConfig , il driver può chiamare il metodo SerCxGetConnectionParameters .

Per registrare una funzione di callback EvtSerCxApplyConfig , il driver deve chiamare il metodo SerCxInitialize .

Esempio

Il tipo di funzione per questo callback viene dichiarato in Sercx.h, come indicato di seguito.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Per definire una funzione di callback EvtSerCxApplyConfig denominata MyEvtSerCxApplyConfig, è prima necessario specificare una dichiarazione di funzione che l'sdV ( Static Driver Verifier ) e altri strumenti di verifica richiedono, come indicato di seguito.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

Implementare quindi la funzione di callback come indicato di seguito.

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

Per altre informazioni sui requisiti SDV per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver KMDF.

Nell'esempio di codice seguente viene illustrata un'implementazione parziale di una funzione EvtSerCxApplyConfig per un oggetto UART.

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1


//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

I tipi di puntatore PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PPNP_SERIAL_BUS_DESCRIPTOR nell'esempio di codice precedente vengono definiti nel file di intestazione Reshub.h.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	sercx.h
IRQL	Chiamata in IRQL <= DISPATCH_LEVEL

Vedi anche

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize