Commandes étendues par le fournisseur

Une application peut envoyer une commande arbitraire à l’appareil via la méthode IWiaItemExtras ::Escape, qui est décrite dans la documentation Microsoft Windows SDK. En appelant QueryInterface sur l’élément racine, vous pouvez récupérer un pointeur vers l’interface IWiaItemExtras . L’application peut ensuite construire une commande PTP à l’aide de n’importe quel opcode et de paramètres, et envoyer cette commande à l’appareil. L’application peut également envoyer des données à l’appareil ou en recevoir des données.

L’appareil informe l’application du résultat de l’opération lorsque la méthode IWiaItemExtras ::Escape retourne, en remplissant un code de réponse et des paramètres de réponse dans une structure PTP_VENDOR_DATA_OUT . Les membres SessionId et TransactionId de la structure PTP_VENDOR_DATA_IN sont ignorés. Le pilote fournit des valeurs correctes pour celles-ci.

Pour les commandes définies par le fournisseur autres que ESCAPE_PTP_CLEAR_STALLS, un indicateur spécial, ESCAPE_PTP_VENDOR_COMMAND, doit être combiné (à l’aide d’un opérateur OR) avec la commande utilisée dans la méthode IWiaItemExtras ::Escape . Si une commande définie par le fournisseur crée ou supprime un objet sur l’appareil à l’aide des indicateurs décrits ci-dessous, le pilote ajoute ou supprime l’objet de ses structures internes et génère un événement WIA. Toutes les autres commandes standard doivent être émises via l’interface WIA appropriée.

Le premier paramètre de IWiaItemExtras ::Escape est la combinaison d’un ou plusieurs des indicateurs suivants :

Lorsqu’une application appelle IWiaItemExtras ::Escape avec l’indicateur ESCAPE_PTP_CLEAR_STALL comme premier argument de cette méthode, le pilote émet la demande PTP Get Device Status pour déterminer si des points de terminaison sont dans une condition STALL. Si la commande Obtenir l’état du périphérique réussit, le pilote émet le code de contrôle USB IOCTL_RESET_PIPE pour chaque point de terminaison. Si la commande Obtenir l’état de l’appareil échoue, le pilote émet une demande de réinitialisation de périphérique PTP. L’obtention de l’état de l’appareil et la réinitialisation de l’appareil sont décrits dans la norme PIMA 15740 :2000, la première édition et la révision 1.0 de la définition de périphérique de capture d’images fixes USB (SICDD USB).

L’exemple de code suivant illustre l’utilisation de l’interface de commande étendue par le fournisseur. Assurez-vous que votre code inclut l’en-tête ptpusd.h , car il contient les définitions des codes d’échappement et d’autres constantes, ainsi que les structures PTP_VENDOR_DATA_IN et PTP_VENDOR_DATA_OUT . L’interface IWiaItemExtras est obtenue à l’aide d’un appel à QueryInterface sur l’élément racine. Un pointeur vers cet élément racine, pIWiaRootItem, peut être obtenu, par exemple, par un appel à IWiaDevMgr ::SelectDeviceDlg (décrit dans la documentation Microsoft Windows SDK).

//
// Test IWiaItemExtras::Escape method
//
HRESULT hr = S_OK;
IWiaItemExtras *pIWiaItemExtras = NULL;

hr = pIWiaRootItem->QueryInterface(IID_IWiaItemExtras,
                                   (VOID **) &pIWiaItemExtras);
if (FAILED(hr)) {
    MessageBox("QueryInterface for IWiaItemExtras failed");
    return;
}

PTP_VENDOR_DATA_IN *pDataIn = NULL;
PTP_VENDOR_DATA_OUT *pDataOut = NULL;
DWORD dwDataInSize = SIZEOF_REQUIRED_VENDOR_DATA_IN;
DWORD dwDataOutSize = SIZEOF_REQUIRED_VENDOR_DATA_OUT + 0x1000;
DWORD dwActualDataOutSize = 0;

pDataIn = (PTP_VENDOR_DATA_IN *) CoTaskMemAlloc(dwDataInSize);
if (!pDataIn) {
    MessageBox("CoTaskMemAlloc failed");
    return;
}

pDataOut = (PTP_VENDOR_DATA_OUT *) CoTaskMemAlloc(dwDataOutSize);
if (!pDataOut) {
 CoTaskMemFree(pDataIn);
    MessageBox("CoTaskMemAlloc failed");
    return;
}
ZeroMemory(pDataIn, dwDataInSize);
ZeroMemory(pDataOut, dwDataOutSize);

pDataIn->OpCode = 0x1001;
pDataIn->SessionId = 0;     // The driver will fill this in.
pDataIn->TransactionId = 0; // The driver will fill this in.
pDataIn->NumParams = 0;

//
// pDataIn->NextPhase informs the PTP driver whether to 
// read data from the device (as shown), or
// write data to the device (use PTP_NEXTPHASE_WRITE_DATA),
// to neither read nor write data (use PTP_NEXTPHASE_NO_DATA).
//
pDataIn->NextPhase = PTP_NEXTPHASE_READ_DATA;

hr = pIWiaItemExtras->Escape(ESCAPE_PTP_VENDOR_COMMAND,
                             (BYTE *) pDataIn, dwDataInSize,
                             (BYTE *) pDataOut, dwDataOutSize,
                             &dwActualDataOutSize);

if (FAILED(hr)) {
    MessageBox("Escape failed");
    return;
}

//
// Data returned from device is located at pDataOut->VendorReadData.
//