// Copyright (c) 2007-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.

//

// Description:

// Symbian USBDI Descriptors Parsing Routines.

// 

//

/**

 @file

 @publishedPartner

*/

#include <d32usbdescriptors.h>

#include "usbdescutils.h"

// ----------------

// TUsbGenericDescriptor

// ----------------

EXPORT_C TUsbGenericDescriptor::TUsbGenericDescriptor()

	: iRecognisedAndParsed(EUnrecognised)

	, iNextPeer(NULL)

	, iFirstChild(NULL)

	, iParent(NULL)

	{

	}

/**

Deletes all child and peer descriptors.  Does not delete this descriptor, the caller is responsible for

doing this separately.

*/

EXPORT_C void TUsbGenericDescriptor::DestroyTree()

	{

	// Store the tree pointers

	TUsbGenericDescriptor* child = this->iFirstChild;

	TUsbGenericDescriptor* peer = this->iNextPeer;

	// Now we chop off the tree from the root node, by doing this

	// we don't need to NULL pointers as we go down (which makes

	// the iterative algorithm more efficient).

	this->iFirstChild = NULL;

	this->iNextPeer = NULL;

	// Now we walk and destroy the tree from the two pointers

	// we have

	WalkAndDelete(child);

	WalkAndDelete(peer);

	}

void TUsbGenericDescriptor::WalkAndDelete(TUsbGenericDescriptor* aDesc)

	{

	if(!aDesc)

		{

		return;

		}

	TUsbGenericDescriptor* topLevel = aDesc->iParent;

	do

		{

		if(aDesc->iFirstChild)

			{

			// walk down the tree depth first.

			aDesc = aDesc->iFirstChild;

			}

		else if(aDesc->iNextPeer)

			{

			// Walk along each peer at the "bottom"

			TUsbGenericDescriptor* peer = aDesc->iNextPeer;

			delete aDesc;

			aDesc = peer;

			}

		else

			{

			// End of bottom tier, so we go back up to the parent

			// and null the first child pointer so we don't go back

			// down again.

			TUsbGenericDescriptor* parent = aDesc->iParent;

			delete aDesc;

			aDesc = parent;

			if(aDesc)

				{

				aDesc->iFirstChild = NULL;

				}

			// if we have gone up to the top level for destruction then we don't

			// do anymore.

			if(aDesc == topLevel)

				{

				break;

				}

			}

		}

	while(aDesc);

	}

/**

Utility method to retrieve a TUint8 value from a given offset in the descriptor.

@param aOffset The offset in the binary blob at which to retrieve the value.

@return The value from the descriptor.

*/

EXPORT_C TUint8 TUsbGenericDescriptor::TUint8At(TInt aOffset) const

	{

	return ParseTUint8(iBlob, aOffset);

	}

/**

Utility method to retrieve a TUint16 value from a given offset in the descriptor.

@param aOffset The offset in the binary blob at which to retrieve the value.

@return The value from the descriptor.

*/

EXPORT_C TUint16 TUsbGenericDescriptor::TUint16At(TInt aOffset) const

	{

	return ParseTUint16(iBlob, aOffset);

	}

/**

Utility method to retrieve a TUint32 value from a given offset in the descriptor.

@param aOffset The offset in the binary blob at which to retrieve the value.

@return The value from the descriptor.

*/

EXPORT_C TUint32 TUsbGenericDescriptor::TUint32At(TInt aOffset) const

	{

	return ParseTUint32(iBlob, aOffset);

	}

/**

Assignment operator to fill in the TUsbGenericDescriptor fields from a TUsbGenericDescriptor.

Note that if a TUsbGenericDescriptor derived class has additional member fields then

they should define a specialised assignment overload for that type.

*/

EXPORT_C TUsbGenericDescriptor& TUsbGenericDescriptor::operator=(const TUsbGenericDescriptor& aDescriptor)

	{

	ibLength = aDescriptor.ibLength;

	ibDescriptorType = aDescriptor.ibDescriptorType;

	iRecognisedAndParsed = aDescriptor.iRecognisedAndParsed;

	iNextPeer = aDescriptor.iNextPeer;

	iFirstChild = aDescriptor.iFirstChild;

	iParent = aDescriptor.iParent;

	iBlob.Set(aDescriptor.iBlob);

	return *this;

	}

/**

This function determines whether the given USB descriptor is a parent

of the descriptor the method is called on.  The implementation may be

specialised for each type of descriptor to ensure the tree is correctly

built up.

@param aPotentialRelative The USB descriptor that is being queried to see if it is a parent or peer.

@return TBool Efalse if the given USB descriptor is a parent of this USB descriptor, ETrue if a peer of this descriptor

*/

/*virtual*/ TBool TUsbGenericDescriptor::IsParent(TUsbGenericDescriptor& aPotentialParent)

	{

	// As generic descriptors we consider all other "unknown" descriptors as peers, and

	// all "known" descriptors as parents of the descriptor.

	switch(aPotentialParent.ibDescriptorType)

		{

	case EDevice:

	case EConfiguration:

	case EString:

	case EInterface:

	case EEndpoint:

	case EDeviceQualifier:

	case EOtherSpeedConfiguration:

	case EInterfacePower:

	case EOTG:

	case EDebug:

	case EInterfaceAssociation:

		return ETrue;

	default:

		return EFalse;

		}

	}

/**

This function determines whether the given USB descriptor is a peer

of the descriptor the method is called on.  The implementation may be

specialised for each type of descriptor to ensure the tree is correctly

built up.

@param aPotentialPeer The USB descriptor that is being queried to see if it is a peer.

@return TBool EFalse if the given USB descriptor is a parent of this USB descriptor, ETrue if a peer of this descriptor

*/

/*virtual*/ TBool TUsbGenericDescriptor::IsPeer(TUsbGenericDescriptor& /*aPotentialPeer*/)

	{

	// As generic descriptors we are very permissive in binding peers.

	return ETrue;

	}

/**

This function determines whether the given USB descriptor is a child

of the descriptor the method is called on.  The implementation may be

specialised for each type of descriptor to ensure the tree is correctly

built up.

@param aPotentialChild The USB descriptor that is being queried to see if it is a child.

@return TBool ETrue if the given USB descriptor is a child of this USB descriptor, ETrue if a peer of this descriptor

*/

/*virtual*/ TBool TUsbGenericDescriptor::IsChild(TUsbGenericDescriptor& /*aPotentialChild*/)

	{

	// We just use the logic in the IsParent.

	return EFalse;

	}

/**

Ensures no memory is leaked if an owned TUsbGenericDescriptor is no longer needed.

@param aPtr The TUsbGenericDescriptor that is to be cleaned up.

@internalComponent

*/

EXPORT_C /*static*/ void TUsbGenericDescriptor::Cleanup(TAny* aPtr)

	{

	TUsbGenericDescriptor* ptr = static_cast<TUsbGenericDescriptor*>(aPtr);

	ptr->DestroyTree(); // belt and braces really.

	delete ptr;

	}

// ----------------------

// TUsbDeviceDescriptor

// See section 9.6.1 of the USB 2.0 specification.

// ----------------------

EXPORT_C TUsbDeviceDescriptor::TUsbDeviceDescriptor()

	{

	}

EXPORT_C /*static*/ TUsbDeviceDescriptor* TUsbDeviceDescriptor::Cast(TUsbGenericDescriptor* aOriginal)

	{

	TUsbDeviceDescriptor* ret = NULL;

	// Only cast if correctly indentified as device descriptor

	if(	aOriginal &&

		aOriginal->ibDescriptorType == EDevice &&

		aOriginal->ibLength == TUsbDeviceDescriptor::KSizeInOctets &&

		aOriginal->iRecognisedAndParsed == ERecognised)

		{

		ret = static_cast<TUsbDeviceDescriptor*>(aOriginal);

		}

	return ret;

	}

EXPORT_C TUint16 TUsbDeviceDescriptor::USBBcd() const

	{

    return ParseTUint16(iBlob, EbcdUSB);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::DeviceClass() const

	{

	return ParseTUint8(iBlob, EbDeviceClass);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::DeviceSubClass() const

	{

	return ParseTUint8(iBlob, EbDeviceSubClass);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::DeviceProtocol() const

	{

	return ParseTUint8(iBlob, EbDeviceProtocol);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::MaxPacketSize0() const

	{

	return ParseTUint8(iBlob, EbMaxPacketSize0);

	}

EXPORT_C TUint16 TUsbDeviceDescriptor::VendorId() const

	{

	return ParseTUint16(iBlob, EidVendor);

	}

EXPORT_C TUint16 TUsbDeviceDescriptor::ProductId() const

	{

	return ParseTUint16(iBlob, EidProduct);

	}

EXPORT_C TUint16 TUsbDeviceDescriptor::DeviceBcd() const

	{

	return ParseTUint16(iBlob, EbcdDevice);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::ManufacturerIndex() const

	{

	return ParseTUint8(iBlob, EiManufacturer);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::ProductIndex() const

	{

	return ParseTUint8(iBlob, EiProduct);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::SerialNumberIndex() const

	{

	return ParseTUint8(iBlob, EiSerialNumber);

	}

EXPORT_C TUint8 TUsbDeviceDescriptor::NumConfigurations() const

	{

	return ParseTUint8(iBlob, EbNumConfigurations);

	}

/**

The parsing routine for device descriptors.

Here the previous descriptor parameter is ignored - because logically a device descriptor can be neither a peer

nor a child.

@internalComponent

*/

/*static*/ TUsbDeviceDescriptor* TUsbDeviceDescriptor::ParseL(TPtrC8& aUsbDes, TUsbGenericDescriptor* aPreviousDesc)

	{

	TUsbDeviceDescriptor* devDes = NULL;

	const TInt KMinDeviceDesDecisionLength = 2;

	if(	aUsbDes.Length() >= KMinDeviceDesDecisionLength &&

		aUsbDes[KbDescriptorTypeOffset] == EDevice &&

		aUsbDes[KbLengthOffset] == TUsbDeviceDescriptor::KSizeInOctets)

		{

		// Robustness check - check the length field is valid, and that we have enough data.

		if(aUsbDes.Length() < TUsbDeviceDescriptor::KSizeInOctets)

			{

			User::Leave(KErrCorrupt);

			}

		// Robustness check - check that the device descriptor is the first to be parsed.

		if(aPreviousDesc)

			{

			User::Leave(KErrCorrupt);

			}

		// Looks ok to be a device descriptor.

		devDes = new(ELeave) TUsbDeviceDescriptor;

		// Set the standard fields

		devDes->ibLength = TUsbDeviceDescriptor::KSizeInOctets;

		devDes->ibDescriptorType = EDevice;

		// Set the blob appropriately

		devDes->iBlob.Set(aUsbDes.Left(TUsbDeviceDescriptor::KSizeInOctets));

		devDes->iRecognisedAndParsed = ERecognised;

		// Update the data-left-to-parse Symbian descriptor

		aUsbDes.Set(aUsbDes.Mid(TUsbDeviceDescriptor::KSizeInOctets));

		}

	return devDes;

	}

/**

@internalComponent

*/

/*virtual*/ TBool TUsbDeviceDescriptor::IsParent(TUsbGenericDescriptor& /*aPotentialParent*/)

	{

	// The device descriptor should only come by itself in a bundle, so must be top-level.

	return EFalse;

	}

/**

@internalComponent

*/

/*virtual*/ TBool TUsbDeviceDescriptor::IsPeer(TUsbGenericDescriptor& /*aPotentialPeer*/)

	{

	// The device descriptor should only come by itself in a bundle, so no other peers.

	return EFalse;

	}

// ------------------------------

// TUsbDeviceQualifierDescriptor

// See section 9.6.2 of the USB 2.0 specification.

// ------------------------------

EXPORT_C TUsbDeviceQualifierDescriptor::TUsbDeviceQualifierDescriptor()

	{

	}

EXPORT_C /*static*/ TUsbDeviceQualifierDescriptor* TUsbDeviceQualifierDescriptor::Cast(TUsbGenericDescriptor* aOriginal)

	{

	TUsbDeviceQualifierDescriptor* ret = NULL;

	// Only cast if correctly indentified as device qualifier descriptor

	if(	aOriginal &&

		aOriginal->ibDescriptorType == EDeviceQualifier &&

		aOriginal->ibLength == TUsbDeviceQualifierDescriptor::KSizeInOctets &&

		aOriginal->iRecognisedAndParsed == ERecognised)

		{

		ret = static_cast<TUsbDeviceQualifierDescriptor*>(aOriginal);

		}

	return ret;

	}

EXPORT_C TUint16 TUsbDeviceQualifierDescriptor::USBBcd() const

	{

	return ParseTUint16(iBlob, EbcdUSB);

	}

EXPORT_C TUint8 TUsbDeviceQualifierDescriptor::DeviceClass() const

	{

	return ParseTUint8(iBlob, EbDeviceClass);

	}

EXPORT_C TUint8 TUsbDeviceQualifierDescriptor::DeviceSubClass() const

	{

	return ParseTUint8(iBlob, EbDeviceSubClass);

	}

EXPORT_C TUint8 TUsbDeviceQualifierDescriptor::DeviceProtocol() const

	{

	return ParseTUint8(iBlob, EbDeviceProtocol);

	}

EXPORT_C TUint8 TUsbDeviceQualifierDescriptor::MaxPacketSize0() const

	{

	return ParseTUint8(iBlob, EbMaxPacketSize0);

	}

EXPORT_C TUint8 TUsbDeviceQualifierDescriptor::NumConfigurations() const

	{

	return ParseTUint8(iBlob, EbNumConfigurations);

	}

EXPORT_C TUint8 TUsbDeviceQualifierDescriptor::Reserved() const

	{

	return ParseTUint8(iBlob, EbReserved);

	}

/**

The parsing routine for device qualifier descriptors.

@internalComponent

*/

/*static*/ TUsbDeviceQualifierDescriptor* TUsbDeviceQualifierDescriptor::ParseL(TPtrC8& aUsbDes, TUsbGenericDescriptor* /*aPreviousDesc*/)

	{

	TUsbDeviceQualifierDescriptor* devQualDes = NULL;

	const TInt KMinDevQualDesDecisionLength = 2;

	if(	aUsbDes.Length() >= KMinDevQualDesDecisionLength &&

		aUsbDes[KbDescriptorTypeOffset] == EDeviceQualifier &&

		aUsbDes[KbLengthOffset] == TUsbDeviceQualifierDescriptor::KSizeInOctets)

		{

		// Robustness check - check the length field is valid, and that we have enough data.

		if(aUsbDes.Length() < TUsbDeviceQualifierDescriptor::KSizeInOctets)

			{

			User::Leave(KErrCorrupt);

			}

		// Looks ok to be a device quialifier descriptor.

		devQualDes = new(ELeave) TUsbDeviceQualifierDescriptor;

		// Set the standard fields

		devQualDes->ibLength = TUsbDeviceQualifierDescriptor::KSizeInOctets;

		devQualDes->ibDescriptorType = EDeviceQualifier;

		// Set the blob appropriately

		devQualDes->iBlob.Set(aUsbDes.Left(TUsbDeviceQualifierDescriptor::KSizeInOctets));

		devQualDes->iRecognisedAndParsed = ERecognised;

		// Update the data-left-to-parse Symbian descriptor

		aUsbDes.Set(aUsbDes.Mid(TUsbDeviceQualifierDescriptor::KSizeInOctets));

		}

	return devQualDes;

	}

/**

@internalComponent

*/

/*virtual*/ TBool TUsbDeviceQualifierDescriptor::IsParent(TUsbGenericDescriptor& /*aPotentialParent*/)

	{

	// Like a device descriptor, they should be top-level.

	return EFalse;

	}

/**

@internalComponent

*/

/*virtual*/ TBool TUsbDeviceQualifierDescriptor::IsPeer(TUsbGenericDescriptor& /*aPotentialPeer*/)

	{

	// Like a device descriptor, they should come by themselves.

	return EFalse;

	}

// ----------------------------

// TUsbConfigurationDescriptor

// See section 9.6.3 of the USB 2.0 specification.

// ----------------------------

EXPORT_C TUsbConfigurationDescriptor::TUsbConfigurationDescriptor()

	{

	}

EXPORT_C /*static*/ TUsbConfigurationDescriptor* TUsbConfigurationDescriptor::Cast(TUsbGenericDescriptor* aOriginal)

	{

	TUsbConfigurationDescriptor* ret = NULL;

	// Only cast if correctly indentified as configuration descriptor

	if(	aOriginal &&

		aOriginal->ibDescriptorType == EConfiguration &&

		aOriginal->ibLength == TUsbConfigurationDescriptor::KSizeInOctets &&

		aOriginal->iRecognisedAndParsed == ERecognised)

		{

		ret = static_cast<TUsbConfigurationDescriptor*>(aOriginal);

		}

	return ret;

	}

EXPORT_C TUint16 TUsbConfigurationDescriptor::TotalLength() const

	{

	return ParseTUint16(iBlob, EwTotalLength);

	}

EXPORT_C TUint8 TUsbConfigurationDescriptor::NumInterfaces() const

	{

	return ParseTUint8(iBlob, EbNumInterfaces);

	}

EXPORT_C TUint8 TUsbConfigurationDescriptor::ConfigurationValue() const

	{

	return ParseTUint8(iBlob, EbConfigurationValue);

	}

EXPORT_C TUint8 TUsbConfigurationDescriptor::ConfigurationIndex() const

	{

	return ParseTUint8(iBlob, EiConfiguration);

	}

EXPORT_C TUint8 TUsbConfigurationDescriptor::Attributes() const

	{