Comandos extendidos por el proveedor

Una aplicación puede enviar un comando arbitrario al dispositivo a través del método IWiaItemExtras::Escape, que se describe en la documentación de Microsoft Windows SDK. Al llamar a QueryInterface en el elemento raíz, puede recuperar un puntero a la interfaz IWiaItemExtras . Después, la aplicación puede construir un comando PTP mediante cualquier código de operación y parámetros, y enviar este comando al dispositivo. La aplicación también puede enviar datos a o recibir datos del dispositivo.

El dispositivo informa a la aplicación del resultado de la operación cuando se devuelve el método IWiaItemExtras::Escape , rellenando un código de respuesta y parámetros de respuesta en una estructura de PTP_VENDOR_DATA_OUT . Se omiten los miembros SessionId y TransactionId de la estructura de PTP_VENDOR_DATA_IN . El controlador proporciona valores correctos para estos.

Para los comandos definidos por el proveedor que no sean ESCAPE_PTP_CLEAR_STALLS, se debe combinar una marca especial, ESCAPE_PTP_VENDOR_COMMAND, con el comando usado en el método IWiaItemExtras::Escape . Si un comando definido por el proveedor crea o elimina un objeto en el dispositivo mediante las siguientes marcas descritas, el controlador agrega o quita el objeto de sus estructuras internas y genera un evento WIA. Todos los demás comandos estándar deben emitirse a través de la interfaz WIA adecuada.

El primer parámetro de IWiaItemExtras::Escape es la combinación de una o varias de las marcas siguientes:

Código de escape	Significado
ESCAPE_PTP_ADD_OBJ_CMD	Se agrega un objeto y el identificador del objeto se encuentra en uno de los parámetros de comando.
ESCAPE_PTP_REM_OBJ_CMD	Se quita un objeto y el identificador del objeto se encuentra en uno de los parámetros de comando.
ESCAPE_PTP_ADD_OBJ_RESP	Se agrega un objeto y el identificador del objeto se encuentra en uno de los parámetros de respuesta.
ESCAPE_PTP_REM_OBJ_RESP	Se quita un objeto y el identificador del objeto se encuentra en uno de los parámetros de respuesta.
ESCAPE_PTP_ADDREM_PARM1	El identificador del objeto agregado o quitado se encuentra en el primer parámetro del comando o respuesta.
ESCAPE_PTP_ADDREM_PARM2	El identificador del objeto agregado o quitado se encuentra en el segundo parámetro del comando o la respuesta.
ESCAPE_PTP_ADDREM_PARM3	El identificador del objeto agregado o quitado se encuentra en el tercer parámetro del comando o respuesta.
ESCAPE_PTP_ADDREM_PARM4	El identificador del objeto agregado o quitado se encuentra en el cuarto parámetro del comando o la respuesta.
ESCAPE_PTP_ADDREM_PARM5	El identificador del objeto agregado o quitado se encuentra en el quinto parámetro del comando o la respuesta.
ESCAPE_PTP_CLEAR_STALLS	Borre las condiciones de error causadas por un comando extendido por el proveedor. Esta marca no se puede usar en combinación con ninguna de las otras marcas. Para obtener más información sobre esta marca, vea la nota que sigue a esta tabla.
ESCAPE_PTP_VENDOR_COMMAND	El comando es un comando extendido por el proveedor.

Cuando una aplicación llama a IWiaItemExtras::Escape con la marca ESCAPE_PTP_CLEAR_STALL como primer argumento para este método, el controlador emite la solicitud PTP Get Device Status para determinar si los puntos de conexión están en una condición STALL. Si el comando Obtener estado del dispositivo se realiza correctamente, el controlador emite el IOCTL_RESET_PIPE código de control USB para cada punto de conexión de este tipo. Si se produce un error en el comando Obtener estado del dispositivo , el controlador emite una solicitud de restablecimiento de dispositivo PTP. Obtener el estado del dispositivo y el restablecimiento del dispositivo se describen en el estándar PIMA 15740:2000, primera edición y revisión 1.0 de la definición del dispositivo de captura de imágenes fijas USB (SICDD USB).

En el código de ejemplo siguiente se muestra cómo usar la interfaz de comandos extendida por el proveedor. Asegúrese de que el código incluye el encabezado ptpusd.h , ya que contiene las definiciones de los códigos de escape y otras constantes, y las estructuras PTP_VENDOR_DATA_IN y PTP_VENDOR_DATA_OUT . La interfaz IWiaItemExtras se obtiene mediante una llamada a QueryInterface en el elemento raíz. Un puntero a este elemento raíz, pIWiaRootItem, se puede obtener, por ejemplo, mediante una llamada a IWiaDevMgr::SelectDeviceDlg (descrito en la documentación de 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.
//