diff -r e9b96e674847 -r 5b2a402e96ac tsrc/testtools/usbman_stub/usbman/client/public/usbman.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tsrc/testtools/usbman_stub/usbman/client/public/usbman.h Thu Aug 19 10:54:11 2010 +0300 @@ -0,0 +1,705 @@ +/* +* 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__