Compartilhar via

Função PcAddAdapterDevice (portcls.h)

  • Artigo

A função PcAddAdapterDevice adiciona um dispositivo adaptador à pilha de dispositivos WDM.

Sintaxe

PORTCLASSAPI NTSTATUS PcAddAdapterDevice(
  [in] PDRIVER_OBJECT   DriverObject,
  [in] PDEVICE_OBJECT   PhysicalDeviceObject,
  [in] PCPFNSTARTDEVICE StartDevice,
  [in] ULONG            MaxObjects,
  [in] ULONG            DeviceExtensionSize
);

Parâmetros

[in] DriverObject

Ponteiro para o objeto driver. Esse ponteiro é passado como um parâmetro para o manipulador AddDevice do adaptador. O objeto driver é uma estrutura do sistema do tipo DRIVER_OBJECT.

[in] PhysicalDeviceObject

Ponteiro para o PDO (objeto de dispositivo físico) do dispositivo. PortCls passa esse ponteiro como um parâmetro de chamada para o manipulador AddDevice do adaptador. O PDO é uma estrutura do sistema do tipo DEVICE_OBJECT.

[in] StartDevice

Ponteiro para a função que o sistema operacional chama para iniciar o dispositivo. Para obter mais informações, consulte a seção Comentários a seguir.

[in] MaxObjects

Especifica o número máximo de subdispositivos a serem registrados por chamadas para PcRegisterSubdevice. Essa contagem define o limite superior para o número total de objetos de miniport que o driver do adaptador pode instanciar.

[in] DeviceExtensionSize

Especifica o tamanho da extensão do dispositivo. Use zero para o tamanho padrão. Consulte a seção Comentários a seguir para obter tamanhos de extensão fornecidos pelo usuário.

Retornar valor

PcAddAdapterDevice retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.

Comentários

Essa função faz a maior parte do trabalho que o manipulador AddDevice do driver do adaptador de áudio precisa executar. PcAddAdapterDevice cria o objeto de dispositivo, inicializa o contexto do dispositivo e anexa o objeto do dispositivo à pilha do dispositivo.

Um driver de adaptador chama PcAddAdapterDevice quando recebe uma chamada para seu manipulador AddDevice . O driver do adaptador normalmente instala o manipulador AddDevice chamando PcInitializeAdapterDriver, embora o driver também possa instalar o manipulador por outros meios. PcAddAdapterDevice cria o FDO (objeto de dispositivo funcional) para o PDO que foi passado para o manipulador AddDevice .

DeviceExtensionSize normalmente é zero. Alguns drivers de adaptador podem precisar reservar espaço adicional na extensão do dispositivo, nesse caso, eles devem especificar um DeviceExtensionSize maior que PORT_CLASS_DEVICE_EXTENSION_SIZE, que é o tamanho padrão. Qualquer valor maior que zero e menor que PORT_CLASS_DEVICE_EXTENSION_SIZE é ilegal. Os drivers do adaptador são livres para usar qualquer parte da extensão do dispositivo após o deslocamento PORT_CLASS_DEVICE_EXTENSION_SIZE. Eles também são livres para usar bytes no intervalo de deslocamento de 16 a 31 inclusive em um sistema com endereçamento de 32 bits e bytes no intervalo de deslocamento de 32 a 63 em um sistema com endereçamento de 64 bits. Se a extensão for considerada uma matriz de ULONG_PTR, os elementos de matriz de quatro a sete estarão disponíveis para uso pelo driver do adaptador.

O parâmetro StartDevice aponta para uma função do tipo PCPFNSTARTDEVICE, que o arquivo de cabeçalho portcls.h define como:

  NTSTATUS
    (*PCPFNSTARTDEVICE)(
      IN PDEVICE_OBJECT  DeviceObject,
      IN PIRP  Irp,
      IN PRESOURCELIST  ResourceList
      );

Para obter mais informações sobre PcAddAdapterDevice e as rotinas de inicialização de dispositivo e AddDevice do driver do adaptador, consulte Sequência de Inicialização.

O código de exemplo a seguir mostra como um driver de adaptador pode usar o parâmetro DeviceExtensionSize para acrescentar 64 bytes de dados de extensão específicos do dispositivo ao final do bloco de armazenamento que PortCls aloca para o contexto do dispositivo:

  #define MY_EXTENSION_SIZE  64
  NTSTATUS  ntstatus = PcAddAdapterDevice(DriverObject, PhysicalDeviceObject,
                                          MyStartDevice, MAX_MINIPORTS,
                                          MY_EXTENSION_SIZE + PORT_CLASS_DEVICE_EXTENSION_SIZE);

A chamada pcAddAdapterDevice acima é semelhante ao exemplo em Sequência de Inicialização, exceto que o último parâmetro passado para PcAddAdapterDevice é diferente de zero.

O driver do adaptador pode acessar os dados de extensão específicos do dispositivo, conforme mostrado no seguinte fragmento de código:

  PVOID  pMyExtensionData = (PVOID)((PCHAR)FunctionalDeviceObject->DeviceExtension +
                                              PORT_CLASS_DEVICE_EXTENSION_SIZE);

Variable FunctionalDeviceObject é um ponteiro para o FDO do adaptador de áudio e pMyExtensionData é um ponteiro temporário para os dados da extensão. Evite confundir o FDO com o PDO, que pertence ao driver de ônibus PCI. O driver do adaptador não deve modificar dados no PDO porque isso corrompe a memória de propriedade do driver de barramento PCI e pode causar uma falha no sistema.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível a partir do Windows 2000.
Plataforma de Destino Universal
Cabeçalho portcls.h (inclua Portcls.h)
Biblioteca Portcls.lib
IRQL PASSIVE_LEVEL

Confira também

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice