Função SerCx2InitializeDeviceInit (sercx.h)

Artigo
03/01/2024

O método SerCx2InitializeDeviceInit permite que a versão 2 da extensão de estrutura serial (SerCx2) registre propriedades específicas da extensão com a estrutura do driver durante a criação do objeto de dispositivo de estrutura para o controlador serial.

Sintaxe

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

Parâmetros

[in, out] DeviceInit

Um ponteiro para uma estrutura WDFDEVICE_INIT , que é uma estrutura opaca que armazena informações que o KMDF (Kernel Mode Driver Framework) usa para criar um objeto de dispositivo de estrutura. O driver do controlador serial recebe um ponteiro para essa estrutura como um parâmetro de entrada para a função de retorno de chamada EvtDriverDeviceAdd do driver.

Retornar valor

SerCx2InitializeDeviceInit retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis incluem os seguintes códigos de status.

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	O método foi chamado no IRQL errado ou o parâmetro DeviceInit é NULL.
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes estão disponíveis para executar a operação solicitada.

Comentários

O driver do controlador serial deve chamar esse método de sua função de retorno de chamada EvtDriverDeviceAdd antes de criar um objeto WDFDEVICE para o controlador serial.

SerCx2InitializeDeviceInit anexa informações específicas da extensão à estrutura de WDFDEVICE_INIT do driver. Essas informações permitem que o SerCx2 execute determinadas ações em nome do driver do controlador serial. Por exemplo, o SerCx2 recebe solicitações de E/S que os clientes enviam para o controlador serial.

O driver do controlador serial deve chamar SerCx2InitializeDeviceInit antes de criar um objeto de dispositivo de estrutura para representar o controlador serial e antes de chamar o método SerCx2InitializeDevice para concluir a inicialização do objeto do dispositivo. O driver chama um método como WdfDeviceCreate para criar o objeto do dispositivo.

SerCx2InitializeDeviceInit define um descritor de segurança padrão que permite que drivers no modo kernel e drivers de modo de usuário enviem solicitações de E/S para SerCx2. O descritor permite que os aplicativos enviem essas solicitações somente se forem executados com privilégios de administrador. Para especificar esse descritor, o SerCx2 usa a seguinte cadeia de caracteres SDDL:

"D:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;UD)" Se necessário, o driver do controlador serial pode substituir a configuração padrão chamando o método WdfDeviceInitAssignSDDLString com o descritor de segurança desejado. O driver deve chamar WdfDeviceInitAssignSDDLString depois de chamar SerCx2InitializeDeviceInit , mas antes de chamar WdfDeviceCreate. Para obter mais informações sobre cadeias de caracteres SDDL, consulte SDDL for Device Objects.