estructura _URB_HEADER (usb.h)

Artículo
08/07/2023

Los controladores de cliente USB usan la estructura _URB_HEADER para proporcionar información básica sobre la solicitud que se envía al controlador del controlador de host.

Sintaxis

struct _URB_HEADER {
  USHORT      Length;
  USHORT      Function;
  USBD_STATUS Status;
  PVOID       UsbdDeviceHandle;
  ULONG       UsbdFlags;
};

Miembros

Length

Especifica la longitud, en bytes, del URB. Para las solicitudes URB que usan estructuras de datos distintas de _URB_HEADER, este miembro debe establecerse en la longitud de toda la estructura de solicitudes URB, no en el tamaño de _URB_HEADER.

Function

Especifica un código numérico que indica la operación solicitada para este URB. Se debe establecer uno de los siguientes valores:

URB_FUNCTION_SELECT_CONFIGURATION

Indica al controlador del controlador de host que se va a seleccionar una configuración. Si se establece, el URB se usa con URB_SELECT_CONFIGURATION como estructura de datos.

URB_FUNCTION_SELECT_INTERFACE

Indica al controlador del controlador de host que se selecciona una configuración de interfaz alternativa para una interfaz. Si se establece, el URB se usa con _URB_SELECT_INTERFACE como estructura de datos.

URB_FUNCTION_ABORT_PIPE

Indica que se deben cancelar todas las solicitudes pendientes de una canalización. Si se establece, el URB se usa con _URB_PIPE_REQUEST como estructura de datos. Esta solicitud de uso general permite a un cliente cancelar las transferencias pendientes para la canalización especificada. El estado de canalización y el estado del punto de conexión no se ven afectados. La solicitud de anulación puede completarse antes de que se hayan completado todas las solicitudes pendientes. No suponga que la finalización de la solicitud de anulación implica que todas las demás solicitudes pendientes se han completado.

URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL

Esta función URB está en desuso en los sistemas operativos Windows 2000 y versiones posteriores y no es compatible con Microsoft. No debe usarse. Si especifica esta función con una solicitud URB, se producirá un error en la solicitud y el sistema notificará un error.

URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

URB_FUNCTION_GET_FRAME_LENGTH

Esta función URB está en desuso en los sistemas operativos Windows 2000 y versiones posteriores y no es compatible con Microsoft. No debe usarse. Si usa esta función con una solicitud URB, se producirá un error en la solicitud y el sistema notificará un error.

URB_FUNCTION_SET_FRAME_LENGTH

Esta función URB está en desuso en los sistemas operativos Windows 2000 y versiones posteriores y no es compatible con Microsoft. No debe usarse. Si lo usa con una solicitud URB, se producirá un error en la solicitud y el sistema notificará un error.

URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Solicita el número de fotograma actual del controlador de host. Si se establece, el URB se usa con _URB_GET_CURRENT_FRAME_NUMBER como estructura de datos.

URB_FUNCTION_CONTROL_TRANSFER

Transfiere datos hacia o desde una canalización de control. Si se establece, el URB se usa con _URB_CONTROL_TRANSFER como estructura de datos.

URB_FUNCTION_CONTROL_TRANSFER_EX

Transfiere datos a una canalización de control o desde él sin un límite de tiempo especificado por un valor de tiempo de espera. Si se establece, el URB se usa con URB_CONTROL_TRANSFER_EX como estructura de datos.

Disponible en Windows Vista y sistemas operativos posteriores.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Transfiere datos de una canalización masiva o una canalización de interrupción o a una canalización masiva. Si se establece, el URB se usa con _URB_BULK_OR_INTERRUPT_TRANSFER como estructura de datos.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER_USING_CHAINED_MDL

Transfiere datos hacia y desde una canalización masiva o una canalización de interrupción mediante MDL encadenadas. Si se establece, el URB se usa con _URB_BULK_OR_INTERRUPT_TRANSFER como estructura de datos. El controlador cliente debe establecer el miembro TransferBufferMDL en la primera estructura MDL de la cadena que contiene el búfer de transferencia. La pila del controlador USB omite el miembro TransferBuffer al procesar este URB.

Disponible en Windows 8. Para obtener información sobre el uso de MDL encadenados, vea How to Send Chained MDLs(Cómo enviar MDL encadenados).>

URB_FUNCTION_ISOCH_TRANSFER

Transfiere datos hacia o desde una canalización isócrónica. Si se establece, el URB se usa con _URB_ISOCH_TRANSFER como estructura de datos.

URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_MDL

Transfiere datos hacia o desde una canalización isócrónica mediante MDL encadenados. Si se establece, el URB se usa con _URB_ISOCH_TRANSFER como estructura de datos. El controlador cliente debe establecer el miembro TransferBufferMDL en la primera MDL de la cadena que contiene el búfer de transferencia. La pila del controlador USB omite el miembro TransferBuffer al procesar este URB.

Disponible en Windows 8. Para obtener información sobre el uso de MDL encadenados, vea How to Send Chained MDLs(Cómo enviar MDL encadenados).>

URB_FUNCTION_RESET_PIPE

Consulte URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL

Restablece la canalización indicada. Si se establece, este URB se usa con _URB_PIPE_REQUEST.

Nota

Este URB reemplaza URB_FUNCTION_RESET_PIPE.

El controlador de autobús realiza tres tareas en respuesta a este URB:

En primer lugar, para todas las canalizaciones excepto las canalizaciones isócrónicas, este URB envía una solicitud de CLEAR_FEATURE para borrar la característica de ENDPOINT_HALT del dispositivo.

En segundo lugar, el controlador de bus USB restablece el botón de alternancia de datos en el lado host, según lo requiera la especificación USB. El dispositivo USB debe restablecer el botón de alternancia de datos en el lado del dispositivo cuando el controlador de autobús borra su característica de ENDPOINT_HALT. Dado que algunos dispositivos no compatibles no admiten esta característica, Microsoft proporciona las dos direcciones URL adicionales: URB_FUNCTION_SYNC_CLEAR_STALL y URB_FUNCTION_SYNC_RESET_PIPE. Estos permiten a los controladores de cliente borrar la característica de ENDPOINT_HALT en el dispositivo o restablecer la canalización en el lado host, respectivamente, sin afectar a la alternancia de datos en el lado host. Si el dispositivo no restablece el botón de alternancia de datos cuando debería, el controlador cliente puede compensar este defecto al no restablecer el botón de alternancia de datos del lado host. Si el botón de alternancia de datos se restablece en el lado host, pero no en el lado del dispositivo, los paquetes se sacarán de la secuencia y el dispositivo podría quitar paquetes.

En tercer lugar, después de que el controlador de autobús haya restablecido correctamente la canalización, reanuda las transferencias con el siguiente URB en cola.

Después de un restablecimiento de canalización, las transferencias se reanudan con el siguiente URB en cola.

No es necesario borrar una condición de detención en una canalización de control predeterminada. La canalización de control predeterminada siempre debe aceptar paquetes de configuración y, por lo tanto, si se detiene, la pila USB borrará la condición de detención automáticamente. El controlador cliente no necesita realizar ninguna acción especial para borrar la condición de detención en una canalización predeterminada.

Todas las transferencias deben anularse o cancelarse antes de intentar restablecer la canalización.

Este URB debe enviarse en PASSIVE_LEVEL.

URB_FUNCTION_SYNC_RESET_PIPE

Borra la condición de detención en el lado host de una canalización. Si se establece, este URB se usa con _URB_PIPE_REQUEST como estructura de datos.

Este URB permite a un cliente borrar el estado detenido de una canalización sin restablecer el botón de alternancia de datos y sin borrar la condición de detención del punto de conexión (característica ENDPOINT_HALT). Para borrar una condición de detención en la canalización, restablezca el botón de alternancia de datos del lado host y desactive una parada en el dispositivo con una sola operación, use URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

Los siguientes códigos de estado son importantes y tienen el significado indicado:

USBD_STATUS_INVALID_PIPE_HANDLE

PipeHandle no es válido

USBD_STATUS_ERROR_BUSY

El punto de conexión tiene transferencias activas pendientes.

No es necesario borrar una condición de detención en una canalización de control predeterminada. La canalización de control predeterminada siempre debe aceptar paquetes de instalación, por lo que si se detiene, la pila USB borrará la condición de detención automáticamente. El controlador cliente no necesita realizar ninguna acción especial para borrar la condición de detención en una canalización predeterminada.

Todas las transferencias deben anularse o cancelarse antes de intentar restablecer la canalización.

Este URB debe enviarse en PASSIVE_LEVEL.

Disponible en Windows XP y sistemas operativos posteriores.

URB_FUNCTION_SYNC_CLEAR_STALL

Borra la condición de detenerse en el punto de conexión. Para todas las canalizaciones excepto las canalizaciones isócrónicas, este URB envía una solicitud de CLEAR_FEATURE para borrar la característica de ENDPOINT_HALT del dispositivo. Sin embargo, a diferencia de la función RB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL, esta función URB no restablece el botón de alternancia de datos en el lado host de la canalización. La especificación USB requiere que los dispositivos restablezcan la alternancia de datos del lado del dispositivo después de que el cliente borre la característica de ENDPOINT_HALT del dispositivo, pero algunos dispositivos no compatibles no restablecen correctamente sus datos. Los controladores cliente que administran estos dispositivos pueden compensar este defecto borrando la condición de parada directamente con URB_FUNCTION_SYNC_CLEAR_STALL en lugar de restablecer la tubería con URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL. URB_FUNCTION_SYNC_CLEAR_STALL borra una condición de detención en el dispositivo sin restablecer el botón de alternancia de datos del lado host. Esto impide que un dispositivo no compatible interprete el siguiente paquete como una retransmisión y quite el paquete.

Si se establece, el URB se usa con _URB_PIPE_REQUEST como estructura de datos.

Esta función URB debe enviarse en PASSIVE_LEVEL

Disponible en Windows XP y sistemas operativos posteriores.

URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Recupera el descriptor de dispositivo de un dispositivo USB específico. Si se establece, el URB se usa con _URB_CONTROL_DESCRIPTOR_REQUEST como estructura de datos.

URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT

Recupera el descriptor de un punto de conexión en una interfaz para un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_DESCRIPTOR_REQUEST como estructura de datos.

URB_FUNCTION_SET_DESCRIPTOR_TO_DEVICE

Establece un descriptor de dispositivo en un dispositivo. Si se establece, el URB se usa con _URB_CONTROL_DESCRIPTOR_REQUEST como estructura de datos.

URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT

Establece un descriptor de punto de conexión en un punto de conexión para una interfaz. Si se establece, el URB se usa con _URB_CONTROL_DESCRIPTOR_REQUEST como estructura de datos.

URB_FUNCTION_SET_FEATURE_TO_DEVICE

Establece una característica definida por USB en un dispositivo. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_SET_FEATURE_TO_INTERFACE

Establece una característica definida por USB en una interfaz para un dispositivo. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_SET_FEATURE_TO_ENDPOINT

Establece una característica definida por USB en un punto de conexión para una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_SET_FEATURE_TO_OTHER

Establece una característica definida por USB en un destino definido por el dispositivo en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE

Borra una característica definida por USB en un dispositivo. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE

Borra una característica definida por USB en una interfaz para un dispositivo. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT

Borra una característica definida por USB en un punto de conexión, para una interfaz, en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Borra una característica definida por USB en un destino definido por el dispositivo en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_FEATURE_REQUEST como estructura de datos.

URB_FUNCTION_GET_STATUS_FROM_DEVICE

Recupera el estado de un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_GET_STATUS_REQUEST como estructura de datos.

URB_FUNCTION_GET_STATUS_FROM_INTERFACE

Recupera el estado de una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_GET_STATUS_REQUEST como estructura de datos.

URB_FUNCTION_GET_STATUS_FROM_ENDPOINT

Recupera el estado de un punto de conexión para una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_GET_STATUS_REQUEST como estructura de datos.

URB_FUNCTION_GET_STATUS_FROM_OTHER

Recupera el estado de un destino definido por el dispositivo en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_GET_STATUS_REQUEST como estructura de datos.

URB_FUNCTION_VENDOR_DEVICE

Envía un comando específico del proveedor a un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_VENDOR_INTERFACE

Envía un comando específico del proveedor para una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_VENDOR_ENDPOINT

Envía un comando específico del proveedor para un punto de conexión en una interfaz de un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_VENDOR_OTHER

Envía un comando específico del proveedor a un destino definido por el dispositivo en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_CLASS_DEVICE

Envía un comando específico de clase definido por USB a un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_CLASS_INTERFACE

Envía un comando específico de clase definido por USB a una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_CLASS_ENDPOINT

Envía un comando específico de clase definido por USB a un punto de conexión, en una interfaz, en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_CLASS_OTHER

Envía un comando específico de clase definido por USB a un destino definido por el dispositivo en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como estructura de datos.

URB_FUNCTION_GET_CONFIGURATION

Recupera la configuración actual en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_GET_CONFIGURATION_REQUEST como estructura de datos.

URB_FUNCTION_GET_INTERFACE

Recupera la configuración actual de una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_GET_INTERFACE_REQUEST como estructura de datos.

Disponible en Windows 2000, y Windows Vista y sistemas operativos posteriores. No está disponible en Windows XP.

URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE

Recupera el descriptor de una interfaz para un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_DESCRIPTOR_REQUEST como estructura de datos.

URB_FUNCTION_SET_DESCRIPTOR_TO_INTERFACE

Establece un descriptor para una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_CONTROL_DESCRIPTOR_REQUEST como estructura de datos.

URB_FUNCTION_GET_MS_FEATURE_DESCRIPTOR

Recupera un descriptor de características del sistema operativo de Microsoft desde un dispositivo USB o una interfaz en un dispositivo USB. Si se establece, el URB se usa con _URB_OS_FEATURE_DESCRIPTOR_REQUEST como estructura de datos.

Disponible en Windows XP y sistemas operativos posteriores.

URB_FUNCTION_OPEN_STATIC_STREAMS

Abre secuencias en el punto de conexión masivo especificado. Si se establece, el URB se usa con _URB_OPEN_STATIC_STREAMS como estructura de datos.

Disponible en Windows 8. Para obtener información sobre cómo dar formato a un URB para una solicitud de flujo abierto, vea Cómo abrir y cerrar secuencias estáticas en un punto de conexión masivo USB.

URB_FUNCTION_CLOSE_STATIC_STREAMS

Cierra todas las secuencias abiertas en el punto de conexión masivo especificado. Si se establece, el URB se usa con _URB_PIPE_REQUEST como estructura de datos.

Status

Contiene un código USBD_STATUS_XXX devuelto por el controlador del host.

UsbdDeviceHandle

Reservado. No utilizar.

UsbdFlags

Reservado. No utilizar.

Comentarios

La estructura _URB_HEADER es miembro de todas las solicitudes USB que forman parte de la estructura URB. La estructura _URB_HEADER se usa para proporcionar información común sobre cada solicitud al controlador del controlador de host.

Los miembros reservados de esta estructura deben tratarse como opacos y están reservados para uso del sistema.