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

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.

[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.

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 :

• WPD_COMMAND_COMMON_RESET_DEVICE
• WPD_COMMAND_DEVICE_HINTS_GET_CONTENT_LOCATION
• WPD_COMMAND_SMS_SEND
• WPD_COMMAND_STILL_IMAGE_CAPTURE_INITIATE
• WPD_COMMAND_STORAGE_EJECT

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

Voir aussi

IPortableDevice, interface