IOKit/usb/IOUSBHostInterface.h Kernel.framework

@header IOUSBHostInterface.h @brief IOUSBHostInterface is an IOService representing a USB interface. @discussion <h3>Session Management</h3> A driver that has successfully matched on an IOUSBHostInterface is able to take ownership of the interface by calling the <code>open</code> method defined by IOService on the IOUSBHostInterface. Once <code>open</code> has completed successfully, the driver has an open session, and may use the deviceRequest interface to send control requests, the selectAlternateSetting interface to change the endpoints and behavior of the interface. When the driver is finished with control of the IOUSBHostInterface, it must call <code>close</code> to end its session. Calling <code>close</code> will synchronously abort any IO associated with that session, including requests on the control endpoint. If the interface is terminating for any reason, such as the device being unplugged, the driver must call <code>close</code> on the IOUSBHostInterface, or termination will be blocked and the port will not register newly attached devices for matching. The willTerminate call into the driver is the recommended location to call <code>close</code>. <h3>deviceRequest Interface</h3> The <code>deviceRequest</code> methods are used to send control requests to the device's default endpoint. The <code>deviceRequest</code> methods may not be used for the following standard requests: <ul> <li>CLEAR_FEATURE ENDPOINT_HALT (USB 2.0 9.4.1) - Use <code>IOUSBHostPipe::clearStall</code> to send this request</li> <li>SET_ADDRESS (USB 2.0 9.4.6)</li> <li>SET_CONFIGURATION (USB 2.0 9.4.7) - Use <code>setConfiguration</code> to send this request</li> <li>SET_INTERFACE (USB 2.0 9.4.10) - Use <code>IOUSBHostInterface::selectAlternateSetting</code> to send this request</li> </ul> <h3>IOUSBInterface Migration</h3> IOUSBHostInterface serves as a replacement for IOUSBInterface. Clients that previously matched on IOUSBInterface can use the following guide to convert to IOUSBHostInterface. <code>virtual const IOUSBInterfaceDescriptor* IOUSBInterface::FindNextAltInterface(const IOUSBInterfaceDescriptor*, IOUSBFindInterfaceRequest*);</code><br> Replacement: <code>StandardUSB::getNextInterfaceDescriptor(...);</code> <code>virtual IOUSBPipe* IOUSBInterface::FindNextPipe(IOUSBHostPipe*, IOUSBFindEndpointRequest*);<br> virtual IOUSBPipe* IOUSBInterface::FindNextPipe(IOUSBHostPipe*, IOUSBFindEndpointRequest*, bool);</code><br> Replacement: <pre>const EndpointDescriptor* endpointCandidate = NULL; IOUSBHostPipe* foundPipe = NULL; while((endpointCandidate = StandardUSB::getNextAssociatedDescriptorWithType(getConfigurationDescriptor(), getInterfaceDescriptor(), endpointCandidate, kDescriptorTypeEndpoint)) != NULL) { if(endpointCandidate->bEndpointAddress == desiredAddress>) { foundPipe = copyPipe(StandardUSB::getEndpointAddress(endpointCandidate)); break; } }</pre> <code>virtual const IOUSBDescriptorHeader* IOUSBInterface::FindNextAssociatedDescriptor(const void*, UInt8);</code><br> Replacement: <code>StandardUSB::getNextAssociatedDescriptorWithType(getConfigurationDescriptor(), getInterfaceDescriptor(), currentDescriptor, type);</code> <code>virtual IOReturn IOUSBInterface::SetAlternateInterface(IOService*, UInt16); Replacement: <code>selectAlternateSetting(...);</code> <code>virtual IOUSBHostPipe* IOUSBInterface::GetPipeObj(UInt8);<br> virtual IOUSBHostPipe* IOUSBInterface::GetPipeObjRetain(UInt8);</code><br> Replacement: <code>copyPipe(endpointAddress);</code><br> Note that <code>copyPipe</code> behaves like <code>GetPipeObjRetain</code>, and the returned pipe must be released by the caller during termination. <code>virtual UInt8 IOUSBInterface::GetConfigValue();</code><br> Replacement: <code>getConfigurationDescriptor()->bConfigurationValue;</code> <code>virtual IOUSBHostDevice* IOUSBInterface::GetDevice();</code><br> Replacement: <pre>// Function drivers should not assume the immediate provider of an IOUSBHostInterface is an IOUSBHostDevice. IOService* deviceCandidate = getProvider(); IOUSBHostDevice* device = NULL; while(deviceCandidate != NULL) { device = OSDynamicCast(IOUSBHostDevice, deviceCandidate); if(device != NULL) { break; } deviceCandidate = deviceCandidate->getProvider(); }</pre> <code>virtual UInt8 IOUSBInterface::GetInterfaceNumber();</code><br> Replacement: <code>getInterfaceDescriptor()->bInterfaceNumber;</code> <code>virtual UInt8 IOUSBInterface::GetAlternateSetting();</code><br> Replacement: <code>getInterfaceDescriptor()->bAlternateSetting;</code> <code>virtual UInt8 IOUSBInterface::GetNumEndpoints();</code><br> Replacement: <code>getInterfaceDescriptor()->bNumEndpoints;</code> <code>virtual UInt8 IOUSBInterface::GetInterfaceClass();</code><br> Replacement: <code>getInterfaceDescriptor()->bInterfaceClass;</code> <code>virtual UInt8 IOUSBInterface::GetInterfaceSubClass();</code><br> Replacement: <code>getInterfaceDescriptor()->bInterfaceSubClass;</code> <code>virtual UInt8 IOUSBInterface::GetInterfaceProtocol();</code><br> Replacement: <code>getInterfaceDescriptor()->bInterfaceProtocol;</code> <code>virtual UInt8 IOUSBInterface::GetInterfaceStringIndex();</code><br> Replacement: <code>getInterfaceDescriptor()->iInterface;</code> <code>virtual IOReturn IOUSBInterface::DeviceRequest(IOUSBDevRequest* request, IOUSBCompletion* completion = 0);<br> virtual IOReturn IOUSBInterface::DeviceRequest(IOUSBDevRequestDesc* request, IOUSBCompletion* completion = 0);</code><br> Replacement: <code>deviceRequest(...)</code> <code>virtual IOReturn IOUSBInterface::GetEndpointProperties(UInt8 alternateSetting, UInt8 endpointNumber, UInt8 direction, UInt8* transferType, UInt16* maxPacketSize, UInt8* interval);<br> virtual IOReturn GetEndpointPropertiesV3(IOUSBEndpointProperties*);</code><br> Replacement: Use <code>StandardUSB::getEndpoint*</code> methods to retrieve endpoint properties. <code>virtual IOReturn RememberStreams();</code><br> Replacement: none <code>virtual IOReturn RecreateStreams();</code><br> Replacement: none <code>virtual void UnlinkPipes();</code><br> Replacement: none <code>virtual void ReopenPipes();</code><br> Replacement: none <code>virtual IOReturn GetInterfaceStatus(USBStatus*);</code><br> Replacement: Use <code>deviceRequest(...)</code> to manually craft the control request. <code>virtual IOReturn SetFunctionSuspendFeature(UInt8);</code><br> Replacement: It is not recommended for function drivers to send this request. <code>virtual IOReturn EnableRemoteWake(bool);</code><br> Replacement: Use <code>deviceRequest(...)</code> to manually craft the control request. <code>IOUSBHostDevice::setConfiguration</code> will automatically enable remote wake if the descriptors indicate it is supported.

#define IOUSBHostFamily_IOUSBHostInterface_h 

#define TARGET_OS_HAS_USBDRIVERKIT_IOUSBHOSTINTERFACE __has_include(<USBDriverKit/IOUSBHostInterface.h>)