RUsb Class Reference

class RUsb : public RSessionBase

The RUsb class implements the Symbian OS USB Management API RUsb

Inherits from

Public Member Functions
RUsb()
~RUsb()
IMPORT_C TIntBusClearError()
IMPORT_C TIntBusDrop()
IMPORT_C TIntBusRequest()
IMPORT_C TIntBusRespondSrp()
IMPORT_C TIntCancelInterest(TUsbReqType)
IMPORT_C TIntClassSupported(TInt, TUid, TBool &)
IMPORT_C TIntConnect()
IMPORT_C voidDeviceStateNotification(TUint, TUsbDeviceState &, TRequestStatus &)
IMPORT_C voidDeviceStateNotificationCancel()
IMPORT_C voidDisableFunctionDriverLoading()
IMPORT_C TIntEnableFunctionDriverLoading()
IMPORT_C TIntGetCurrentPersonalityId(TInt &)
IMPORT_C TIntGetCurrentState(TUsbServiceState &)
IMPORT_C TIntGetDescription(TInt, HBufC *&)
IMPORT_C TIntGetDetailedDescription(TInt, HBufC *&)
IMPORT_C TIntGetDeviceState(TUsbDeviceState &)
IMPORT_C TIntGetManufacturerStringDescriptor(TUint, TUint, TName &)
IMPORT_C TIntGetOtgDescriptor(TUint, TOtgDescriptor &)
IMPORT_C TIntGetPersonalityIds(RArray< TInt > &)
IMPORT_C TIntGetPersonalityProperty(TInt, TUint32 &)
IMPORT_C TIntGetProductStringDescriptor(TUint, TUint, TName &)
IMPORT_C TIntGetServiceState(TUsbServiceState &)
IMPORT_C TIntGetSupportedClasses(TInt, RArray< TUid > &)
IMPORT_C TIntGetSupportedLanguages(TUint, RArray< TUint > &)
IMPORT_C voidHostEventNotification(TRequestStatus &, TDeviceEventInformation &)
IMPORT_C voidHostEventNotificationCancel()
IMPORT_C voidMessageNotification(TRequestStatus &, TInt &)
IMPORT_C voidMessageNotificationCancel()
IMPORT_C TIntRequestSession()
IMPORT_C voidServiceStateNotification(TUsbServiceState &, TRequestStatus &)
IMPORT_C voidServiceStateNotificationCancel()
IMPORT_C TIntSetCtlSessionMode(TBool)
IMPORT_C voidStart(TRequestStatus &)
IMPORT_C voidStartCancel()
IMPORT_C voidStateNotification(TUint, TUsbDeviceState &, TRequestStatus &)
IMPORT_C voidStateNotificationCancel()
IMPORT_C voidStop()
IMPORT_C voidStop(TRequestStatus &)
IMPORT_C voidStopCancel()
IMPORT_C voidTryStart(TInt, TRequestStatus &)
IMPORT_C voidTryStop(TRequestStatus &)
IMPORT_C TVersionVersion()
IMPORT_C TInt__DbgAlloc()
IMPORT_C TInt__DbgCheckHeap(TInt)
IMPORT_C TInt__DbgFailNext(TInt)
IMPORT_C TInt__DbgMarkEnd(TInt)
IMPORT_C TInt__DbgMarkHeap()
Inherited Functions
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::Close()
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RSessionBase::CreateSession(RServer2,const TVersion &)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Open(TInt,TOwnerType)
RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Send(TInt)const
RSessionBase::Send(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt)const
RSessionBase::SendReceive(TInt,TRequestStatus &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSessionBase::SetReturnedHandle(TInt)
RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
RSessionBase::ShareAuto()
RSessionBase::ShareProtected()
Public Member Enumerations
enumTUsbReqType { EStart, EStop, ETryStart, ETryStop }
Inherited Enumerations
RHandleBase:TAttributes
RSessionBase:TAttachMode
Private Attributes
TPckg< TUint32 >iDeviceStatePkg
TPckg< TDeviceEventInformation >iHostPkg
TPckg< TUint32 >iMessagePkg
TPckg< TUint32 >iServiceStatePkg
Inherited Attributes
RHandleBase::iHandle

Constructor & Destructor Documentation

RUsb()

IMPORT_CRUsb()

Constructor

Since
7.0

~RUsb()

IMPORT_C~RUsb()

Destructor

Since
7.0

Member Functions Documentation

BusClearError()

IMPORT_C TIntBusClearError()

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

BusDrop()

IMPORT_C TIntBusDrop()

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

BusRequest()

IMPORT_C TIntBusRequest()

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

BusRespondSrp()

IMPORT_C TIntBusRespondSrp()

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

CancelInterest(TUsbReqType)

IMPORT_C TIntCancelInterest(TUsbReqTypeaMessageId)

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.

Parameters

TUsbReqType aMessageIda message id to identify the request to be cancelled

ClassSupported(TInt, TUid, TBool &)

IMPORT_C TIntClassSupported(TIntaPersonalityId,
TUidaClassUid,
TBool &aSupported
)

Queries the USB manager to determine if a given class is supported

Parameters

TInt aPersonalityIda personality id
TUid aClassUida class uid
TBool & aSupportedset upon return

Connect()

IMPORT_C TIntConnect()

Connect the Handle to the Server Must be called before all other methods except Version()

Since
7.0

DeviceStateNotification(TUint, TUsbDeviceState &, TRequestStatus &)

IMPORT_C voidDeviceStateNotification(TUintaStateMask,
TUsbDeviceState &aState,
TRequestStatus &aStatus
)

Request to be notified of a change in state of the USB device.

Since
7.0s

Parameters

TUint aStateMaskState mask of the states the client is interested in
TUsbDeviceState & aStateState variable to be written to upon completion of the request
TRequestStatus & aStatusStatus to complete when required state change occurs

DeviceStateNotificationCancel()

IMPORT_C voidDeviceStateNotificationCancel()

Cancel the outstanding device state notification request.

Since
7.0s

DisableFunctionDriverLoading()

IMPORT_C voidDisableFunctionDriverLoading()

Disable Function Driver Loading.

capability
NetworkControl

EnableFunctionDriverLoading()

IMPORT_C TIntEnableFunctionDriverLoading()

Enable Function Driver Loading.

capability
NetworkControl

GetCurrentPersonalityId(TInt &)

IMPORT_C TIntGetCurrentPersonalityId(TInt &aPersonalityId)

Gets the current personality id of the device's USb service

Parameters

TInt & aPersonalityIdset to the current personality of USB device

GetCurrentState(TUsbServiceState &)

IMPORT_C TIntGetCurrentState(TUsbServiceState &aState)

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

Parameters

TUsbServiceState & aStateSet by the method to the current state of the USB service

GetDescription(TInt, HBufC *&)

IMPORT_C TIntGetDescription(TIntaPersonalityId,
HBufC *&aLocalizedPersonalityDescriptor
)

Gets the textual description of the personality identified by the aPersonalityId. Caller is repsonsible for freeing up memories allocated to aLocalizedPersonalityDescriptor.

Parameters

TInt aPersonalityIda personality id
HBufC *& aLocalizedPersonalityDescriptora localize text string

GetDetailedDescription(TInt, HBufC *&)

IMPORT_C TIntGetDetailedDescription(TIntaPersonalityId,
HBufC *&aLocalizedPersonalityDescriptor
)

Gets the detailed textual description of the personality identified by the aPersonalityId. Caller is repsonsible for freeing up memories allocated to aLocalizedPersonalityDescriptor.

Parameters

TInt aPersonalityIda personality id
HBufC *& aLocalizedPersonalityDescriptora localize text string

GetDeviceState(TUsbDeviceState &)

IMPORT_C TIntGetDeviceState(TUsbDeviceState &aState)

Gets the current device state (eg. powered, configured...).

Since
7.0s

Parameters

TUsbDeviceState & aStateSet by the method to the current state of the USB device

GetManufacturerStringDescriptor(TUint, TUint, TName &)

IMPORT_C TIntGetManufacturerStringDescriptor(TUintaDeviceId,
TUintaLangId,
TName &aString
)

Get Manufacturer Descriptor

Parameters

TUint aDeviceIdDeviceID of given device
TUint aLangIdrequired language ID which is supplied by USB-IF and is different from standard Symbian TLanguage enumeration
TName & aStringmanufacturer descriptor value at output

GetOtgDescriptor(TUint, TOtgDescriptor &)

IMPORT_C TIntGetOtgDescriptor(TUintaDeviceId,
TOtgDescriptor &aDescriptor
)
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.

Parameters

TUint aDeviceIdDeviceID of given device
TOtgDescriptor & aDescriptorOTG descriptor value at output

GetPersonalityIds(RArray< TInt > &)

IMPORT_C TIntGetPersonalityIds(RArray< TInt > &aPersonalityIds)

Gets all supported personality ids of the device's USB service.

Parameters

RArray< TInt > & aPersonalityIdspopulated with all supported personality ids of the USB device

GetPersonalityProperty(TInt, TUint32 &)

IMPORT_C TIntGetPersonalityProperty(TIntaPersonalityId,
TUint32 &aProperty
)

Gets the property of the personality identified by the aPersonalityId.

Parameters

TInt aPersonalityIda personality id
TUint32 & aProperty

GetProductStringDescriptor(TUint, TUint, TName &)

IMPORT_C TIntGetProductStringDescriptor(TUintaDeviceId,
TUintaLangId,
TName &aString
)

Get Product Descriptor

Parameters

TUint aDeviceIdDeviceID of given device
TUint aLangIdrequired language ID which is supplied by USB-IF and is different from standard Symbian TLanguage enumeration
TName & aStringproduct descriptor value at output

GetServiceState(TUsbServiceState &)

IMPORT_C TIntGetServiceState(TUsbServiceState &aState)

Get the current state of the device's USB service.

Since
7.0s

Parameters

TUsbServiceState & aStateSet by the method to the current state of the USB service

GetSupportedClasses(TInt, RArray< TUid > &)

IMPORT_C TIntGetSupportedClasses(TIntaPersonalityId,
RArray< TUid > &aClassUids
)

Gets supported classes by the given personality identified by the aPersonalityId

Parameters

TInt aPersonalityIda personality id
RArray< TUid > & aClassUidsan array of class uids

GetSupportedLanguages(TUint, RArray< TUint > &)

IMPORT_C TIntGetSupportedLanguages(TUintaDeviceId,
RArray< TUint > &aLangIds
)

Get Supported Languages from USB Device

Parameters

TUint aDeviceIdDeviceID of given device
RArray< TUint > & aLangIdsan array of language IDs supported by given device. These language IDs are supplied by USB-IF and are different from standard Symbian TLanguage enumeration

HostEventNotification(TRequestStatus &, TDeviceEventInformation &)

IMPORT_C voidHostEventNotification(TRequestStatus &aStatus,
TDeviceEventInformation &aDeviceInformation
)

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

KErrNone - if successful KErrInUse - if there is another outstanding nofitication request for the same session otherwise an error code returned by FDF

Parameters

TRequestStatus & aStatusStatus to complete when required event occurs
TDeviceEventInformation & aDeviceInformationdevice info to be written to upon completion of the request

HostEventNotificationCancel()

IMPORT_C voidHostEventNotificationCancel()

Cancel the outstanding FDF Device Event notification request.

MessageNotification(TRequestStatus &, TInt &)

IMPORT_C voidMessageNotification(TRequestStatus &aStatus,
TInt &aMessage
)

Register for Messages notifications The request only completes when the new message arrives. Calling this function the first time initializes Messages queue

Parameters

TRequestStatus & aStatusStatus 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
TInt & aMessageUI Message variable to be written to upon completion of the request

MessageNotificationCancel()

IMPORT_C voidMessageNotificationCancel()

Cancel the outstanding Messages notification request.

RequestSession()

IMPORT_C TIntRequestSession()

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

ServiceStateNotification(TUsbServiceState &, TRequestStatus &)

IMPORT_C voidServiceStateNotification(TUsbServiceState &aState,
TRequestStatus &aStatus
)

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

Parameters

TUsbServiceState & aStateState variable to be written to upon completion of the request
TRequestStatus & aStatusStatus to complete when required state change occurs

ServiceStateNotificationCancel()

IMPORT_C voidServiceStateNotificationCancel()

Cancel the outstanding service state notification request.

Since
7.0s

SetCtlSessionMode(TBool)

IMPORT_C TIntSetCtlSessionMode(TBoolaValue)

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.

capability
NetworkControl

Parameters

TBool aValueTrue to inform USBMAN that Application wants to 'control' USBMAN False otherwise

Start(TRequestStatus &)

IMPORT_C voidStart(TRequestStatus &aStatus)

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
capability
NetworkControl

Parameters

TRequestStatus & aStatusStatus to complete once the start operation has completed

StartCancel()

IMPORT_C voidStartCancel()

Cancels the pending start operation of the device's USB service.

Since
7.0
capability
NetworkControl

StateNotification(TUint, TUsbDeviceState &, TRequestStatus &)

IMPORT_C voidStateNotification(TUintaStateMask,
TUsbDeviceState &aState,
TRequestStatus &aStatus
)

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

Parameters

TUint aStateMaskState mask of the states the client is interested in
TUsbDeviceState & aStateState variable to be written to upon completion of the request
TRequestStatus & aStatusStatus to complete when required state change occurs

StateNotificationCancel()

IMPORT_C voidStateNotificationCancel()

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

Stop()

IMPORT_C voidStop()

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

Stop(TRequestStatus &)

IMPORT_C voidStop(TRequestStatus &aStatus)

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
capability
NetworkControl

Parameters

TRequestStatus & aStatusStatus to complete once the stop operation has completed

StopCancel()

IMPORT_C voidStopCancel()

Cancels the pending stop operation of the device's USB service.

Since
7.0s
capability
NetworkControl

TryStart(TInt, TRequestStatus &)

IMPORT_C voidTryStart(TIntaPersonalityId,
TRequestStatus &aStatus
)

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

capability
NetworkControl

Parameters

TInt aPersonalityIda personality id
TRequestStatus & aStatusStatus to complete once the start operation has completed. It may be one of the following: KErrNotSupported KErrAccessDenied KErrServerBusy KErrAbort KErrNone

TryStop(TRequestStatus &)

IMPORT_C voidTryStop(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

capability
NetworkControl

Parameters

TRequestStatus & aStatusStatus to complete once the stop operation has completed. It may be one of the following: KErrNotSupported KErrAccessDenied KErrServerBusy KErrNone

Version()

IMPORT_C TVersionVersion()const

Extract the version of the server providing the RUsb API

Since
7.0

__DbgAlloc()

IMPORT_C TInt__DbgAlloc()

Simulates memory allocation in the USB Manager. This function is only defined in debug builds.

__DbgCheckHeap(TInt)

IMPORT_C TInt__DbgCheckHeap(TIntaCount)

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.

Parameters

TInt aCountThe expected number of heap cells allocated

__DbgFailNext(TInt)

IMPORT_C TInt__DbgFailNext(TIntaCount)

Simulates memory allocation failure in the USB Manager. This function is only defined in debug builds.

Parameters

TInt aCountThe number of allocations after which memory allocation should fail

__DbgMarkEnd(TInt)

IMPORT_C TInt__DbgMarkEnd(TIntaCount)

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.

Parameters

TInt aCountThe expected number of heap cells allocated

__DbgMarkHeap()

IMPORT_C TInt__DbgMarkHeap()

Marks the start of heap cell checking for the USB Manager. This function is only defined in debug builds.

Member Enumerations Documentation

Enum TUsbReqType

Enumerators

EStart
EStop
ETryStart
ETryStop

Member Data Documentation

TPckg< TUint32 > iDeviceStatePkg

TPckg< TUint32 >iDeviceStatePkg[private]

Used to register device state notifications.

TPckg< TDeviceEventInformation > iHostPkg

TPckg< TDeviceEventInformation >iHostPkg[private]

Used to register Host state notifications.

TPckg< TUint32 > iMessagePkg

TPckg< TUint32 >iMessagePkg[private]

Used to register OTG/Host message notifications.

TPckg< TUint32 > iServiceStatePkg

TPckg< TUint32 >iServiceStatePkg[private]

Used to register service state notifications.