AVC_FUNCTION_COMMAND

Artigo
06/15/2023

O código da função AVC_FUNCTION_COMMAND é usado para enviar uma solicitação AV/C e receber uma resposta como uma operação.

Bloco de Status de E/S

Se tiver êxito, o driver de protocolo AV/C definirá Irp-IoStatus.Status> como STATUS_SUCCESS.

Outros valores retornados possíveis incluem:

Valor Retornado	Descrição
STATUS_TIMEOUT	A solicitação foi feita, mas nenhuma resposta foi recebida antes de todo o tempo limite e o processamento de repetição foi concluído. O dispositivo de destino ignorará as solicitações se uma solicitação anterior ainda estiver sendo processada. Alguns dispositivos AV/C não estão em conformidade e se recusam a responder dentro do tempo limite de 100 ms, mesmo após várias tentativas sucessivas. A estrutura AVC_COMMAND_IRB permite o ajuste dos membros Timeout e Retries padrão (100ms e 9, respectivamente), mas essas configurações padrão foram suficientes para todas as implementações conhecidas.
STATUS_PENDING	A solicitação foi feita e uma resposta provisória foi recebida. É responsabilidade da rotina de conclusão lidar com a resposta final e liberar os recursos IRP e IRB.
STATUS_REQUEST_ABORTED	Ao enviar solicitações AV/C, anule imediatamente quando a status de conclusão do IRP for STATUS_REQUEST_ABORTED.
STATUS_*	Qualquer outro código de retorno indica que ocorreu um erro ou aviso que estava além do escopo do protocolo AV/C.

Comentários

Essa função usa a estrutura AVC_COMMAND_IRB conforme mostrado abaixo.

typedef struct _AVC_COMMAND_IRB {
  AVC_IRB  Common;
  UCHAR  SubunitAddrFlag : 1;
  UCHAR  AlternateOpcodesFlag : 1;
  UCHAR  TimeoutFlag : 1;
  UCHAR  RetryFlag : 1;
  union {
    UCHAR  CommandType;
    UCHAR  ResponseCode;
  };
  PUCHAR  SubunitAddr;
  PUCHAR  AlternateOpcodes;
  LARGE_INTEGER  Timeout;
  UCHAR  Retries;
  UCHAR  Opcode;
  ULONG  OperandLength;
  UCHAR  Operands[MAX_AVC_OPERAND_BYTES];
  NODE_ADDRESS  NodeAddress;
  ULONG  Generation;
} AVC_COMMAND_IRB, *PAVC_COMMAND_IRB;

Requisitos

Cabeçalhos: Declarado em avc.h. Inclua avc.h.

Entrada AVC_COMMAND_IRB

Comum
O submembro Function desse membro deve ser definido como AVC_FUNCTION_COMMAND da enumeração AVC_FUNCTION.

SubunitAddrFlag
Defina isso como um para substituir o endereço de subunidade que avc.sys associa ao driver de subunidade. Os motivos para substituir incluem: o driver de subunidade representa várias subunidades em uma única instância; um comando de unidade deve ser enviado; ou o driver foi carregado porque avc.sys não pôde determinar o tipo de subunidade ou a ID. Se isso for definido, o membro SubunitAddr deverá apontar para a memória nãopagada que contém o endereço de subunidade desejado.

Isso deve ser definido como um (e o SubunitAddr apropriado fornecido) se o chamador estiver enviando solicitações diretamente para um avc.sys FDO.

Observação

Se esse sinalizador não estiver definido na solicitação, na resposta de uma solicitação bem-sucedida, esse sinalizador será definido e o membro SubunitAddr apontará para o endereço real da subunidade. Não tente alterar o conteúdo ou liberar a memória: ele faz parte da extensão de dispositivo do driver pai. Isso pode, naturalmente, ser definido como zero e o ponteiro SubunitAddr limpo para reutilizar a estrutura para uma subunidade diferente.

AlternateOpcodesFlag Defina isso como um se o tipo de comando e o opcode dessa solicitação resultarem em uma resposta com um opcode diferente. Sem isso, somente as respostas com opcodes correspondentes são aceitas. Se isso for definido, o membro AlternateOpcodes deverá ser ponteiro para memória nãopagada que contém a lista de opcodes alternativos.

TimeoutFlag
Defina isso como um se o tempo limite padrão não for apropriado para a subunidade. Se isso for definido, o membro Timeout deverá ser definido como o tempo limite desejado (em unidades de 100 ns).

RetryFlag
Defina isso como um se a contagem de repetição padrão não for apropriada para a subunidade. Se isso for definido, o membro Retries deverá ser definido como a contagem de repetição desejada.

Commandtype Na solicitação, esse membro deve ser definido como um dos enumeradores da enumeração AvcCommandType . Esse é um parâmetro necessário.

ResponseCode Na resposta, esse membro é definido como um valor da enumeração AvcResponseCode .

SubunitAddr
Defina isso como o endereço da memória nãopagada que contém o endereço de subunidade desejado codificado de acordo com a Seção 5.3.3 da Especificação Geral do Conjunto de Comandos da Interface Digital AV/C da Associação Comercial 1394, Rev 3.0. Nenhum comprimento é necessário porque a codificação de endereço de subunidade implica isso. Esse parâmetro será ignorado se SubunitAddrFlag for zero.

AlternateOpcodes Defina isso como o endereço da memória nãopagada que contém a lista de opcode alternativa desejada. O primeiro byte da lista opcode é a contagem de opcodes a seguir (equivalente ao número de bytes). O comprimento total da memória que contém a lista opcode alternativa é AlternateOpcodes[0]+1. Esse parâmetro será ignorado se AlternateOpcodesFlag for zero.

Tempo Limite
Defina isso como o tempo limite desejado em unidades de 100 ns. Por exemplo, o valor de tempo limite padrão é: Timeout.QuadPart = 1000000 (100ms em unidades de 100ns). Esse parâmetro será ignorado se TimeoutFlag for zero.

Tentativas Defina isso como o número desejado de vezes avc.sys deve tentar repetir solicitações após cada tempo limite sem uma resposta. Observe que uma contagem de repetição de zero significa que a solicitação é tentada uma vez. A quantidade total de tempo gasto tentando processar um comando sem obter uma resposta é calculada pela seguinte fórmula:

Tempo limite * (Repetições+ 1)

Esse parâmetro será ignorado se RetryFlag for zero.

Opcode Defina isso como o opcode AV/C desejado (apropriado para o tipo de subunidade). Esse é um parâmetro necessário. Na resposta, se AlternateOpcodesFlag foi definido e um dos opcodes alternativos foi usado para corresponder à resposta, isso é definido como esse opcode alternativo.

OperandLength
Defina isso como o número de bytes usados para armazenar os operandos no membro Operandos . Esse é um parâmetro necessário. Na resposta, esse parâmetro é definido como o número de bytes na lista de operandos usada pela resposta.

Operandos
Defina isso como a lista de operandos apropriada para o tipo de subunidade e opcode. Esse é um parâmetro necessário. Na resposta, esse parâmetro contém a lista de operandos da resposta.

NodeAddress Reservados. Isso deve ser zero.

Generation
Reservado. Isso deve ser zero.

O código da função AVC_FUNCTION_COMMAND não é compatível com instâncias virtuais do avc.sys. Se o chamador quiser controlar um dispositivo externo, a instância não virtual desse dispositivo poderá ser localizada por meio de um mecanismo privado ou por meio de alguma combinação dos códigos de função AVC_FUNCTION_FIND_PEER_DO, AVC_FUNCTION_PEER_DO_LIST e AVC_FUNCTION_GET_SUBUNIT_INFO do código de controle de E/S do IOCTL_AVC_CLASS.

Essa estrutura define os componentes comuns de uma solicitação de comando AV/C. Ele contém o opcode e os operandos de uma solicitação e o opcode e os operandos de uma resposta (após a conclusão). O tamanho da lista de operandos é fixo no número máximo permitido de operandos dado um endereço de subunidade de um byte. Se o endereço de subunidade for estendido de alguma forma, o número máximo permitido de bytes de operando será reduzido adequadamente.

O uso recomendado dessa estrutura é primeiro zero da estrutura (use RtlZeroMemory) antes de preencher os parâmetros.

Isso deve ser chamado em IRQL = PASSIVE_LEVEL.