IRP_MN_QUERY_DEVICE_RELATIONS

O gerenciador PnP envia essa solicitação para determinar determinadas relações entre dispositivos. Os seguintes tipos de drivers lidam com essa solicitação:

Os motoristas de ônibus devem lidar com BusRelations solicitações para seu adaptador ou controlador (barramento FDO). Os drivers de filtro podem lidar com solicitações de BusRelations.
Os motoristas de ônibus devem lidar com solicitações de TargetDeviceRelation para seus dispositivos filhos (PDOs filho).
Os drivers de função e filtro podem lidar com RemovalRelations e solicitações de PowerRelations.
Os motoristas de ônibus podem lidar com EjectionRelations solicitações para seus dispositivos filho (PDOs filho).

Valor

0x07

Código principal

IRP_MJ_PNP

Quando enviado

O gerenciador PnP envia esse IRP para coletar informações sobre dispositivos com uma relação com o dispositivo especificado.

O gerenciador PnP consulta a BusRelations de um dispositivo (dispositivos filho) quando o dispositivo é enumerado e em outros momentos enquanto o dispositivo está ativo, como quando um driver chama a rotinaIoInvalidateDeviceRelations para indicar que um dispositivo filho chegou ou partiu.

O gerenciador PnP consulta o RemovalRelations de de um dispositivo antes de remover os drivers de um dispositivo. O gerenciador PnP consulta RemovalRelations e EjectionRelations antes de ejetar um dispositivo.

O gerenciador PnP consulta o TargetDeviceRelation de um dispositivo quando um driver ou aplicativo de modo de usuário se registra para notificação PnP de um EventCategoryTargetDeviceChange no dispositivo. O gerenciador PnP consulta o dispositivo associado a um objeto de arquivo específico. IRP_MN_QUERY_DEVICE_RELATIONS é o único IRP PnP que tem um parâmetro de objeto de arquivo válido. Um driver pode consultar uma pilha de dispositivos para TargetDeviceRelation. Um driver não precisa fornecer um objeto de arquivo ao enviar seu consulta TargetDeviceRelation.

O gerenciador PnP consulta o PowerRelations de um dispositivo quando o driver do dispositivo chama IoInvalidateDeviceRelations para indicar que o conjunto de dispositivos com os quais esse dispositivo tem uma relação implícita de gerenciamento de energia foi alterado. solicitações de PowerRelations são suportadas a partir do Windows 7.

Para BusRelations, RemovalRelations, EjectionRelationse solicitações de PowerRelations, o gerente PnP envia IRP_MN_QUERY_DEVICE_RELATIONS em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Para solicitações de TargetDeviceRelation, o gerenciador PnP envia esse IRP em IRQL = PASSIVE_LEVEL em um contexto de thread arbitrário.

Parâmetros de entrada

O Parameters.QueryDeviceRelations.Type membro da estrutura IO_STACK_LOCATION especifica o tipo de relações que estão sendo consultadas. Os valores possíveis incluem BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelatione PowerRelations.

O FileObject membro da estrutura de IO_STACK_LOCATION atual aponta para um objeto de arquivo válido somente se Parameters.QueryDeviceRelations.Type estiver TargetDeviceRelation.

Parâmetros de saída

Retornado no bloco de status de E/S.

Bloco de status de E/S

Um driver define Irp->IoStatus.Status para STATUS_SUCCESS ou para um status de falha, como STATUS_INSUFFICIENT_RESOURCES.

No sucesso, um driver define Irp->IoStatus.Information para um ponteiro PDEVICE_RELATIONS que aponta para as informações de relações solicitadas. A estrutura DEVICE_RELATIONS é definida do seguinte modo:

typedef struct _DEVICE_RELATIONS {
  ULONG  Count;
  PDEVICE_OBJECT  Objects[1];  // variable length
} DEVICE_RELATIONS, *PDEVICE_RELATIONS;

Funcionamento

Se um driver retornar relações em resposta a esse IRP_MN_QUERY_DEVICE_RELATIONS, o driver alocará uma estrutura de DEVICE_RELATIONS da memória paginada que contém uma contagem e o número apropriado de ponteiros de objeto de dispositivo. O gestor PnP liberta a estrutura quando esta já não é necessária. Se um condutor substituir uma estrutura DEVICE_RELATIONS que outro condutor atribuiu, o condutor deve libertar a estrutura anterior.

Um driver deve fazer referência ao PDO de qualquer dispositivo que ele relata neste IRP (ObReferenceObject). O gerenciador PnP remove a referência quando apropriado.

Uma função ou driver de filtro deve estar preparado para lidar com esse IRP para um dispositivo a qualquer momento após sua rotina de AddDevice ter sido concluída para o dispositivo. Os motoristas de ônibus devem estar preparados para lidar com uma consulta para BusRelations imediatamente após um dispositivo ser enumerado.

Para obter as regras gerais sobre como lidar com IRPs menores Plug and Play consulte Plug and Play.

As subseções a seguir descrevem as ações específicas para lidar com as várias consultas.

Pedido de BusRelations

Quando o gerente PnP consulta as relações de barramento (dispositivos filho) de um adaptador ou controlador, o driver de barramento deve retornar uma lista de ponteiros para os PDOs de quaisquer dispositivos fisicamente presentes no barramento. O driver de barramento relata todos os dispositivos, independentemente de terem sido iniciados. O motorista do ônibus pode precisar ligar seu dispositivo de barramento para determinar quais crianças estão presentes.

Aviso Um objeto de dispositivo não pode ser passado para qualquer rotina que tome um DOP como argumento até que o gerenciador PnP crie um nó de dispositivo (devnode) para esse objeto. (Se o driver passar um objeto de dispositivo, o sistema irá verificar bugs com Bug Check 0xCA: PNP_DETECTED_FATAL_ERROR.) O gerenciador PnP cria o devnode em resposta à solicitação de IRP_MN_QUERY_DEVICE_RELATIONS. O driver pode presumir com segurança que o devnode do PDO foi criado quando recebe uma solicitação de IRP_MN_QUERY_RESOURCE_REQUIREMENTS.

O driver de barramento que responde a esse IRP é o driver de função para o adaptador de barramento ou controlador, não o driver de barramento pai para o barramento ao qual o adaptador ou controlador está conectado. Os drivers de função para dispositivos que não são de barramento não lidam com essa consulta. Esses motoristas apenas passam o IRP para o próximo motorista inferior. (Veja a figura a seguir.) Os drivers de filtro normalmente não lidam com essa consulta.

No Windows Vista e sistemas operacionais posteriores, recomendamos que os drivers sempre passem o IRP IRP_MN_QUERY_DEVICE_RELATIONS e concluam seu processamento mais tarde. Essa ordem permite que o sistema processe consultas de relação de barramento de forma assíncrona. (Em sistemas operacionais anteriores ao Windows Vista, os drivers podem retornar com segurança STATUS_PENDING de suas rotinas de despacho, mas o gerenciador PnP não sobrepõe a consulta de relação de barramento com nenhuma outra operação.)

O diagrama a seguir mostra como os drivers lidam com uma consulta para relações de barramento.

diagrama ilustrando os motoristas que lidam com uma consulta para relações de ônibus.

No exemplo mostrado na figura, o gerenciador PnP envia um IRP_MN_QUERY_DEVICE_RELATIONS para BusRelations para os drivers do dispositivo hub USB. O gerente PnP está solicitando uma lista dos filhos do dispositivo hub.

Como acontece com todos os IRPs PnP, o gerenciador PnP envia o IRP para o driver superior na pilha de dispositivos para o dispositivo.
Um driver de filtro opcional pode ser o driver superior na pilha. Um driver de filtro normalmente não lida com esse IRP; ele passa o IRP para baixo da pilha. Um driver de filtro pode manipular esse IRP, por exemplo, se o driver expõe um dispositivo não enumerável no barramento.
O driver do barramento de hub USB lida com o IRP.

O driver de barramento de hub USB:
- Cria uma DOP para qualquer dispositivo filho que ainda não tenha um.
- Marca o DOP inativo para qualquer dispositivo que não esteja mais presente no barramento. O driver de barramento não exclui esses PDOs.Para obter mais informações sobre quando excluir os PDOs, consulte Removendo um dispositivo.
- Relata quaisquer dispositivos filho que estejam presentes no barramento.
  
  Para cada dispositivo filho, o driver de barramento faz referência ao DOP e coloca um ponteiro para o DOP na estrutura DEVICE_RELATIONS.
  
  Há dois PDOs neste exemplo: um para o dispositivo joystick e outro para o dispositivo de teclado.
  
  O motorista do ônibus deve verificar se outro motorista já criou uma estrutura DEVICE_RELATIONS para este IRP. Em caso afirmativo, o motorista do ônibus deve adicionar às informações existentes.
  
  Se não houver nenhum dispositivo filho presente no barramento, o driver define a contagem como zero na estrutura de DEVICE_RELATIONS e retorna o sucesso.
- Define os valores apropriados no bloco de status de E/S e passa o IRP para o próximo driver inferior. O driver de barramento para o adaptador ou controlador não completa o IRP.
Um filtro inferior opcional, se presente, normalmente não manipula esse IRP. Tal driver de filtro passa o IRP para baixo da pilha. Se um driver de filtro inferior lida com esse IRP, ele pode adicionar DOP à lista de dispositivos filho, mas não deve excluir nenhum DOP criado por outros drivers.
O driver de barramento pai não manipula esse IRP, a menos que seja o único driver na pilha de dispositivos (o dispositivo está no modo bruto). Como acontece com todos os IRPs PnP, o driver de barramento pai completa o IRP com IoCompleteRequest.

Se houver um ou mais drivers de filtro de barramento na pilha de dispositivos, esses drivers podem manipular o IRP em seu caminho até o driver de barramento e/ou no caminho de volta do IRP para cima da pilha de dispositivos (se houver rotinas de IoComplete). De acordo com as regras de IRP PnP, tal driver pode adicionar PDOs ao IRP em seu caminho para baixo da pilha e/ou modificar a lista de relações no caminho de volta do IRP para cima da pilha (em rotinas de IoComplete).

Pedido de EjectionRelations

Um driver retorna ponteiros para PDOs de quaisquer dispositivos que possam ser fisicamente removidos do sistema quando o dispositivo especificado é ejetado. Não denuncie as DOP de crianças do dispositivo; o gerenciador PnP sempre solicita que os dispositivos filho sejam removidos antes do dispositivo pai.

O gerenciador PnP envia um IRP_MN_EJECT IRP para um dispositivo que está sendo ejetado. O driver para tal dispositivo também receber um IRP remover. As relações de ejeção do dispositivo recebem um IRP IRP_MN_REMOVE_DEVICE (não um IRP IRP_MN_EJECT).

Somente um driver de barramento pai pode responder a uma consulta EjectionRelations para um de seus dispositivos filho. Função e drivers de filtro devem passá-lo para o próximo driver inferior na pilha de dispositivos. Se um driver de barramento recebe este IRP como o driver de função para seu adaptador ou controlador, o driver de barramento está executando as tarefas de um driver de função e deve passar o IRP para o próximo driver inferior.

Pedido de PowerRelations

A partir do Windows 7, a consulta PowerRelations permite que um driver especifique uma relação de gerenciamento de energia fora da relação convencional entre um barramento pai que oferece suporte à enumeração PnP e um dispositivo filho enumerado no barramento. Por exemplo, se um driver de barramento não puder enumerar um dispositivo filho no barramento ou se um dispositivo for filho de mais de um barramento, a consulta PowerRelations poderá descrever as relações de energia do dispositivo filho com o barramento ou barramentos.

O gerenciador PnP emite uma consulta PowerRelations para um dispositivo quando o driver do dispositivo chama a rotinaIoInvalidateDeviceRelations e especifica um Tipo valor do parâmetro de PowerRelations.

Em resposta a esta consulta, o driver para o dispositivo de destino (ou seja, o dispositivo que é o destino para a consulta) fornece uma estrutura de DEVICE_RELATIONS que contém ponteiros para os PDOs de quaisquer outros dispositivos que devem ser ligados pelo gerenciador de energia antes que o dispositivo de destino seja ligado. Por outro lado, esses outros dispositivos devem ser desligados somente depois que o dispositivo alvo é desligado. O gerenciador de energia usa as informações da consulta para garantir que esses dispositivos sejam ligados e desligados na ordem correta.

Esta garantia de encomenda aplica-se apenas às transições globais do estado de suspensão do sistema, que incluem transições de e para os estados de energia do sistema S1, S2, S3 (de suspensão), S4 (de hibernação) e S5 (de encerramento). A garantia de pedido PowerRelations não se aplica às transições de estado de energia do dispositivo Dx enquanto o sistema permanece no estado do sistema S0 (em execução), exceto no caso das transições de DFx (Directed Runtime Power Management).

Se o dispositivo de destino estiver no caminho do dispositivo para um arquivo especial (como o arquivo de paginação, o arquivo de hibernação ou o arquivo de despejo de falha), o driver do dispositivo de destino deverá executar uma etapa adicional quando manipular um IRP de IRP_MN_DEVICE_USAGE_NOTIFICATION no qual do InPath é TRUE. Este driver deve garantir que os dispositivos cujos PDOs são fornecidos para o consulta PowerRelations também podem suportar estar no caminho do dispositivo para o arquivo especial. Para confirmar esse suporte, o driver para o dispositivo de destino deve primeiro enviar o IRP IRP_MN_DEVICE_USAGE_NOTIFICATION para cada um desses dispositivos, e esse IRP deve especificar o mesmo UsageNotification.Type que o dispositivo de destino. Somente se todos os dispositivos que recebem esse IRP completarem o IRP com um código de status de sucesso o driver do dispositivo de destino poderá concluir seu IRP IRP_MN_DEVICE_USAGE_NOTIFICATION com êxito. Caso contrário, este driver deve completar este IRP com um código de status de falha.

Quando esse mesmo driver manipula um IRP IRP_MN_DEVICE_USAGE_NOTIFICATION para o qual InPath é FALSO , o driver deve enviar o IRP IRP_MN_DEVICE_USAGE_NOTIFICATION para o mesmo conjunto de dispositivos dependentes como para o caso em que InPath é TRUE. No entanto, o driver nunca deve completar este IRP com um código de status de falha quando InPath estiver FALSE.

O driver que responde à consulta PowerRelations deve se registrar para notificações de alteração de dispositivo de destino em todos os dispositivos cujos PDOs são fornecidos para a consulta PowerRelations. Para se registrar para essas notificações, o driver pode chamar o IoRegisterPlugPlayNotification rotina e especificar um EventCategory valor do parâmetro de EventCategoryTargetDeviceChange.

Pedido de RemoçãoRelações

Um driver retorna ponteiros para PDOs de quaisquer dispositivos cujos drivers devem ser removidos quando os drivers para o dispositivo especificado são removidos. Não denuncie as DOP de crianças do dispositivo; o gerenciador PnP já solicita a remoção de dispositivos filho antes de remover um dispositivo.

A ordem pela qual as relações de remoção são removidas é indefinida.

Qualquer driver na pilha de dispositivos pode lidar com esse tipo de consulta de relações. Um driver de função ou filtro manipula o IRP antes de passá-lo para o próximo driver inferior. Um motorista de ônibus lida com o IRP e, em seguida, completa-o.

de solicitação TargetDeviceRelation

A consulta TargetDeviceRelation permite que o gerenciador PnP consulte uma pilha de dispositivos não-PnP para o PDO na pilha de dispositivos PnP que controla o hardware.

Em geral, os drivers encaminham o IRP IRP_MN_QUERY_DEVICE_RELATIONS para baixo em sua pilha até que o IRP atinja a parte inferior de uma pilha de dispositivos específica. Um driver na parte inferior de uma pilha não-PnP, em seguida, encaminha ou reemite o IRP para a pilha PnP relevante. Por exemplo, o gerenciador PnP pode enviar uma consulta TargetDeviceRelation para o objeto de dispositivo na parte superior da pilha do sistema de arquivos, que é uma pilha não-PnP. Cada objeto de dispositivo na pilha do sistema de arquivos passaria a consulta para o objeto de dispositivo abaixo dele até que a consulta alcançasse o objeto de dispositivo na parte inferior da pilha. O objeto de dispositivo mais baixo na pilha encaminharia ou reemitiria a consulta TargetDeviceRelation para o objeto de dispositivo na parte superior da pilha de volumes de armazenamento PnP e, em seguida, a consulta seria passada para o PDO na parte inferior da pilha de volumes de armazenamento.

A lista a seguir resume as situações em que você pode adquirir com segurança um ponteiro para o DOP na parte inferior de uma pilha de dispositivos PnP:

Objeto Device em um PnP

Um objeto de dispositivo que está em uma pilha de dispositivos PnP aprende sobre o PDO da pilha quando a rotina deAddDevice para o dispositivo é chamada. O driver pode armazenar o ponteiro em cache com segurança para o DOP se o uso do ponteiro estiver sincronizado corretamente com as mensagens de IRP_MN_REMOVE_DEVICE recebidas usando as rotinas de bloqueio de remoção.
Objeto de dispositivo em uma pilha não-PnP, não na parte inferior da pilha

Para um objeto de dispositivo que não está na parte inferior de uma pilha não-PnP, um driver pode enviar uma consulta de TargetDeviceRelation para obter um ponteiro para o PDO na parte inferior da pilha de dispositivos PnP correspondente.
Objeto de arquivo para o dispositivo

Dado um objeto de arquivo para o dispositivo, um driver pode chamar IoGetRelatedDeviceObject para obter o objeto de dispositivo e, em seguida, siga as instruções no item de lista anterior.
Manipular para o objeto do dispositivo

Dado um identificador para o objeto de dispositivo, um driver pode chamar ObReferenceObjectByHandle para obter o objeto de arquivo para o dispositivo e, em seguida, siga as instruções no item de lista anterior.

Um driver de barramento pai deve manipular uma consulta de relações de TargetDeviceRelation para seus dispositivos filho. O driver de barramento faz referência ao PDO do dispositivo filho com ObReferenceObject e retorna um ponteiro para o DOP na estrutura DEVICE_RELATIONS. Existe apenas um ponteiro DOP na estrutura para este tipo de relação. O gerenciador PnP remove a referência ao PDO quando o driver ou aplicativo cancela o registro para notificação no dispositivo.

Somente um driver de barramento pai responde a uma consulta TargetDeviceRelation. Função e drivers de filtro devem passá-lo para o próximo driver inferior na pilha de dispositivos. Se um driver de barramento recebe este IRP como o driver de função para seu adaptador ou controlador, o driver de barramento está executando as tarefas de um driver de função e deve passar o IRP para o próximo driver inferior.

Se um driver não estiver em uma pilha baseada em DOP, o driver enviará uma nova consulta IRP de relação de dispositivo de destino para o objeto de dispositivo associado ao identificador de arquivo no qual o driver executa E/S.

enviar este IRP

Os motoristas não devem enviar IRP_MN_QUERY_DEVICE_RELATIONS para solicitar BusRelations. Os drivers não estão impedidos de enviar este IRP para RemovalRelations ou EjectionRelations, mas não é provável que um driver o faça.

Os drivers podem consultar uma pilha de dispositivos para TargetDeviceRelation. Consulte Tratamento de IRPs para obter informações sobre como enviar IRPs. As seguintes etapas se aplicam especificamente a este IRP:

Defina os valores no próximo local da pilha de E/S do IRP: defina MajorFunction como IRP_MJ_PNP, defina MinorFunction como IRP_MN_QUERY_DEVICE_RELATIONS, defina Parameters.QueryDeviceRelations.Type como TargetDeviceRelatione defina > FileObject Irp-como um objeto de arquivo válido.
Inicialize IoStatus.Status para STATUS_NOT_SUPPORTED.

Se um driver enviou esse IRP para obter o PDO para relatar em resposta a um IRP_MN_QUERY_DEVICE_RELATIONS para TargetDeviceRelation que o driver recebeu, então o driver relata o PDO e libera a estrutura de relações retornadas quando o IRP for concluído. Se um driver iniciou este IRP por outro motivo, o driver libera a estrutura de relações quando o IRP é concluído e desreferencia o DOP quando ele não é mais necessário.