AVC_FUNCTION_COMMAND

Article
06/15/2023

Le code de la fonction AVC_FUNCTION_COMMAND est utilisé pour envoyer une requête AV/C et recevoir une réponse sous la forme d’une seule opération.

Bloc d’état E/S

En cas de réussite, le pilote de protocole AV/C définit Irp-IoStatus.Status> sur STATUS_SUCCESS.

Les autres valeurs de retour possibles sont les suivantes :

Valeur de retour	Description
STATUS_TIMEOUT	La demande a été effectuée, mais aucune réponse n’a été reçue avant l’expiration du délai d’attente et le traitement des nouvelles tentatives. L’appareil cible ignore les demandes si une requête précédente est toujours en cours de traitement. Certains appareils AV/C ne sont pas conformes et refusent de répondre dans le délai d’attente de 100 ms, même après plusieurs tentatives successives. La structure AVC_COMMAND_IRB permet d’ajuster les membres timeout et retries par défaut (100 ms et 9, respectivement), mais ces paramètres par défaut ont été suffisants pour toutes les implémentations connues.
STATUS_PENDING	La demande a été faite et une réponse provisoire a été reçue. Il incombe à la routine d’achèvement de gérer la réponse finale et de libérer les ressources IRP et IRB.
STATUS_REQUEST_ABORTED	Lors de l’envoi de demandes AV/C, abandonnez immédiatement lorsque le status d’achèvement IRP est STATUS_REQUEST_ABORTED.
STATUT_*	Tout autre code de retour indique qu’une erreur ou un avertissement s’est produit au-delà de la portée du protocole AV/C.

Commentaires

Cette fonction utilise la structure AVC_COMMAND_IRB comme indiqué ci-dessous.

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;

Spécifications

En-têtes: Déclaré dans avc.h. Incluez avc.h.

entrée AVC_COMMAND_IRB

Commun
Le sous-membre Function de ce membre doit être défini sur AVC_FUNCTION_COMMAND à partir de l’énumération AVC_FUNCTION.

Sous-unitéAddrFlag
Définissez cette valeur sur une pour remplacer l’adresse de sous-unité que avc.sys associe au pilote de sous-unité. Les raisons de remplacer incluent : le pilote de sous-unité représente plusieurs sous-unités dans un seul instance ; une commande d’unité doit être envoyée ; ou le pilote a été chargé car avc.sys n’a pas pu déterminer le type ou l’ID de sous-unité. Si cette valeur est définie, le membre SubunitAddr doit pointer vers la mémoire non paginée contenant l’adresse de sous-unité souhaitée.

Cette valeur doit être définie sur un (et la sous-unitéAddr appropriée fournie) si l’appelant envoie des demandes directement à un FDOavc.sys .

Notes

Si cet indicateur n’est pas défini à la demande, lors de la réponse d’une demande réussie, cet indicateur est défini et le membre SubunitAddr pointe vers l’adresse réelle de la sous-unité. N’essayez pas de modifier le contenu ou de libérer de la mémoire : elle fait partie de l’extension de périphérique du pilote parent. Cela peut, bien sûr, être rétabli à zéro, et le pointeur SubunitAddr effacé pour réutiliser la structure pour une autre sous-unité.

AlternateOpcodesFlag Définissez cette valeur sur une valeur si le type de commande et l’opcode de cette requête entraînent une réponse avec un opcode différent. Sans cela, seules les réponses avec des opcodes correspondants sont acceptées. Si cette option est définie, le membre AlternateOpcodes doit pointer vers la mémoire non paginé contenant la liste des opcodes alternatifs.

TimeoutFlag
Définissez cette valeur sur une valeur si le délai d’attente par défaut n’est pas approprié pour la sous-unité. Si ce paramètre est défini, le membre Timeout doit être défini sur le délai d’attente souhaité (en unités de 100 ns).

RetryFlag
Définissez cette valeur sur une valeur si le nombre de nouvelles tentatives par défaut n’est pas approprié pour la sous-unité. Si ce paramètre est défini, le membre Nouvelles tentatives doit être défini sur le nombre de nouvelles tentatives souhaité.

Commandtype Sur demande, ce membre doit être défini sur l’un des énumérateurs de l’énumération AvcCommandType . Il s’agit d’un paramètre obligatoire.

ResponseCode Lors de la réponse, ce membre est défini sur une valeur de l’énumération AvcResponseCode .

Sous-unitéAddr
Définissez cette valeur sur l’adresse de la mémoire non paginée contenant l’adresse de sous-unité souhaitée encodée conformément à la section 5.3.3 de la spécification générale de l’ensemble de commandes d’interface numérique AV/C av/C de l’association commerciale 1394, Rev 3.0. Aucune longueur n’est nécessaire, car l’encodage d’adresse de sous-unité l’implique. Ce paramètre est ignoré si SubunitAddrFlag est égal à zéro.

AlternateOpcodes Définissez cette valeur sur l’adresse de la mémoire non paginé contenant la liste d’opcodes de remplacement souhaitée. Le premier octet de la liste d’opcodes correspond au nombre d’opcodes à suivre (équivalent au nombre d’octets). La longueur totale de la mémoire contenant la liste d’opcodes alternatifs est AlternateOpcodes[0]+1. Ce paramètre est ignoré si AlternateOpcodesFlag est égal à zéro.

Délai d'expiration
Définissez cette valeur sur le délai d’attente souhaité en unités de 100 ns. Par exemple, la valeur de délai d’attente par défaut est : Timeout.QuadPart = 1000000 (100 ms dans 100ns unités). Ce paramètre est ignoré si TimeoutFlag est égal à zéro.

Tentatives Définissez ce paramètre sur le nombre souhaité de fois queavc.sys tentez de réessayer des demandes après chaque délai d’attente sans réponse. Notez qu’un nombre de nouvelles tentatives de zéro signifie que la demande est essayée une seule fois. Le temps total passé à essayer de traiter une commande sans obtenir de réponse est calculé selon la formule suivante :

Délai d’expiration * (nouvelles tentatives+ 1)

Ce paramètre est ignoré si RetryFlag est égal à zéro.

Opcode Définissez cette valeur sur le opcode AV/C souhaité (approprié pour le type de sous-unité). Il s’agit d’un paramètre obligatoire. Sur la réponse, si AlternateOpcodesFlag a été défini et que l’un des opcodes alternatifs a été utilisé pour faire correspondre la réponse, il est défini sur cet opcode alternatif.

OperandLength
Définissez cette valeur sur le nombre d’octets utilisés pour stocker les opérandes dans le membre Operands . Il s’agit d’un paramètre obligatoire. Sur la réponse, ce paramètre est défini sur le nombre d’octets dans la liste d’opérandes utilisée par la réponse.

Opérandes
Définissez cette valeur sur la liste d’opérandes appropriée pour le type de sous-unité et l’opcode. Il s’agit d’un paramètre obligatoire. Sur la réponse, ce paramètre contient la liste d’opérandes de la réponse.

NodeAddress Réservés au. Il doit être égal à zéro.

Generation
Réservé. Il doit être égal à zéro.

Le code de fonction AVC_FUNCTION_COMMAND n’est pas pris en charge par les instances virtuelles de avc.sys. Si l’appelant souhaite contrôler un appareil externe, les instance non virtuels de cet appareil peuvent être localisés via un mécanisme privé ou via une combinaison des codes de fonction AVC_FUNCTION_FIND_PEER_DO, AVC_FUNCTION_PEER_DO_LIST et AVC_FUNCTION_GET_SUBUNIT_INFO du code de contrôle d’E/S IOCTL_AVC_CLASS.

Cette structure définit les composants communs d’une demande de commande AV/C. Il contient l’opcode et les opérandes d’une requête, ainsi que l’opcode et les opérandes d’une réponse (à l’achèvement). La taille de la liste d’opérandes est fixée au nombre maximal autorisé d’opérandes en fonction d’une adresse de sous-unité d’un octet. Si l’adresse de sous-unité est étendue de quelque manière que ce soit, le nombre maximal autorisé d’octets d’opérandes est réduit en conséquence.

L’utilisation recommandée de cette structure est de commencer par zéro la structure (utilisez RtlZeroMemory) avant de remplir les paramètres.

Cela doit être appelé à l’adresse IRQL = PASSIVE_LEVEL.