diff -r 000000000000 -r a41df078684a kernel/eka/include/d32usbc.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/include/d32usbc.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,1163 @@ +// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// e32/include/d32usbc.h +// User side class definitions for USB Device support. +// +// + +/** + @file d32usbc.h + @publishedPartner + @released +*/ + +#ifndef __D32USBC_H__ +#define __D32USBC_H__ + +#include +#include +#include + + + +/** @internalComponent +*/ +enum TTransferType + { + ETransferTypeReadData, + ETransferTypeReadPacket, + ETransferTypeWrite, + ETransferTypeNone, + ETransferTypeReadOneOrMore, + ETransferTypeReadUntilShort + }; + + +/** Available endpoints. At most only these are available per interface. +*/ +enum TEndpointNumber + { + EEndpoint0 = 0, + EEndpoint1 = 1, + EEndpoint2 = 2, + EEndpoint3 = 3, + EEndpoint4 = 4, + EEndpoint5 = 5 + }; + + + + +/** Bandwidth indicators for an Interface + + @see RDevUsbcClient::SetInterface() +*/ +enum TUsbcBandwidthPriority + { + /** Economical OUT buffering. */ + EUsbcBandwidthOUTDefault = 0x00, + /** More memory than Default for OUT buffering. */ + EUsbcBandwidthOUTPlus1 = 0x01, + /** More memory than Plus1 for OUT buffering. */ + EUsbcBandwidthOUTPlus2 = 0x02, + /** Maximum memory for OUT buffering. + Use this value for high volume USB High-speed + data transfers only, otherwise memory will be wasted. + */ + EUsbcBandwidthOUTMaximum = 0x03, + // + /** Economical IN buffering */ + EUsbcBandwidthINDefault = 0x00, + /** More memory than Default for IN buffering */ + EUsbcBandwidthINPlus1 = 0x10, + /** More memory than Plus1 for IN buffering */ + EUsbcBandwidthINPlus2 = 0x20, + /** Maximum memory for IN buffering. + Use this value for high volume USB High-speed + data transfers only, otherwise memory will be wasted. + */ + EUsbcBandwidthINMaximum = 0x30 + }; + + + + + + + +/** Bit positions of endpoints. + + @see RDevUsbcClient::EndpointStatusNotify() + @see RDevUsbcClient::EndpointTransferCancel() + + Bit position of endpoint0. +*/ +const TUint KUsbcEndpoint0Bit = 1< TUsbcInterfaceInfoBuf; + + +/** The user side handle to the USB client driver. +*/ +class RDevUsbcClient : public RBusLogicalChannel + { +public: + /** @internalComponent */ + enum TVer + { + EMajorVersionNumber = 0, + EMinorVersionNumber = 1, + EBuildVersionNumber = KE32BuildVersionNumber + }; + + enum TRequest + { + // Positive requests. + ERequestEp0 = 0x0, + ERequestEp1 = EEndpoint1, + ERequestEp2 = EEndpoint2, + ERequestEp3 = EEndpoint3, + ERequestEp4 = EEndpoint4, + ERequestEp5 = EEndpoint5, + ERequestUnused = 6, + ERequestAlternateDeviceStatusNotify = 7, + ERequestReEnumerate = 8, + ERequestEndpointStatusNotify = 9, + // The cancel TRequest's are interpreted as bitmaps. As they're not mixed + // with the previous ones, it doesn't matter if they have the same absolute + // value as those. + ERequestEp0Cancel = 1<(data), sizeof(data), sizeof(data)); + ret = usbPort.EndpointCaps(dataPtr); + @endcode + + @param aEpCapsBuf a descriptor encapsulating an array of TUsbcEndpointData. + + @return KErrNone if successful. + */ + inline TInt EndpointCaps(TDes8& aEpCapsBuf); + + /** Retrieves the capabilities of the USB device. + + @see TUsbDeviceCaps + + @param aDevCapsBuf a TUsbDeviceCaps object. + + @return KErrNone if successful. + */ + inline TInt DeviceCaps(TUsbDeviceCaps& aDevCapsBuf); + + /** Copies the current alternate setting for this interface into aInterfaceNumber + For USB Interfaces whose main interface is active, this will be 0 (zero). + + @param aInterfaceNumber current alternate setting for this interface is copied into this. + + @return KErrNone if successful. + */ + inline TInt GetAlternateSetting(TInt& aInterfaceNumber); + + /** Copies the current device status into aDeviceStatus. + + @param aDeviceStatus current device status is copied into this. + + @return KErrNone if successful + */ + inline TInt DeviceStatus(TUsbcDeviceState& aDeviceStatus); + + /** Copies the current endpoint status into aEndpointStatus. + + @param aEndpoint endpoint number valid for the current alternate setting. + @param aEndpointStatus the current endpoint status, might be stalled, not stalled or unknown. + + @return KErrNone if successful. + */ + inline TInt EndpointStatus(TEndpointNumber aEndpoint, TEndpointState& aEndpointStatus); + + /** Copies the number of bytes available in the aEndpoint read buffer into aNumberOfBytes. + + @param aEndpoint endpoint number valid for the current alternate setting. + @param aNumberOfBytes number of bytes available in the aEndpoint read buffer. + + @return KErrNone if successful. + */ + inline TInt QueryReceiveBuffer(TEndpointNumber aEndpoint, TInt& aNumberOfBytes); + + /** Requests that a zero length status packet be sent to the host in response + to a class or vendor specific ep0 SETUP packet. + + @return KErrNone if successful. + */ + inline TInt SendEp0StatusPacket(); + + /** Stalls endpoint aEndpoint, usually to indicate an error condition with a previous command. + The host will normally send a SET_FEATURE command on ep0 to acknowledge and clear the stall. + + @return KErrNone if successful. + */ + inline TInt HaltEndpoint(TEndpointNumber aEndpoint); + + /** Clears the stall condition on endpoint aEndpoint. This is inluded for symmetry and test purposes. + + @return KErrNone if successful. + */ + inline TInt ClearHaltEndpoint(TEndpointNumber aEndpoint); + + /** Requests that device control be allocated to this channel. + + @return KErrNone if successful. + */ + inline TInt SetDeviceControl(); + + /** Relinquishes device control previously allocated to this channel. + + @return KErrNone if successful. + */ + inline TInt ReleaseDeviceControl(); + + /** Returns a bitmap of available ep0 maximum packet sizes. + + @return bitmap of available ep0 maximum packet sizes. + */ + inline TUint EndpointZeroMaxPacketSizes(); + + /** Requests that a maximum packet size of aMaxPacketSize be set on ep0. + + @param aMaxPacketSize The maximum packet size. + + @return KErrNone if successful. + */ + inline TInt SetEndpointZeroMaxPacketSize(TInt aMaxPacketSize); + + /** Queries the current maximum packet size on ep0. + + @return The currently set maximum packet size on ep0. + */ + inline TInt GetEndpointZeroMaxPacketSize(); + + /** Copies the current device descriptor into aDeviceDescriptor. + + @param aDeviceDescriptor Receives the current device descriptor. + + @return KErrNone if successful. + */ + inline TInt GetDeviceDescriptor(TDes8& aDeviceDescriptor); + + /** Sets the contents of aDeviceDescriptor to be the current device descriptor. + + @param aDeviceDescriptor contains the device descriptor. + + @return KErrNone if successful. + */ + inline TInt SetDeviceDescriptor(const TDesC8& aDeviceDescriptor); + + /** Gets the size of the current device descriptor. This is unlikely to be anything other than 9. + + @param aSize receives the size of the current device descriptor. + + @return KErrNone if successful. + */ + inline TInt GetDeviceDescriptorSize(TInt& aSize); + + /** Copies the current configuration descriptor into aConfigurationDescriptor. + + @param aConfigurationDescriptor Receives the current configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt GetConfigurationDescriptor(TDes8& aConfigurationDescriptor); + + /** Sets the contents of aConfigurationDescriptor to be the current configuration descriptor. + + @param aConfigurationDescriptor contains the configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt SetConfigurationDescriptor(const TDesC8& aConfigurationDescriptor); + + /** Gets the size of the current configuration descriptor. + + @param aSize receives the size of the current configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt GetConfigurationDescriptorSize(TInt& aSize); + + /** Copies the interface descriptor into aInterfaceDescriptor for the interface with alternate + setting aSettingNumber, 0 for the main interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Receives the interface descriptor. + + @return KErrNone if successful. + */ + inline TInt GetInterfaceDescriptor(TInt aSettingNumber, TDes8& aInterfaceDescriptor); + + /** Sets the interface descriptor contained in aInterfaceDescriptor for the interface with + alternate setting aSettingNumber, 0 for the main interface, for transmission to the host + during enumeration. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Contains the interface descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetInterfaceDescriptor(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor); + + /** Copies the size of the interface descriptor for the interface with alternate + setting aSettingNumber, 0 for the main interface, into aSize. + + @param aSettingNumber The alternate setting. + @param aSize receives the size of the interface descriptor. + + @return KErrNone if successful. + */ + inline TInt GetInterfaceDescriptorSize(TInt aSettingNumber, TInt& aSize); + + /** Copies the endpoint descriptor for logical endpoint number aEndpointNumber into aEndpointDescriptor + for the interface with alternate setting aSettingNumber, 0 for the main interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber. + @param aEndpointDescriptor Receives the endpoint descriptor. + + @return KErrNone if successful. + */ + inline TInt GetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, TDes8& aEndpointDescriptor); + + /** Sets the endpoint descriptor for logical endpoint number aEndpointNumber contained in + aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface, + for transmission to the host during enumeration. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aEndpointDescriptor Contains the endpoint descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, + const TDesC8& aEndpointDescriptor); + + /** Copies the size of the endpoint descriptor for logical endpoint number aEndpointNumber for the + interface with alternate setting aSettingNumber, 0 for the main interface, into aSize. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aSize receives the size of the endpoint descriptor. + + @return KErrNone if successful. + */ + inline TInt GetEndpointDescriptorSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize); + + /** Get OTG descriptor size + + @param aSize TInt reference which contains OTG descriptor size on return + */ + inline void GetOtgDescriptorSize(TInt& aSize); + + /** Get OTG descriptor of USB on-the-go feature + + @param aOtgDesc User-side buffer to store copy of descriptor + + @return KErrNone if successful + */ + inline TInt GetOtgDescriptor(TDes8& aOtgDesc); + + /** Set OTG descriptor by user to enable/disable USB on-the-go feature + + @param aOtgDesc Descriptor buffer containing OTG features + + @return KErrNone if successful + */ + inline TInt SetOtgDescriptor(const TDesC8& aOtgDesc); + + /** Copies the current device_qualifier descriptor into aDescriptor. + + @param aDescriptor Receives the current device_qualifier descriptor. + + @return KErrNone if successful. + */ + inline TInt GetDeviceQualifierDescriptor(TDes8& aDescriptor); + + /** Sets the device_qualifier descriptor to the contents of aDescriptor. + + @param aDescriptor contains the new device_qualifier descriptor. + + @return KErrNone if successful. + */ + inline TInt SetDeviceQualifierDescriptor(const TDesC8& aDescriptor); + + /** Copies the current other_speed_configuration descriptor into aDescriptor. + + @param aDescriptor Receives the current other_speed_configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt GetOtherSpeedConfigurationDescriptor(TDes8& aDescriptor); + + /** Sets the other_speed_configuration descriptor to the contents of aDescriptor. + + @param aDescriptor contains the new other_speed_configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt SetOtherSpeedConfigurationDescriptor(const TDesC8& aDescriptor); + + /** Copies the class specific interface descriptor block into aInterfaceDescriptor for the interface + with alternate setting aSettingNumber, 0 for the main interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Contains the interface descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt GetCSInterfaceDescriptorBlock(TInt aSettingNumber, TDes8& aInterfaceDescriptor); + + /** aSettingNumber is the alternate interface setting, 0 for the main interface, that the descriptor block + aDes should be attached to. aDes is a block of data containing at least one class specific descriptor + for transmission during enumeration after the class interface descriptor (or alternate interface + descriptor) has been sent, but before the endpoint descriptors belonging to this interface are sent. + aDes may contain as many descriptors as are necessary or only 1. SetCSInterfaceDescriptorBlock() + should be called at any time after SetInterface() has been called to establish a main interface or an + alternate interface. More than one call may be made - the data blocks will be concatenated prior to + sending. No checking or validation of the contents of aDes will be made and it is the caller's + responsibility to ensure that the data supplied is correct and appropriate to the interface identified + by aSettingNumber. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Contains the interface descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetCSInterfaceDescriptorBlock(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor); + + /** Copies the size of the class specific interface descriptor block for the interface with alternate + setting aSettingNumber, 0 for the main interface, into aSize. + + @param aSettingNumber The alternate setting number. + @param aSize receives the size of the interface descriptor. + + @return KErrNone if successful. + */ + inline TInt GetCSInterfaceDescriptorBlockSize(TInt aSettingNumber, TInt& aSize); + + /** Copies the class specific endpoint descriptor for logical endpoint number aEndpointNumber + into aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main + interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aEndpointDescriptor Receives the endpoint descriptor. + + @return KErrNone if successful. + */ + inline TInt GetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber, + TDes8& aEndpointDescriptor); + + /** Sets the class specific endpoint descriptor for logical endpoint number aEndpointNumber contained in + aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface, + for transmission to the host during enumeration. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aEndpointDescriptor Contains the endpoint descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber, + const TDesC8& aEndpointDescriptor); + + /** Copies the size of the class specific endpoint descriptor block for logical endpoint number + aEndpointNumber for the interface with alternate setting aSettingNumber, 0 for the main interface, + into aSize. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aSize On return, contains the size of the class specific endpoint descriptor block. + + @return KErrNone if successful. + */ + inline TInt GetCSEndpointDescriptorBlockSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize); + + /** Generates a Remote Wakeup bus condition + The capability of the device to generate Remote Wakeup signalling is enquired in + RDevUsbcClient::DeviceCaps. + + @return KErrNone if this signalling is possible and the signal has been generated. + */ + inline TInt SignalRemoteWakeup(); + + /** Simulates a physical removal of the USB cable by disabling the D+/- pull-ups.The iConnect member of + TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality is + supported. + + @return KErrNone if successful. + */ + inline TInt DeviceDisconnectFromHost(); + + /** Simulates a physical insertion of the USB cable by enabling the D+/- pull-ups.The iConnect member + of TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality + is supported. + + @return KErrNone if successful. + */ + inline TInt DeviceConnectToHost(); + + /** Powers up the UDC and connects it to the bus if one or more interfaces exist. + + @return KErrNone if UDC successfully powered up, KErrNotReady if no + interfaces have been registered yet, KErrHardwareNotAvailable if UDC + couldn't be activated. + */ + inline TInt PowerUpUdc(); + + /** Enquires about the current operating speed of the UDC. + + @return ETrue if the UDC is currently operating at High speed, EFalse otherwise. + */ + inline TBool CurrentlyUsingHighSpeed(); + + /** Allocates the use of aResource to aEndpoint. it will be used from when the current bus transfer has been + completed. + + @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint + behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. + @param aEndpoint The endpoint number to which the resource is to be allocated. + + @return KErrNone if successful, KErrInUse if the resource is already consumed and cannot be allocated, + KErrNotSupported if the endpoint does not support the resource requested. + + @publishedPartner @deprecated + + @see TUsbcEndpointInfo + */ + inline TInt AllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource); + + /** Deallocates the use of aResource aEndpoint or ends a specified endpoint behaviour. + + @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint + behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. + @param aEndpoint The endpoint number from which the resource is to be removed. + + @return KErrNone if the resource has been successfully deallocated, KErrNotSupported if the endpoint + does not support the resource requested. + + @publishedPartner @deprecated + + @see TUsbcEndpointInfo + */ + inline TInt DeAllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource); + + /** Queries endpoint resource use. + + @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint + behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. + @param aEndpoint The endpoint number at which the resource is to be queried. + + @return ETrue is the specified resource is in use at the endpoint and EFalse if not. + */ + inline TBool QueryEndpointResourceUse(TInt aEndpoint, TUsbcEndpointResource aResource); + + /** Request (i.e. claim for this channel) up to five endpoints and set the class type for this USB + interface. 'aInterfaceData' is a package buffer which describes the interface and all the endpoints + being requested by the driver for this interface. + + @param aInterfaceNumber Distinguishes between alternate interfaces. If these are not be used then this + should always be zero. If this parameter is used, then its value must be one more than that of the + proceeding alternate interface. + @param aInterfaceData a package buffer which describes the interface and all the endpoints being + requested by the driver for this interface. + @param aBandwidthPriority is a bitmap combining the required IN and OUT priorities. Values are in the + range [0,3] from the lowest priority bandwidth, 0, to the highest 3 and are separately specified for + IN and OUT endpoints. Interfaces requiring higher bandwidth are allocated significantly more buffering + than low bandwidth interfaces. Interfaces should not be given a higher bandwidth priority than they + require. + + @return KErrInUse if any of the endpoints being requested have already been claimed by another channel + KErrNotSupported if an endpoint with all of the specified properties is not supported on this + platform. KErrNoMemory if insufficient memory is available to complete the operation. + */ + inline TInt SetInterface(TInt aInterfaceNumber, TUsbcInterfaceInfoBuf& aInterfaceData, + TUint32 aBandwidthPriority = + (EUsbcBandwidthOUTDefault | EUsbcBandwidthINDefault)); + + /** Release an interface previously claimed by this channel. Alternate interfaces need to be released + in strict descending order, starting with the last (i.e. highest numbered) one. + It is not necessary to release an interface that wasn't successfully requested. + + @param aInterfaceNumber Specifies the alternate setting number 'aInterfaceNum' of the interface to be + released. + + @return KErrNone if successful. KErrArgument if the alternate setting doesn't exist or is released out + of order. + */ + inline TInt ReleaseInterface(TInt aInterfaceNumber); + + /** Copies the current string descriptor language ID (LANGID) code into the aLangId argument. Even though + the USB spec allows for the existence of a whole array of LANGID codes, we only support one. + + @param aLangId receives the LANGID code. + + @return KErrNone if successful, KErrArgument if problem with argument (memory cannot be written to, etc.). + */ + inline TInt GetStringDescriptorLangId(TUint16& aLangId); + + /** Sets the string descriptor language ID (LANGID). Even though the USB spec allows for the existence of + a whole array of LANGID codes, we only support one. + + @param aLangId the LANGID code to be set. + + @return KErrNone if successful. + */ + inline TInt SetStringDescriptorLangId(TUint16 aLangId); + + /** Copies the string descriptor identified by the iManufacturer index field of the Standard Device + Descriptor into the aString argument. + + @param aString receives manufacturer string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetManufacturerStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iManufacturer index field of the Standard Device + Descriptor to the aString argument. + + @param aString Contains the new manufacturer string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetManufacturerStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iManufacturer index field of the Standard + Device Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveManufacturerStringDescriptor(); + + /** Retrieves the string descriptor identified by the iProduct index field of the Standard Device + Descriptor into the aString argument. + + @param aString receives product string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetProductStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iProduct index field of the Standard Device Descriptor to + the aString argument. + + @param aString Contains the new product string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetProductStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iProduct index field of the Standard Device + Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveProductStringDescriptor(); + + /** Retrieves the string descriptor identified by the iSerialNumber index field of the Standard Device + Descriptor into the aString argument. + + @param aString receives product string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetSerialNumberStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iSerialNumber index field of the Standard Device + Descriptor to the aString argument. + + @param aString Contains the new serial number string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetSerialNumberStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iSerialNumber index field of the Standard + Device Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveSerialNumberStringDescriptor(); + + /** Retrieves the string descriptor identified by the iConfiguration index field of the (first) Standard + Configuration Descriptor into the aString argument. + + @param aString receives configuration string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetConfigurationStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iConfiguration index field of the Standard Configuration + Descriptor to the aString argument. + + @param aString Contains the new serial number string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetConfigurationStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iConfiguration index field of the Standard + Configuration Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveConfigurationStringDescriptor(); + + /** Copies the string of the USB string descriptor at the specified index in the string descriptor array + into the aString argument. + + Although this function can also be used for it, for querying most standard string descriptors + there exists a set of dedicated access functions. + + @see RDevUsbcClient::GetStringDescriptorLangId + @see RDevUsbcClient::GetManufacturerStringDescriptor + @see RDevUsbcClient::GetProductStringDescriptor + @see RDevUsbcClient::GetSerialNumberStringDescriptor + @see RDevUsbcClient::GetConfigurationStringDescriptor + + @param aIndex The position of the string descriptor in the string descriptor array. + @param aString The target location for the string descriptor copy. + + @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index, + KErrArgument if MaxLength() of aString is too small to hold the entire descriptor. + */ + inline TInt GetStringDescriptor(TUint8 aIndex, TDes16& aString); + + /** Sets the aString argument to be the string of a USB string descriptor at the specified index in the + string descriptor array. If a string descriptor already exists at that position then its string will + be replaced. + + Care should be taken, when choosing aIndex, not to inadvertently overwrite one of the standard + string descriptors. For their manipulation there exists a set of dedicated access functions. + + @see RDevUsbcClient::SetStringDescriptorLangId + @see RDevUsbcClient::SetManufacturerStringDescriptor + @see RDevUsbcClient::SetProductStringDescriptor + @see RDevUsbcClient::SetSerialNumberStringDescriptor + @see RDevUsbcClient::SetConfigurationStringDescriptor + + @param aIndex The position of the string descriptor in the string descriptor array. + @param aString Contains the string descriptor to be set. + + @return KErrNone if successful, KErrArgument if aIndex is invalid, KErrNoMemory if no memory + is available to store the new string (an existing descriptor at that index will be preserved). + */ + inline TInt SetStringDescriptor(TUint8 aIndex, const TDesC16& aString); + + /** Removes (deletes) the USB string descriptor at the specified index in the string descriptor array. + The position in the array of other string descriptors is not affected. + + Care should be taken, when choosing aIndex, not to inadvertently delete a standard string descriptor + (also because index references from non-string descriptors would be invalidated). For the deletion + of most standard string descriptors there exists a set of dedicated functions. + + @see RDevUsbcClient::RemoveManufacturerStringDescriptor + @see RDevUsbcClient::RemoveProductStringDescriptor + @see RDevUsbcClient::RemoveSerialNumberStringDescriptor + @see RDevUsbcClient::RemoveConfigurationStringDescriptor + + @param aIndex The position of the string descriptor in the string descriptor array. + + @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index. + */ + inline TInt RemoveStringDescriptor(TUint8 aIndex); + + /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. + Request completes when the specified number of bytes is received, length taken from max. length of + descriptor. + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + */ + inline void Read(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes); + + /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. + Request completes when the specified number of bytes is received. + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + @param aLen The number of bytes to read. + */ + inline void Read(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aLen); + + /** Asynchronously read an entire packet of data from endpoint 'aEndpoint' into the descriptor 'aDes'. + If a packet has previously been partly read. then only the remainder of the packet will be returned. + The request should be for the maximum packet size of the endpoint. If less data is requested, then + after this read completes the remainder of the data in the packet will be discarded and the next read + will start from the next available packet. + Request completes when either a complete packet is received or the length of the packet currently + being received exceeds 'aMaxLen'. + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + @param aMaxLen . + */ + inline void ReadPacket(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aMaxLen); + + /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. + Request completes when the specified number of bytes is received (in first version, + length taken from max. length of descriptor). + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + */ + inline void ReadUntilShort(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes); + + /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. + Request completes when the specified number of bytes is received (in first version, + length taken from max. length of descriptor). + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + @param aLen The number of bytes to receive. + */ + inline void ReadUntilShort(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aLen); + + /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. The request completes + when the specified number of bytes is received, length taken from max. length of descriptor or a + packet whose size is smaller than the endpoint's maximum packet size is received. + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + */ + inline void ReadOneOrMore(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes); + + /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. The request completes + when the specified number of bytes is received, or a packet whose size is smaller than the endpoint's + maximum packet size is received. + + @param aStatus The request status. + @param aEndpoint The endpoint number to read from. + @param aDes Descriptor to receive the data. + @param aLen The number of bytes to receive. + */ + inline void ReadOneOrMore(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aLen); + + /** Cancels an outstanding read request. The request will complete with whatever data is available. + */ + inline void ReadCancel(TEndpointNumber aEndpoint); + + /** Asynchronously write 'aLen' bytes of data to endpoint 'aEndpoint' from descriptor 'aDes'. 'aZlpRequired' + (optional) signals that ZLP termination may be required. + + @param aStatus The request status. + @param aEndpoint The endpoint number to write to. + @param aDes Descriptor to provide the data. + @param aLen The number of bytes of data to be written. + @param aZlpRequired True, if ZLP termination is required; false, otherwise. + */ + inline void Write(TRequestStatus& aStatus, TEndpointNumber aEndpoint, const TDesC8& aDes, TInt aLen, + TBool aZlpRequired=EFalse); + + /** Cancels an outstanding write request on endpoint aEndpoint. + + @param aEndpoint The endpoint number whose write is to be cancelled. + */ + inline void WriteCancel(TEndpointNumber aEndpoint); + + /** Cancels any transfer on any endpoint specified in aEndpointMask. + + @code + // Cancel transfer requests on endpoints 1, 2 & 3 + usbPort.EndpointTransferCancel(KUsbcEndpoint1Bit | KUsbcEndpoint2Bit | KUsbcEndpoint3Bit); + @endcode + + @param aEndpointMask bitmap of the endpoints. + */ + inline void EndpointTransferCancel(TUint aEndpointMask); + + /** Register for notification when a change of the Interface alternate setting or the USB Controller's + current state occurs. When the alternate setting or the Controller state changes, then the + asynchronous function completes and the current alternate setting number or Controller state is + written back to aValue. If the KUsbAlternateSetting bit is set then the remaining bits are the + alternate setting number. Otherwise aValue is interpreted as a TUsbcDeviceState. + + @see TUsbcDeviceState + + @param aStatus The request status. + @param aValue Receives the alternate setting number or Controller state. + */ + inline void AlternateDeviceStatusNotify(TRequestStatus& aStatus, TUint& aValue); + + /** Completes an AlternateDeviceStatusNotify request. If a request has previously been made then the + status variable is updated with the current device state. + */ + inline void AlternateDeviceStatusNotifyCancel(); + + /** If the channel has changed the grouping of endpoints between interfaces or changed the interface class + type from the defaults then it is necessary to force a re-enumeration. This will typically involve the + Symbian OS device initiating a disconnection and re-connection. This is an asynchronous operation + which will complete when the Controller is successfully configured by the host, i.e. has achieved + EUsbcDeviceStateConfigured. Since it is not known if the operation has failed, at the same time that + a ReEnumerate request is made, a timer should be set up to complete after approximately 5 seconds. It + can be assumed that if the operation has not completed after this time interval then it will not + complete. + + @param aStatus The request status. + */ + inline void ReEnumerate(TRequestStatus& aStatus); + + /** Cancels an outstanding ReEnumerate() request. + */ + inline void ReEnumerateCancel(); + + /** Register for notification when a change in stall status of any of the interface's endpoints occurs, + but not ep0. When a change in stall status occurs, then the asynchronous function completes and the + current stall state is written back to 'aEndpointStatus' as a bit map: Only stall state changes caused + by SET_FEATURE and CLEAR_FEATURE standard commands on ep0 will be notified when this function + completes. After this request completes the request should be re-issued to obtain future + notifications. + + @param aStatus The request status. + @param aEndpointMask a bitmap of the endpoints stall status. This is filled in when the call completes + bit 1 represents the interface's virtual endpoint 1, (KUsbcEndpoint1Bit) + bit 2 represents the interface's virtual endpoint 2, (KUsbcEndpoint2Bit) etc. + bit value 0 - not stalled, + bit value 1 - stalled. + */ + inline void EndpointStatusNotify(TRequestStatus& aStatus, TUint& aEndpointMask); + + /** Completes an endpoint status notify request. + */ + inline void EndpointStatusNotifyCancel(); + + /** Get current on-the-go features relating to the ability of device/host pair to + perform OTG role swap. + + @param aFeatures On return it contanis features the device currently has + bit 2 represents b_hnp_enable, (KUsbOtgAttr_B_HnpEnable) + bit 3 represents a_hnp_support, (KUsbOtgAttr_A_HnpSupport) + bit 4 represents a_alt_hnp_support, (KUsbOtgAttr_A_AltHnpSupport) + @return KErrNone if successful, KErrNotSupported if OTG is not supported by + this device, otherwise system-wide error returns + */ + inline TInt GetOtgFeatures(TUint8& aFeatures); + + /** Register for notification on USB on-the-go features' change. If any OTG feature + is changed, request completes and current feature value is filled in aValue. + + @param aStatus Request status object + @param aValue On request completion, it contains current OTG feature value + */ + inline void OtgFeaturesNotify(TRequestStatus& aStatus, TUint8& aValue); + + /** Cancel pending OTG feature request. + */ + inline void OtgFeaturesNotifyCancel(); + +#endif // #ifndef __KERNEL_MODE__ + }; + + +#include + + +#endif // __D32USBC_H__