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 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 |