SerCxDeviceInitConfig, fonction (sercx.h)

Article
03/01/2024

La méthode SerCxDeviceInitConfig est appelée par le pilote de contrôleur série pour attacher l’extension d’infrastructure série (SerCx) au pipeline d’E/S d’un objet de périphérique d’infrastructure (FDO ou PDO) qu’il crée.

Syntaxe

NTSTATUS SerCxDeviceInitConfig(
  [in, out] PWDFDEVICE_INIT DeviceInit
);

Paramètres

[in, out] DeviceInit

Pointeur vers la structure WDFDEVICE_INIT qui doit être configurée.

Valeur retournée

SerCxDeviceInitConfig retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent le code status suivant.

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer des ressources système (généralement de la mémoire).

Remarques

Cette méthode associe les informations de configuration de SerCx à la structure WDFDEVICE_INIT de l’objet d’appareil d’infrastructure (PDO ou FDO) qui doit être créé. Appelez SerCxDeviceInitConfig avant d’appeler la méthode WdfDeviceCreate pour créer l’objet d’appareil.

La fonction de rappel EvtDriverDeviceAdd du pilote du contrôleur reçoit un pointeur vers une structure WDFDEVICE_INIT initialisée en tant que paramètre d’entrée.

SerCx définit un descripteur de sécurité par défaut que le pilote de contrôleur série peut, si nécessaire, remplacer. Par exemple, ce descripteur de sécurité par défaut permet à un pilote en mode utilisateur d’envoyer une demande d’E/S à un périphérique connecté à un port sur le contrôleur série. Pour modifier ce paramètre dans le descripteur de sécurité, le pilote du contrôleur série peut appeler la méthode WdfDeviceInitAssignSDDLString . Cet appel doit se produire après l’appel SerCxDeviceInitConfig , mais avant l’appel à la méthode WdfDeviceCreate .

Exemples

Dans l’exemple de code suivant, la fonction de rappel EvtDriverDeviceAdd d’un pilote de contrôleur transmet une structure de WDFDEVICE_INIT initialisée à la méthode SerCxDeviceInitConfig . L’appel à SerCxDeviceInitConfig doit se produire avant l’appel WdfDeviceCreate qui crée le FDO pour l’appareil de contrôleur série (UART).

//
// FxDeviceInit is a pointer to an initialized WDFDEVICE_INIT structure.
// Drivers receive a pointer to this structure as an input parameter to an
// EvtDriverDeviceAdd callback function, or as a return value from the
// WdfControlDeviceInitAllocate method.
//

status = SerCxDeviceInitConfig(FxDeviceInit);

if (!NT_SUCCESS(status))
{
    return status;
}

// 
// Set WDF and SerCx device-level configuration options.
//

...

//
// Call the WdfDeviceCreate method.
//

...