usb

type ClassSpecificDescriptor struct {
	DescriptorType uint8
	Payload        Data
}

type ConfigHeader struct {
	WTotalLength        uint16 // LE, to be patched after building
	BNumInterfaces      uint8
	BConfigurationValue uint8
	IConfiguration      uint8
	BMAttributes        uint8
	BMaxPower           uint8
}

type ConfigurationDescriptor struct {
	BConfigurationValue uint8
	IConfiguration      uint8
	BMAttributes        uint8
	BMaxPower           uint8
}

type ControlDevice interface {
	// HandleControl handles a control request.
	//
	// - bmRequestType, bRequest, wValue, wIndex, wLength are the raw setup packet fields.
	// - data is the OUT data stage payload (for host-to-device requests), and is nil for
	//   device-to-host requests.
	//
	// If handled is false, the server will fall back to its default behavior.
	// If handled is true, the returned bytes (if any) will be used as the IN data stage.
	HandleControl(bmRequestType, bRequest uint8, wValue, wIndex, wLength uint16, data []byte) (resp []byte, handled bool)
}

type Data []uint8

type Descriptor struct {
	Device        DeviceDescriptor
	Configuration ConfigurationDescriptor
	MicrosoftOS10 *MicrosoftOS10Descriptor
	Associations  []InterfaceAssociationDescriptor
	Interfaces    []InterfaceConfig
	Strings       map[uint8]string
}

type Device interface {
	// HandleTransfer processes a non-EP0 transfer (interrupt/bulk).
	// ep is the endpoint number (without direction). dir is usbip.DirIn or usbip.DirOut.
	// For IN transfers, return the payload to send; for OUT, consume 'out' and return nil.
	HandleTransfer(ep uint32, dir uint32, out []byte) []byte
	GetDescriptor() *Descriptor
	GetDeviceSpecificArgs() map[string]any
}

type DeviceDescriptor struct {
	BcdUSB             uint16 // LE
	BDeviceClass       uint8
	BDeviceSubClass    uint8
	BDeviceProtocol    uint8
	BMaxPacketSize0    uint8
	IDVendor           uint16 // LE; may get overridden
	IDProduct          uint16 // LE; may get overridden
	BcdDevice          uint16 // LE
	IManufacturer      uint8
	IProduct           uint8
	ISerialNumber      uint8
	BNumConfigurations uint8
	Speed              uint32 // USB speed: 1=low, 2=full, 3=high, 4=super
}

type EndpointDescriptor struct {
	BEndpointAddress uint8
	BMAttributes     uint8
	WMaxPacketSize   uint16 // LE
	BInterval        uint8

	// ClassDescriptors are optional endpoint-level class-specific descriptors
	// emitted immediately after this endpoint descriptor.
	ClassDescriptors []ClassSpecificDescriptor
}

type HIDDescriptor struct {
	BcdHID       uint16 // LE
	BCountryCode uint8
	Descriptors  []HIDSubDescriptor
}

type HIDFunction struct {
	Descriptor       HIDDescriptor
	ReportDescriptor hid.ReportDescriptor
	// ReportDescriptorBytes, when non-empty, is returned verbatim as the HID report
	// descriptor (0x22) and used for HID report length calculation. This is useful for
	// complex, vendor-specific descriptors that are easier to provide as raw bytes.
	ReportDescriptorBytes Data
}

type HIDSubDescriptor struct {
	Type   uint8
	Length uint16 // LE
}

type InterfaceAssociationDescriptor struct {
	BFirstInterface   uint8
	BInterfaceCount   uint8
	BFunctionClass    uint8
	BFunctionSubClass uint8
	BFunctionProtocol uint8
	IFunction         uint8
}

type InterfaceConfig struct {
	Descriptor InterfaceDescriptor
	Endpoints  []EndpointDescriptor

	// HID describes a HID-class interface (bInterfaceClass=0x03).
	// If set, the server will emit the HID descriptor (0x21) in the configuration
	// descriptor and serve the report descriptor (0x22) via GET_DESCRIPTOR.
	HID *HIDFunction

	// ClassDescriptors are additional interface-level class-specific descriptors
	// emitted as part of the configuration descriptor (after the interface descriptor
	// and before the endpoints).
	//
	// This is also used for vendor-specific interfaces that need to expose opaque
	// descriptors (e.g. type 0x21 blobs on Xbox360).
	ClassDescriptors []ClassSpecificDescriptor
}

type InterfaceDescriptor struct {
	BInterfaceNumber   uint8
	BAlternateSetting  uint8
	BNumEndpoints      uint8
	BInterfaceClass    uint8
	BInterfaceSubClass uint8
	BInterfaceProtocol uint8
	IInterface         uint8
}

type MicrosoftOS10Descriptor struct {
	VendorCode          uint8
	InterfaceNumber     uint8
	CompatibleID        string
	SubCompatibleID     string
	DeviceInterfaceGUID string
}