1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 /**

    19  @file

    20  @internalComponent

    21 */

    22 

    23 #ifndef DEVICEPROXY_H

    24 #define DEVICEPROXY_H

    25 

    26 #include <e32base.h>

    27 #include "usbhoststack.h"

    28 

    29 #ifdef __OVER_DUMMYUSBDI__

    30 #include <usbhost/dummyusbdi/d32usbdi_hubdriver.h>

    31 #else

    32 #include <d32usbdi_hubdriver.h>

    33 #endif

    34 

    35 class TDeviceEvent;

    36 class TOtgDescriptor;

    37 

    38 NONSHARABLE_CLASS(CDeviceProxy) : public CBase

    39 	{

    40 public:

    41 	/** Link between elements of this type in a TSglQue. */

    42 	TSglQueLink iLink;

    43 

    44 public:

    45 	static CDeviceProxy* NewL(RUsbHubDriver& aHubDriver, TUint aDeviceId);

    46 	~CDeviceProxy();

    47 

    48 public: // querying information from the device

    49 	TInt GetDeviceDescriptor(TUsbDeviceDescriptor& aDescriptor);

    50 	TInt GetConfigurationDescriptor(TUsbConfigurationDescriptor& aDescriptor) const;

    51 	const RArray<TUint>& GetSupportedLanguages() const;

    52 	void GetManufacturerStringDescriptorL(TUint32 aLangId, TName& aString) const;

    53 	void GetProductStringDescriptorL(TUint32 aLangId, TName& aString) const;

    54 	void GetSerialNumberStringDescriptorL(TUint32 aLangId, TName& aString) const;

    55 	

    56 	void GetOtgDescriptorL(TOtgDescriptor& aDescriptor) const;

    57 	void SetOtgDescriptorL(const TUsbOTGDescriptor& aDescriptor);

    58 

    59 public: // management

    60 	TInt GetTokenForInterface(TUint aIndex, TUint32& aToken) const;

    61 	TUint DeviceId() const;

    62 	void SetDriverLoadingEventData(TDriverLoadStatus aStatus, TInt aError = KErrNone);

    63 	TInt Suspend();

    64 

    65 	// These methods TAKE OWNERSHIP of the relevant objects.

    66 	TDeviceEvent* GetAttachmentEventObject();

    67 	TDeviceEvent* GetDriverLoadingEventObject();

    68 	TDeviceEvent* GetDetachmentEventObject();

    69 	inline void SetMultipleDriversFlag()

    70 	{

    71 		iMultipleDriversFound = ETrue;

    72 	}

    73 

    74 	inline TBool MultipleDriversFlag()

    75 	{

    76 		return iMultipleDriversFound;

    77 	}

    78 	inline void SetHasIADFlag()

    79 	{

    80 		iHasIAD = ETrue;

    81 	}

    82 	inline TBool HasIADFlag()

    83 	{

    84 		return iHasIAD;

    85 	}

    86 

    87 private:

    88 	CDeviceProxy(TUint aDeviceId);

    89 	void ConstructL(RUsbHubDriver& aHubDriver);

    90 

    91 private: // utility

    92 	void Log();

    93 	void ReadStringDescriptorsL();

    94 	void PopulateStringDescriptorsL(TUint8 aStringDescriptorIndex, RArray<TName>& aStringArray);

    95 	void GetStringDescriptorFromUsbdL(TUint32 aLangId, TName& aString, TUint8 aStringDescriptorIndex) const;

    96 	void GetStringDescriptorFromCacheL(TUint32 aLangId, TName& aString, const RArray<TName>& aStringArray) const;

    97 

    98 private: // owned

    99 	RUsbDevice iHandle;

   100 	const TUint iId;

   101 

   102 	TDeviceEvent* iAttachmentEvent;

   103 	TDeviceEvent* iDriverLoadingEvent;

   104 	TDeviceEvent* iDetachmentEvent;

   105 

   106 	// The design of string descriptor access in this class deserves some 

   107 	// explanation.

   108 	// In the simplest implementation of the FDF, we handle a device 

   109 	// attachment without getting or storing any string descriptors from the 

   110 	// device. If the FDF doesn't load any drivers for the device, it must 

   111 	// suspend the device to save power. If USBMAN, subsequent to this, 

   112 	// queries any string descriptors, the FDF will have to resume the device 

   113 	// first (string descriptors are not requested or cached by USBD). 

   114 	// Resuming a device is an asynchronous operation. We must therefore 

   115 	// either make querying a string descriptor asynchronous as far as USBMAN 

   116 	// is concerned (which would clearly make the relevant APIs much less 

   117 	// friendly) or find another way round. [For completeness: this 

   118 	// asynchronicity would rely on 

   119 	// RHubDriver::QueueDeviceStateChangeNotification.]

   120 	// Solution 1: if the FDF doesn't load drivers for the device, wait until 

   121 	// USBSVR has queried string descriptors from us before suspending the 

   122 	// device. Con: USBMAN only queries string descriptors when its client (in 

   123 	// licensee-land) does so. We can't make any assumptions about their doing 

   124 	// it in a timely manner or indeed at all. 

   125 	// Solution 2: use User::After to give the device time to resume 

   126 	// synchronously. Con: this is a major no-no in a production thread which 

   127 	// must remain responsive to user requests and lower-level events. 

   128 	// Mentioned only for completeness.

   129 	// Solution 3 (implemented): request and cache all supported string 

   130 	// descriptors at attachment time. String descriptors are typically small 

   131 	// (a dozen characters, say), we only support 3 of them (manufacturer, 

   132 	// product and serial number- not all of which may actually be supported 

   133 	// by a particular device) and there is usually only 1 language, if that. 

   134 	// Having cached the string descriptors, it is trivial to look them up 

   135 	// later when the client wants.

   136 	// These arrays are tied together, i.e. iManufacturerStrings[2] is the 

   137 	// manufacturer string in the language with ID iLangIds[2]. Note that this 

   138 	// may be KNullDesC if the device doesn't support the manufacturer string 

   139 	// descriptor, but there's still an entry in the array for it.

   140 	RArray<TUint> iLangIds;

   141 	RArray<TName> iManufacturerStrings;

   142 	RArray<TName> iProductStrings;

   143 	RArray<TName> iSerialNumberStrings;

   144 	TBool		  iHasIAD;

   145 	TBool         iMultipleDriversFound;

   146 	TOtgDescriptor* iOtgDescriptor; // Owned

   147 	};

   148 

   149 #endif // DEVICEPROXY_H