RBTPhysicalLinkAdapter Class Reference

class RBTPhysicalLinkAdapter

Class to enable modification of a physical link:

Modifications may be requested or prevented (blocked). Whilst a modification is being prevented, any request to perform that modification by this or any other RBTPhysicalLinkAdapter client will be ignored. If a low power mode is being used on the physical link, a call to prevent that low power mode will, if possible, cause the physical link to exit that low power mode. An arbitration between all RBTPhysicalLinkAdapter clients will then occur to decide whether the physical link should remain active or enter another low power mode. (If all low power modes are prevented then that arbitration will result in the physical link remaining active.)

Methods to prevent modifications begin 'Prevent...'

Methods to cancel the prevention of modification begin 'Allow...'

Requests for low power mode modifications, and notification of modifications take the form of continuously repeated requests which can be switched on or switched off.

Only one low power mode requester may active on a single RBTPhysicalLinkAdapter client at a time. If several RBTPhysicalLinkAdapter clients have differing low power mode requests active at a given moment then the priority will be: Hold Sniff Park

Methods to perform these requests start 'Activate...'

Methods to cancel these requests start 'Cancel...'

Constructor & Destructor Documentation

RBTPhysicalLinkAdapter()

IMPORT_C RBTPhysicalLinkAdapter ( )

Constructor

Member Functions Documentation

ActivateActiveRequester()

IMPORT_C TInt ActivateActiveRequester ( )

Start a facility that will continually attempt to put the physical link into Active Mode.

Puts the physical link into Active mode, even if a Low Power Mode (Sniff or Park) has been explicitly requested by another client of the physical link. Calling CancelLowPowerModeRequests() will cancel the explicit request for Active mode.
Pre-condition
One of the Open functions has been called

ActivateParkRequester()

IMPORT_C TInt ActivateParkRequester ( )

Start a facility that will continually attempt to put the physical link into Park Mode.

Attempt to put the physical link into Park mode. If for any reason this is not possible (e.g another user of a RBTPhysicalLinkAdapter object has called PreventLowPowerModes on Park) or the physical link comes out of Park mode, this attempt will be repeated whenever a relevant event occurs or command is made. These attempts will cease, if a call to either ActivateSniffRequester, ActivateActiveRequester or CancelLowPowerModeRequester is made.
Pre-condition
One of the Open functions has been called

ActivateSniffRequester()

IMPORT_C TInt ActivateSniffRequester ( )

Start a facility that will continually attempt to put the physical link into Sniff Mode.

Attempt to put the physical link into Sniff mode. If for any reason this is not possible (e.g another user of a RBTPhysicalLinkAdapter object has called PreventLowPowerModes on Sniff) or the physical link comes out of Sniff mode, this attempt will be repeated whenever a relevant event occurs or command is made. These attempts will cease if a call to either ActivateParkRequester, ActivateActiveRequester or CancelLowPowerModeRequester is made.
Pre-condition
One of the Open functions has been called

AllowLowPowerModes(TUint32)

IMPORT_C TInt AllowLowPowerModes ( TUint32 aLowPowerModes )

Ensures this object does not block the use of a specified set of low power modes

Switches off 'PreventLowPowerModes' for the low power modes specified by the parameter 'aLowPowerModes'. If another RBTPhysicalLinkAdapter object requests, or has requested one of those low power modes, that request will now NOT be blocked by this RBTPhysicalLinkAdapter object. The default is to allow all low power modes. NB. Warning this may reactivate a low power mode requester. For example: ActivateSniffRequester() ; //sniff requester active PreventLowPowersModes(ESniffMode); //sniff requester dormant .... AllowLowPowersModes(ESniffMode); //sniff requseter active

Pre-condition
One of the Open functions has been called

Parameters

TUint32 aLowPowerModes A mask to specify which power modes are to be prevented. (Combine EHoldMode, ESniffMode, EParkMode or use EAnyLowPowerMode)

AllowRoleSwitch()

IMPORT_C TInt AllowRoleSwitch ( )

Ensures this object does not block a role switch.

Switches off 'PreventRoleSwitch'. If another RBTPhysicalLinkAdapter object requests, or has requested a Master/Slave switch, that request will now not be blocked by this RBTPhysicalLinkAdapter object The default is to allow a Master/Slave switch.
Pre-condition
One of the Open functions has been called

Authenticate()

IMPORT_C TInt Authenticate ( )

Attempts to authenticate the existing physical link

If the the physical link has already been authenticated it will return an error, otherwise an Authentication Request will be made to the remote device.

This is a synchronous call and will return immediately the request has been issued. If required, NotifyNextBasebandChangeEvent() should be issued before this to wait for the completion of this authenticaton (for both authentication success and failure)

Pre-condition
One of the Open functions has been called

CancelLowPowerModeRequester()

IMPORT_C TInt CancelLowPowerModeRequester ( )

Cancel a facility that is continually requesting a low power mode

If ActivateSniffRequester, ActivateParkRequester or ActivateActiveRequester has been called by the user of this RBTPhysicalLinkAdapter object, repeated attempts will be made to put/return the physical link to that mode whenever a relevant event occurs or command is made. CancelLowPowerModeRequester stops these requests. However if another user of a RBTPhysicalLinkAdapter object has called ActivateSniffRequester, ActivateParkRequester or ActivateActiveRequester, those requests will still be active, and so the physical link will remain controlled by these requests.

To try to force the physical link into active mode, a call to either PreventLowPowerModes(EAnyLowPowerMode) or ActivateActiveRequester() should be made.

Pre-condition
One of the Open functions has been called

CancelNextBasebandChangeEventNotifier()

IMPORT_C void CancelNextBasebandChangeEventNotifier ( )

Cancel a currently requested notification

Switch off the currently active baseband change event notifier.
Pre-condition
One of the Open functions has been called

Close()

IMPORT_C void Close ( )

Close the physical link adapter.

IsOpen()

IMPORT_C TBool IsOpen ( ) const

Check whether the physical link adapter is open

This method is not required to be called before the other methods. KErrNotReady will be returned by other methods, if RBTPhysicalLinkAdapter is not open yet.

NotifyNextBasebandChangeEvent(TBTBasebandEvent &, TRequestStatus &, TUint32)

IMPORT_C void NotifyNextBasebandChangeEvent ( TBTBasebandEvent & aEventNotification,
TRequestStatus & aStatus,
TUint32 aEventMask = ENotifyAnyPhysicalLinkState
)

Request a notification

Request notification the next time one of a user specified selection (see parameter 3) of baseband events occurs.
Pre-condition
One of the Open functions has been called
TBTPhysicalLinkStateNotifier TBTPhysicalLinkStateNotifierCombinations

Parameters

TBTBasebandEvent & aEventNotification Return parameter
TRequestStatus & aStatus Status parameter for asynchronous request
TUint32 aEventMask = ENotifyAnyPhysicalLinkState Bitmask for those events for which notification is being requested Use TBTPhysicalLinkStateNotifier (and TBTPhysicalLinkStateNotifierCombinations)

Open(RSocketServ &, RSocket &)

IMPORT_C TInt Open ( RSocketServ & aSocketServ,
RSocket & aSocket
)
Open a physical link adapter on an existing physical link defined by 'aSocket'.
Pre-condition
There exists a Bluetooth connection
capability
LocalServices

Parameters

RSocketServ & aSocketServ An existing ESock session
RSocket & aSocket An open connected socket (ESock subsession) on that existing ESock session

Open(RSocketServ &, const TBTDevAddr &)

IMPORT_C TInt Open ( RSocketServ & aSocketServ,
const TBTDevAddr & aDevAddr
)
Open a physical link adapter on an existing physical link defined by 'aDevAddr'.
Pre-condition
There exists a Bluetooth connection
capability
LocalServices

Parameters

RSocketServ & aSocketServ An existing ESock session
const TBTDevAddr & aDevAddr The Bluetooth address of a remote device with which there is an existing connection

PhysicalLinkState(TUint32 &)

IMPORT_C TInt PhysicalLinkState ( TUint32 & aState )
Get the state of the physical link.
Pre-condition
One of the Open functions has been called
TBTPhysicalLinkStateNotifier

Parameters

TUint32 & aState Used to return the physical link state - as a combination of bit values defined in TBTPhysicalLinkStateNotifier.

PreventLowPowerModes(TUint32)

IMPORT_C TInt PreventLowPowerModes ( TUint32 aLowPowerModes )

Blocks the use of a specified set of low power modes

Stops the physical link using any one of the set of low power modes specified by the bit mask 'aLowPowerModes'. To undo this blocking mechanism for a given set of low power modes, 'AllowLowPowerModes' needs to be called with appropriate values in its 'aLowPowerModes' parameter.

NB THIS METHOD CAN BE USED TO FORCE THE PHYSICAL LINK INTO ACTIVE MODE. To do this set the parameter to EAnyLowPowerMode. The requests for low power modes by any RBTPhysicalLinkAdapter objects will now be blocked by this object.

NB Some remote devices will automatically disconnect from a device whose Link Policy settings prevent low power modes.

Pre-condition
One of the Open functions has been called

Parameters

TUint32 aLowPowerModes A mask to specify which power modes are to be prevented. (Combine EHoldMode, ESniffMode, EParkMode or use EAnyLowPowerMode)

PreventRoleSwitch()

IMPORT_C TInt PreventRoleSwitch ( )

Blocks a role switch

Stops a Master/Slave switch occurring until such time as 'AllowRoleSwitch' is called.
Pre-condition
One of the Open functions has been called

RequestChangeSupportedPacketTypes(TUint16)

IMPORT_C TInt RequestChangeSupportedPacketTypes ( TUint16 aPacketTypes )

Update the set of baseband packet types that are allowed locally

Attempts to control which Bluetooth baseband ACL packet types (i.e. DM1, DH1, DM3 etc) are allowed by our host controller on the physical link.
Pre-condition
One of the Open functions has been called
TBTPacketType TBTPacketTypeCombinations

Parameters

TUint16 aPacketTypes Bitmask for packet types to be supported (Combine elements of TBTPacketType (or use TBTPacketTypeCombinations))

RequestMasterRole()

IMPORT_C TInt RequestMasterRole ( )

Attempt to be the Bluetooth Master of a Piconet.

If the local device is currently the slave, a role switch maybe performed if no other user of a RBTPhysicalLinkAdapter object has called PreventRoleSwitch and the remote device allows the role switch.

RequestSlaveRole()

IMPORT_C TInt RequestSlaveRole ( )

Attempt to be a Bluetooth Slave of a Piconet.

If the local device is currently the master, a role switch maybe performed if no other user of a RBTPhysicalLinkAdapter object has called PreventRoleSwitch and the remote device allows the role switch.
Pre-condition
One of the Open functions has been called

Member Data Documentation

RBTBaseband iBTBaseband

RBTBaseband iBTBaseband [private]

TUint32 iPadding1

TUint32 iPadding1 [private]

TUint32 iPadding2

TUint32 iPadding2 [private]