diff -r 703a2b94c06c -r dde4619868dc tsrc/testtools/usbman_stub/usbman/client/public/usbman.h --- a/tsrc/testtools/usbman_stub/usbman/client/public/usbman.h Wed Sep 15 13:20:24 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,705 +0,0 @@ -/* -* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies). -* All rights reserved. -* This component and the accompanying materials are made available -* under the terms of "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: -* -*/ - -/** - @file -*/ - -#ifndef __USBMAN_H__ -#define __USBMAN_H__ - -#include -#include -#include -#include - -// The propery of a personality is a bitmap, and bit 0 is used to identify -// whether a personality is hidden. -const TUint32 KUsbPersonalityPropertyHidden = 0x00000001; - -NONSHARABLE_CLASS(RUsb) : public RSessionBase -/** -The RUsb class implements the Symbian OS USB Management API RUsb - -@publishedPartner -@released -*/ - { -public: - - // Request types, the interest of which can be cancelled by clients - enum TUsbReqType - { - EStart, - EStop, - ETryStart, - ETryStop - }; - - /** - Constructor - - - @since 7.0 - - @publishedPartner - @released - */ - IMPORT_C RUsb(); - - /** - Destructor - - - @since 7.0 - - @publishedPartner - @released - */ - IMPORT_C ~RUsb(); - - /** - Extract the version of the server providing the RUsb API - - - @since 7.0 - - @return Version of the server - - @publishedPartner - @released - */ - IMPORT_C TVersion Version() const; - - /** - Connect the Handle to the Server - Must be called before all other methods except Version() - - - @since 7.0 - - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt Connect(); - - /** - Start the device's USB service. Should not be called if the USB services - have already been started - Note: Asynchonous Version, outcome returned when the status is completed - - - @since 7.0 - @param aStatus Status to complete once the start operation has completed - @capability NetworkControl - - @publishedPartner - @released - */ - IMPORT_C void Start(TRequestStatus& aStatus); - - /** - Cancels the pending start operation of the device's USB service. - - - @since 7.0 - @capability NetworkControl - - @publishedPartner - @released - */ - IMPORT_C void StartCancel(); - - /** - Stops the device's USB service. Should not be called if the USB services - have not been started. This is the synchronous variant of this function. - This function is deprecated- use the asynchronous version. - - - @since 7.0 - @capability NetworkControl - - @publishedPartner - @released - */ - IMPORT_C void Stop(); - - /** - Stops the device's USB service. Should not be called if the USB services - have not been started. This is the asynchronous variant of this function. - - - @since 7.0s - @param aStatus Status to complete once the stop operation has completed - @capability NetworkControl - - @publishedPartner - @released - */ - IMPORT_C void Stop(TRequestStatus& aStatus); - - /** - Cancels the pending stop operation of the device's USB service. - - - @since 7.0s - @capability NetworkControl - - @publishedPartner - @released - */ - IMPORT_C void StopCancel(); - - /** - Get the current state of the device's USB service. - - - @since 7.0s - @param aState Set by the method to the current state of the USB service - - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt GetServiceState(TUsbServiceState& aState); - - /** - Request to be notified of a change in service state of the USB device. The - request only completes when the service state changes. - - - @since 7.0s - @param aState State variable to be written to upon completion of the request - @param aStatus Status to complete when required state change occurs - - @publishedPartner - @released - */ - IMPORT_C void ServiceStateNotification( - TUsbServiceState& aState, - TRequestStatus& aStatus - ); - - /** - Cancel the outstanding service state notification request. - - - @since 7.0s - - @publishedPartner - @released - */ - IMPORT_C void ServiceStateNotificationCancel(); - - /** - Gets the current device state (eg. powered, configured...). - - - @since 7.0s - @param aState Set by the method to the current state of the USB device - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt GetDeviceState(TUsbDeviceState& aState); - - /** - Request to be notified of a change in state of the USB device. - - - @since 7.0s - @param aStateMask State mask of the states the client is interested in - @param aState State variable to be written to upon completion of the request - @param aStatus Status to complete when required state change occurs - - @publishedPartner - @released - */ - IMPORT_C void DeviceStateNotification( - TUint aStateMask, - TUsbDeviceState& aState, - TRequestStatus& aStatus - ); - - /** - Cancel the outstanding device state notification request. - - - @since 7.0s - - @publishedPartner - @released - */ - IMPORT_C void DeviceStateNotificationCancel(); - - /** - Try to start the device's USB service. It starts the current personality - only if the service is in the idle state. Calling this API while the server - is in any other states has no any effect on the service state. - - Note: Asynchonous version, outcome returned when the status is completed - - @param aPersonalityId a personality id - @param aStatus Status to complete once the start operation has completed. - It may be one of the following: - KErrNotSupported - KErrAccessDenied - KErrServerBusy - KErrAbort - KErrNone - @capability NetworkControl - @publishedPartner - @released - */ - IMPORT_C void TryStart(TInt aPersonalityId, TRequestStatus& aStatus); - - /** - Try to stop the device's USB service. It stops the service only if the serice - is in the started state. Calling this API while the server is in the other states - has no any effect on the service state. - - Note: Asynchonous version, outcome returned when the status is completed - - @param aStatus Status to complete once the stop operation has completed. - It may be one of the following: - KErrNotSupported - KErrAccessDenied - KErrServerBusy - KErrNone - @capability NetworkControl - @publishedPartner - @released - */ - IMPORT_C void TryStop(TRequestStatus& aStatus); - - /** - Cancels the interest of the pending operation of the device's USB service, - either starting or stopping. The pending request will run to the completion. - The caller of this function receives a status of KErrCancel. - - @param aMessageId a message id to identify the request to be cancelled - @publishedPartner - @released - */ - IMPORT_C TInt CancelInterest(TUsbReqType aMessageId); - - /** - Gets the textual description of the personality identified by the aPersonalityId. - Caller is repsonsible for freeing up memories allocated to - aLocalizedPersonalityDescriptor. - - @param aPersonalityId a personality id - @param aLocalizedPersonalityDescriptor a localize text string - @return KErrNone if successful, otherwise the error that occurred - @publishedPartner - @released - */ - IMPORT_C TInt GetDescription(TInt aPersonalityId, HBufC*& aLocalizedPersonalityDescriptor); - - /** - Gets the current personality id of the device's USb service - - @param aPersonalityId set to the current personality of USB device - @return KErrNone if successful, otherwise the error that occurred - @publishedPartner - @released - */ - IMPORT_C TInt GetCurrentPersonalityId(TInt& aPersonalityId); - - /** - Gets supported classes by the given personality identified by the aPersonalityId - - @param aPersonalityId a personality id - @param aClassUids an array of class uids - @return KErrNone if successful, otherwise the error that occurred - @publishedPartner - @released - */ - IMPORT_C TInt GetSupportedClasses(TInt aPersonalityId, RArray& aClassUids); - - /** - Queries the USB manager to determine if a given class is supported - - @param aPersonalityId a personality id - @param aClassUid a class uid - @param aSupported set upon return - @return KErrNone if successful, otherwise the error that occurred - @publishedPartner - @released - */ - IMPORT_C TInt ClassSupported(TInt aPersonalityId, TUid aClassUid, TBool& aSupported); - - /** - Gets all supported personality ids of the device's USB service. - - @param aPersonalityIds populated with all supported personality ids of the USB device - @return KErrNone if successful, otherwise the error that occurred - @publishedPartner - @released - */ - IMPORT_C TInt GetPersonalityIds(RArray& aPersonalityIds); - - /** - Marks the start of heap cell checking for the USB Manager. This function is only defined - in debug builds. - - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt __DbgMarkHeap(); - - /** - Checks that the number of allocated cells on the USB Manager's heap is correct. The USB - Manager will be panicked if it is not. This function is only defined in debug builds. - - @param aCount The expected number of heap cells allocated - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt __DbgCheckHeap(TInt aCount); - - /** - Marks the end of heap cell checking for the USB Manager. Checks that the number of heap - cells allocated since the last __DbgMarkHeap() is aCount; the most common value to pass - here is zero. This function is only defined in debug builds. - - @param aCount The expected number of heap cells allocated - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt __DbgMarkEnd(TInt aCount); - - /** - Simulates memory allocation failure in the USB Manager. This function is only defined in - debug builds. - - @param aCount The number of allocations after which memory allocation should fail - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt __DbgFailNext(TInt aCount); - - /** - Functions below this point are deprecated and should not be used. - */ - - /** - Get the current state of the device's USB service. This function is deprecated and has been - replaced by the GetServiceState function from version 7.0s onwards. - - - @since 7.0 - @param aState Set by the method to the current state of the USB service - - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @deprecated - */ - IMPORT_C TInt GetCurrentState(TUsbServiceState& aState); - - /** - Request to be notified of a change in state of the USB device. This function is deprecated - and has been replaced by the DeviceStateNotification function from version 7.0s onwards. - - - @since 7.0 - @param aStateMask State mask of the states the client is interested in - @param aState State variable to be written to upon completion of the request - @param aStatus Status to complete when required state change occurs - - @publishedPartner - @deprecated - */ - IMPORT_C void StateNotification( - TUint aStateMask, - TUsbDeviceState& aState, - TRequestStatus& aStatus - ); - - /** - Cancel the outstanding device state notification request. This function is deprecated and - has been replaced by the DeviceStateNotificationCancel function from version 7.0s onwards. - - - @since 7.0 - - @publishedPartner - @deprecated - */ - IMPORT_C void StateNotificationCancel(); - - /** - * Set or reset the mode in which current RUsb session operates. - * Recent implementation assumes that there is the one and only application - * which controls USBMAN, all other clients act as listeners to notification - * requests. Only application which was previously granted 'control' mode is - * allowed to reset it at later stage. Any calls from other applications will - * generate an error. - * - * @param aValue True to inform USBMAN that Application wants to 'control' - * USBMAN - * False otherwise - * - * @capability NetworkControl - * @return KErrNone if successful - * KErrAccessDenied otherwise - */ - IMPORT_C TInt SetCtlSessionMode(TBool aValue); - - /** - * Cable watcher wants to assert Bus_request. - * If ID-Pin is present this is an A-Device and this will result in an attempt - * to raise VBus. Second attempt to raise VBus causes KErrUsbOtgVbusAlreadyRaised - * error. - * If ID-Pin is absent this is a B-Device and this will result in an attempt to - * use SRP. Recently does nothing - * - * When BusRequest() returns an error, VBus remains low until the errors are cleared by - * BusDrop() or BusClearErr() calls - * - * @capability NetworkControl - * @return KErrNone if successful, otherwise an error code returned by OTGDI - */ - IMPORT_C TInt BusRequest(); - - /** - * Cable watcher wants to assert Bus_request after SRP. - * If ID-Pin is present this is an A-Device and this will result in an attempt - * to raise VBus - * - * @capability NetworkControl - * @return KErrNone if successful, otherwise an error code returned by OTGDI - */ - IMPORT_C TInt BusRespondSrp(); - - /** - * Cable watcher wants to clear the Bus Error after A_VBUS_ERR - * Only works if ID-Pin is present (this is an A-Device) and there - * has already been a bus erorr. - * This will not result in any attempt to raise or drop VBus - * - * @capability NetworkControl - * @return KErrNone if successful, otherwise an error code returned by OTGDI - */ - IMPORT_C TInt BusClearError(); - - /** - * Cable watcher wants to drop VBus. - * If ID-Pin is present this is an A-Device and this will result in stopping VBus - * power-up - * - * @capability NetworkControl - * @return KErrNone if successful, otherwise an error code returned by OTGDI - */ - IMPORT_C TInt BusDrop(); - - /** - * Register for Messages notifications - * The request only completes when the new message arrives. - * Calling this function the first time initializes Messages queue - * - * - * @param aMessage UI Message variable to be written to upon completion - * of the request - * @param aStatus Status to complete when required state change occurs - * KErrNone - if successful - * KErrInUse - if there is another outstanding nofitication request - * for the same session - * otherwise an error code returned by OTGDI or Host - */ - IMPORT_C void MessageNotification(TRequestStatus& aStatus, TInt& aMessage); - - /** - * Cancel the outstanding Messages notification request. - */ - IMPORT_C void MessageNotificationCancel(); - - /** - * Register for Host Device Event notifications. - * The request only completes when the host event occurs. - * Calling this function the first time initializes Host Events queue - * - * @param aStatus Status to complete when required event occurs - * - * KErrNone - if successful - * KErrInUse - if there is another outstanding nofitication - * request for the same session - * otherwise an error code returned by FDF - * @param aDeviceInformation device info to be written to upon completion - * of the request - */ - IMPORT_C void HostEventNotification(TRequestStatus& aStatus, - TDeviceEventInformation& aDeviceInformation); - /** - * Cancel the outstanding FDF Device Event notification request. - */ - IMPORT_C void HostEventNotificationCancel(); - - /** - * Enable Function Driver Loading. - * - * @capability NetworkControl - * @return KErrNone - if successful - * KErrNotSupported - if FDF is not included in current configuration - * otherwise an error code returned by FDF - */ - IMPORT_C TInt EnableFunctionDriverLoading(); - - /** - * Disable Function Driver Loading. - * - * @capability NetworkControl - */ - IMPORT_C void DisableFunctionDriverLoading(); - - /** - * Get Supported Languages from USB Device - * - * @param aDeviceId DeviceID of given device - * @param aLangIds an array of language IDs supported by given device. - * These language IDs are supplied by USB-IF and are - * different from standard Symbian TLanguage enumeration - * - * @return KErrNone - if successful - * otherwise an error code returned by FDF - */ - IMPORT_C TInt GetSupportedLanguages(TUint aDeviceId, RArray& aLangIds); - - /** - * Get Manufacturer Descriptor - * - * @param aDeviceId DeviceID of given device - * @param aLangId required language ID which is supplied by USB-IF and is - * different from standard Symbian TLanguage enumeration - * @param aString manufacturer descriptor value at output - * - * @return KErrNone - if successful - * otherwise an error code returned by FDF - */ - IMPORT_C TInt GetManufacturerStringDescriptor(TUint aDeviceId, TUint aLangId, TName& aString); - - /** - * Get Product Descriptor - * - * @param aDeviceId DeviceID of given device - * @param aLangId required language ID which is supplied by USB-IF and is - * different from standard Symbian TLanguage enumeration - * @param aString product descriptor value at output - * - * @return KErrNone - if successful - * otherwise an error code returned by FDF - */ - IMPORT_C TInt GetProductStringDescriptor(TUint aDeviceId, TUint aLangId, TName& aString); - - /** - * Retrieve Otg Descriptor for device which has given device Id. - * Currently TOtgDescriptor has following fields: - * - HNP supported - * - SRP supported - * An OTG device should support them both. - * - * @param aDeviceId DeviceID of given device - * @param aDescriptor OTG descriptor value at output - * - * @return KErrNone - if successful - * otherwise an error code returned by FDF - */ - IMPORT_C TInt GetOtgDescriptor(TUint aDeviceId, TOtgDescriptor& aDescriptor); - - /** - Simulates memory allocation in the USB Manager. This function is only defined in - debug builds. - - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt __DbgAlloc(); - - /** - Informs USB Manager that the client would like to initialte USB session. - On A-Device, it results in sending a notification to 'controller' application - On B-Device, it may trigger either SRP or HNP sequence depending on the state of VBus - - @return KErrNone if successful, otherwise the error that occurred - - @publishedPartner - @released - */ - IMPORT_C TInt RequestSession(); - - - /** - Gets the property of the personality identified by the aPersonalityId. - - @param aPersonalityId a personality id - @return the personality property - @publishedPartner - @released - */ - IMPORT_C TInt GetPersonalityProperty(TInt aPersonalityId, TUint32& aProperty); - - /** - Gets the detailed textual description of the personality identified by the aPersonalityId. - Caller is repsonsible for freeing up memories allocated to - aLocalizedPersonalityDescriptor. - - @param aPersonalityId a personality id - @param aLocalizedPersonalityDescriptor a localize text string - @return KErrNone if successful, otherwise the error that occurred - @publishedPartner - @released - */ - IMPORT_C TInt GetDetailedDescription(TInt aPersonalityId, HBufC*& aLocalizedPersonalityDescriptor); - -private: - /** - Used to register device state notifications. - */ - TPckg iDeviceStatePkg; - - /** - Used to register service state notifications. - */ - TPckg iServiceStatePkg; - - /** - Used to register OTG/Host message notifications. - */ - TPckg iMessagePkg; - - /** - Used to register Host state notifications. - */ - TPckg iHostPkg; - }; - -#endif //__USBMAN_H__