Méthode IPortableDevice ::SendCommand (portabledeviceapi.h)

Article
03/06/2024

La méthode SendCommand envoie une commande à l’appareil et récupère les résultats de manière synchrone.

Syntaxe

HRESULT SendCommand(
  [in]  const DWORD           dwFlags,
  [in]  IPortableDeviceValues *pParameters,
  [out] IPortableDeviceValues **ppResults
);

Paramètres

[in] dwFlags

Actuellement non utilisé ; spécifiez zéro.

[in] pParameters

Pointeur vers une interface IPortableDeviceValues qui spécifie la commande et les paramètres à appeler sur l’appareil. Cette interface doit inclure les deux valeurs suivantes pour indiquer la commande . Les paramètres supplémentaires varient en fonction de la commande. Pour obtenir la liste des paramètres requis pour chaque commande, consultez Commandes.

Commande ou propriété	Description
WPD_PROPERTY_COMMON_COMMAND_CATEGORY	GUID de catégorie de la commande à envoyer. Par exemple, pour réinitialiser un appareil, vous devez envoyer WPD_COMMAND_COMMON_RESET_DEVICE.fmtid.
WPD_PROPERTY_COMMON_COMMAND_ID	PID de la commande à envoyer. Par exemple, pour réinitialiser un appareil, vous devez envoyer WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Adresse d’une variable qui reçoit un pointeur vers une interface IPortableDeviceValues qui indique les résultats des commandes, y compris la réussite ou l’échec, et toutes les valeurs de commande retournées par l’appareil. L’appelant doit libérer cette interface lorsqu’il a terminé avec elle. Les valeurs récupérées varient selon la commande ; Consultez la documentation appropriée sur les commandes dans Commandes pour savoir quelles valeurs sont retournées par chaque appel de commande.

Valeur retournée

La valeur retournée indique la réussite ou l’échec de l’envoi d’une commande et le retour d’un résultat à partir du pilote ; elle n’indique pas si le pilote prend en charge la commande ou s’il a rencontré une erreur lors du traitement de la commande. (Pour plus d’informations, consultez Remarques.) Ces erreurs sont retournées dans les valeurs HRESULT du paramètre ppResults . Les valeurs HRESULT possibles retournées par cette méthode incluent, sans s’y limiter, celles du tableau suivant.

Code de retour	Description
S_OK	La commande a été reçue avec succès par le pilote. Cela n’indique pas que la commande elle-même a réussi. Vous devez case activée ppResults pour déterminer la réussite ou l’échec de la commande.
E_POINTER	Au moins un des arguments était un pointeur NULL.

Remarques

Cette fonction est utilisée pour envoyer une commande directement au pilote. Une commande est une PROPRIÉTÉKEY qui est envoyée au pilote pour indiquer l’action attendue, ainsi qu’une liste de paramètres requis. Chaque commande a une liste de paramètres et de résultats obligatoires et facultatifs qui doivent être empaquetés avec la commande pour que le pilote puisse effectuer l’action demandée. Une liste de commandes définies par les appareils portables Windows, avec les paramètres et les valeurs de retour requis, est donnée dans Commandes.

La plupart des méthodes d’appareils portables Windows fonctionnent en envoyant une ou plusieurs commandes d’appareils portables Windows pour vous et en encapsulant les paramètres pour vous. Certaines commandes n’ont pas de méthodes d’appareils portables Windows correspondantes. La seule façon d’appeler ces commandes est d’utiliser SendCommand. Les commandes suivantes n’ont pas de méthode correspondante :

Vous devez également appeler SendCommand pour envoyer des commandes de pilote personnalisées.

Certaines commandes personnalisées peuvent nécessiter un niveau d’accès IOCTL (Input/Output Control Code) spécifique. Votre application définit ce niveau d’accès en appelant la méthode IPortableDeviceValues ::SetUnsignedIntegerValue sur les paramètres de commande qu’elle transmet à la méthode SendCommand . Par exemple, si une commande personnalisée nécessite un accès en lecture seule, vous devez appeler SetUnsignedIntegerValue et passer WPD_API_OPTION_IOCTL_ACCESS comme premier argument et FILE_READ_ACCESS comme deuxième argument. En mettant à jour ces paramètres de commande, votre application garantit que l’API Appareils portables Windows émet la commande avec l’IOCTL en lecture seule.

Les erreurs rencontrées par le pilote lors du traitement d’une commande sont récupérées par le paramètre ppResults , et non par la valeur de retour SendCommand . La valeur de retour de cette méthode est tout code d’erreur (ou de réussite) rencontré lors de l’envoi de la commande au pilote.

Si un pilote ne prend pas en charge la commande spécifiée, cette méthode réussit, mais le seul élément garanti dans le paramètre ppResults retourné sera WPD_PROPERTY_COMMON_HRESULT, qui contiendra E_NOTIMPL. Vous pouvez vérifier si un pilote prend en charge une commande en appelant IPortableDeviceCapabilities ::GetSupportedCommands avant d’appeler une commande.

Si une commande prend en charge les options (par exemple, supprimer de manière récursive ou supprimer de manière non récursive), vous pouvez rechercher les options prises en charge en appelant IPortableDeviceCapabilities ::GetCommandOptions.

Il n’existe aucune option permettant de définir un délai d’expiration dans un appel à SendCommand , mais le développeur peut tenter d’annuler la commande en appelant IPortableDevice ::Cancel à partir d’un thread distinct.

Exemples


// 

void ResetDevice(IPortableDevice* pDevice)
{
    HRESULT  hr = S_OK;
    CComPtr<IPortableDeviceValues>  pDevValues;

    hr = CoCreateInstance(CLSID_PortableDeviceValues,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IPortableDeviceValues,
        (VOID**) &pDevValues);
    if (SUCCEEDED(hr))
    {
        if (pDevValues != NULL)
        {
            hr = pDevValues->SetGuidValue(WPD_PROPERTY_COMMON_COMMAND_CATEGORY, 
                WPD_COMMAND_COMMON_RESET_DEVICE.fmtid);
            if (FAILED(hr))
            {
                printf("! IPortableDeviceValues::SetGuidValue failed, hr= 0x%lx\n", hr);
            }
            hr = pDevValues->SetUnsignedIntegerValue(WPD_PROPERTY_COMMON_COMMAND_ID,
                WPD_COMMAND_COMMON_RESET_DEVICE.pid);
            if (FAILED(hr))
            {
                printf("! IPortableDeviceValues::SetGuidValue failed, hr= 0x%lx\n", hr);
            }
        }
    }
    hr = pDevice->SendCommand(0, pDevValues, &pDevValues);
    if (FAILED(hr))
    {
        printf("! Failed to reset the device, hr = 0x%lx\n",hr);
    }
    else
        printf("Device successfully reset\n");
    return;
}

//

Configuration requise

Condition requise	Valeur
Plateforme cible	Windows
En-tête	portabledeviceapi.h
Bibliothèque	PortableDeviceGUIDs.lib

Voir aussi

IPortableDevice, interface

Partager via