// 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 <e32ver.h>

#include <usb.h>

#include <d32usbcshared.h>

/** @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<<EEndpoint0;

/** Bit position of endpoint1.

*/

const TUint KUsbcEndpoint1Bit = 1<<EEndpoint1;

/** Bit position of endpoint2.

*/

const TUint KUsbcEndpoint2Bit = 1<<EEndpoint2;

/** Bit position of endpoint3.

*/

const TUint KUsbcEndpoint3Bit = 1<<EEndpoint3;

/** Bit position of endpoint4.

*/

const TUint KUsbcEndpoint4Bit = 1<<EEndpoint4;

/** Bit position of endpoint5.

*/

const TUint KUsbcEndpoint5Bit = 1<<EEndpoint5;

/** This must be filled in prior to a call to RDevUsbcClient::SetInterface().

*/

class TUsbcInterfaceInfo

	{

public:

	TUsbcInterfaceInfo(TInt aClass=0, TInt aSubClass=0, TInt aProtocol=0,

					   TDesC16* aString=NULL, TUint aTotalEndpoints=0);

public:

	/** The class, subclass and protocol that this interface supports. */

	TUsbcClassInfo iClass;

	/** The description string for the interface. Used to construct the interface string descriptor. */

	const TDesC16* iString;

	/** Total number of endpoints being requested (0-5). Endpoint 0 should not be included in this number. */

	TUint iTotalEndpointsUsed;

	/** Desired properties of the endpoints requested.

		Do NOT include endpoint 0.

		APIs use endpoint numbers that are offsets into this array.

	*/

	TUsbcEndpointInfo iEndpointData[KMaxEndpointsPerClient];

	/** 32 flag bits used for specifying miscellaneous Interface features.

		Currently defined are:

		- KUsbcInterfaceInfo_NoEp0RequestsPlease = 0x00000001

	*/

	TUint32 iFeatureWord;

	};

/** Package buffer for a TUsbcInterfaceInfo object.

	@see TUsbcInterfaceInfo

*/

typedef TPckgBuf<TUsbcInterfaceInfo> 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<<ERequestEp0,

		ERequestEp1Cancel = 1<<ERequestEp1,

		ERequestEp2Cancel = 1<<ERequestEp2,

		ERequestEp3Cancel = 1<<ERequestEp3,

		ERequestEp4Cancel = 1<<ERequestEp4,

		ERequestEp5Cancel = 1<<ERequestEp5,

		ERequestUnusedCancel = 1<<ERequestUnused,

        ERequestAllCancel = (ERequestEp0Cancel | ERequestEp1Cancel |

							 ERequestEp2Cancel | ERequestEp3Cancel |

							 ERequestEp4Cancel | ERequestEp5Cancel |

							 ERequestUnusedCancel),

		ERequestAlternateDeviceStatusNotifyCancel = 1<<ERequestAlternateDeviceStatusNotify,

		ERequestReEnumerateCancel = 1<<ERequestReEnumerate,

		ERequestEndpointStatusNotifyCancel = 1<<ERequestEndpointStatusNotify,

        ERequestOtgFeaturesNotify = 10,

        ERequestOtgFeaturesNotifyCancel = 1<<ERequestOtgFeaturesNotify,

		};

	enum TControl

		{

		// Changing the order of these enums will break BC.

		EControlEndpointZeroRequestError,					// 0

		EControlEndpointCaps,

		EControlDeviceCaps,

		EControlGetAlternateSetting,

		EControlDeviceStatus,

		EControlEndpointStatus,

		EControlSetInterface,

		EControlReleaseInterface,

		EControlQueryReceiveBuffer,

		EControlSendEp0StatusPacket,						// 9

		//

		EControlHaltEndpoint,								// 10

		EControlClearHaltEndpoint,

		EControlSetDeviceControl,

		EControlReleaseDeviceControl,

		EControlEndpointZeroMaxPacketSizes,

		EControlSetEndpointZeroMaxPacketSize,

		EControlGetDeviceDescriptor,

		EControlSetDeviceDescriptor,

		EControlGetDeviceDescriptorSize,

		EControlGetConfigurationDescriptor,					// 19

		//

		EControlSetConfigurationDescriptor,					// 20

		EControlGetConfigurationDescriptorSize,

		EControlGetInterfaceDescriptor,

		EControlSetInterfaceDescriptor,

		EControlGetInterfaceDescriptorSize,

		EControlGetEndpointDescriptor,

		EControlSetEndpointDescriptor,

		EControlGetEndpointDescriptorSize,

		EControlGetCSInterfaceDescriptor,

		EControlSetCSInterfaceDescriptor,					// 29

		//

		EControlGetCSInterfaceDescriptorSize,				// 30

		EControlGetCSEndpointDescriptor,

		EControlSetCSEndpointDescriptor,

		EControlGetCSEndpointDescriptorSize,

		EControlSignalRemoteWakeup,

		EControlGetStringDescriptorLangId,

		EControlSetStringDescriptorLangId,

		EControlGetManufacturerStringDescriptor,

		EControlSetManufacturerStringDescriptor,

		EControlRemoveManufacturerStringDescriptor,			// 39

		//

		EControlGetProductStringDescriptor,					// 40

		EControlSetProductStringDescriptor,

		EControlRemoveProductStringDescriptor,

		EControlGetSerialNumberStringDescriptor,

		EControlSetSerialNumberStringDescriptor,

		EControlRemoveSerialNumberStringDescriptor,

		EControlGetConfigurationStringDescriptor,

		EControlSetConfigurationStringDescriptor,

		EControlRemoveConfigurationStringDescriptor,

		EControlDeviceDisconnectFromHost,					// 49

		//

		EControlDeviceConnectToHost,						// 50

		EControlDevicePowerUpUdc,

		EControlDumpRegisters,

		EControlSetInterface1,								// (not used)

		EControlAllocateEndpointResource,

		EControlDeAllocateEndpointResource,

		EControlQueryEndpointResourceUse,

		EControlGetEndpointZeroMaxPacketSize,

		EControlGetDeviceQualifierDescriptor,

		EControlSetDeviceQualifierDescriptor,				// 59

		//

		EControlGetOtherSpeedConfigurationDescriptor,		// 60

		EControlSetOtherSpeedConfigurationDescriptor,

		EControlCurrentlyUsingHighSpeed,

		EControlSetStringDescriptor,

		EControlGetStringDescriptor,

		EControlRemoveStringDescriptor,

        EControlSetOtgDescriptor,

        EControlGetOtgDescriptor,

        EControlGetOtgFeatures

		};

public:

#ifndef __KERNEL_MODE__

	/** Opens a channel.

		@param aUnit This should be 0 (zero).

		@return KErrNone if successful.

	*/

	inline TInt Open(TInt aUnit);

	inline TVersion VersionRequired() const;

	/** Stalls ep0 to signal command fault to the host.

		@return KErrNone if successful.

	*/

	inline TInt EndpointZeroRequestError();

	/** Retrieves the capabilities of all the endpoints on the device.

		Suggested use is as follows:

		@code

		TUsbcEndpointData data[KUsbcMaxEndpoints];

		TPtr8 dataPtr(reinterpret_cast<TUint8*>(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.