Função PcAddAdapterDevice (portcls.h)
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 de 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. O PortCls passa esse ponteiro como um parâmetro de chamada para o manipulador de 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 subdevices a serem registrados por chamadas para pcRegisterSubdevice. Essa contagem define o limite superior para o número total de objetos de miniporto 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 ver os tamanhos de extensão fornecidos pelo usuário.
Valor de retorno
PcAddAdapterDevice retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.
Observações
Essa função faz a maior parte do trabalho que o driver do adaptador de áudio addDevice manipulador precisa executar. PcAddAdapterDevice cria o objeto do 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 de objeto de dispositivo funcional (FDO) 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 gratuitos 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 de 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 o 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 de Sequência de Inicialização, exceto que o último parâmetro passado para pcAddAdapterDevice não é 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);
A variável FunctionalDeviceObject é um ponteiro para o FDO do adaptador de áudio e pMyExtensionData é um ponteiro temporário para os dados de extensão. Evite confundir o FDO com o PDO, que pertence ao motorista 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 ônibus PCI e pode causar uma falha no sistema.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 2000. |
| da Plataforma de Destino | Universal |
| cabeçalho | portcls.h (inclua Portcls.h) |
| biblioteca | Portcls.lib |
| IRQL | PASSIVE_LEVEL |