RBTPhysicalLinkAdapter Class Reference

#include <bt_sock.h>

Link against: bluetooth.lib

class RBTPhysicalLinkAdapter

Detailed Description

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_CRBTPhysicalLinkAdapter()

Constructor

Member Function Documentation

ActivateActiveRequester ( )

IMPORT_C TIntActivateActiveRequester()

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

Returns: Error code

ActivateParkRequester ( )

IMPORT_C TIntActivateParkRequester()

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

Returns: Error code

ActivateSniffRequester ( )

IMPORT_C TIntActivateSniffRequester()

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

Returns: Error code

AllowLowPowerModes ( TUint32 )

IMPORT_C TIntAllowLowPowerModes(TUint32aLowPowerModes)

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
ParameterDescription
aLowPowerModesA mask to specify which power modes are to be prevented. (Combine EHoldMode, ESniffMode, EParkMode or use EAnyLowPowerMode)

Returns: Error code

AllowRoleSwitch ( )

IMPORT_C TIntAllowRoleSwitch()

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

Returns: Error code

Authenticate ( )

IMPORT_C TIntAuthenticate()

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

Returns: Error code. KErrAlreadyExists if the link is already authenticated

CancelLowPowerModeRequester ( )

IMPORT_C TIntCancelLowPowerModeRequester()

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

Returns: Error code

CancelNextBasebandChangeEventNotifier ( )

IMPORT_C voidCancelNextBasebandChangeEventNotifier()

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 voidClose()

Close the physical link adapter.

IsOpen ( )

IMPORT_C TBoolIsOpen()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 voidNotifyNextBasebandChangeEvent(TBTBasebandEvent &aEventNotification,
TRequestStatus &aStatus,
TUint32aEventMask = 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

See also: TBTPhysicalLinkStateNotifier TBTPhysicalLinkStateNotifierCombinations

ParameterDescription
aEventNotificationReturn parameter
aStatusStatus parameter for asynchronous request
aEventMaskBitmask for those events for which notification is being requested Use TBTPhysicalLinkStateNotifier (and TBTPhysicalLinkStateNotifierCombinations)

Open ( RSocketServ &, RSocket & )

IMPORT_C TIntOpen(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
ParameterDescription
aSocketServAn existing ESock session
aSocketAn open connected socket (ESock subsession) on that existing ESock session

Returns: Error code

Open ( RSocketServ &, const TBTDevAddr & )

IMPORT_C TIntOpen(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
ParameterDescription
aSocketServAn existing ESock session
aDevAddrThe Bluetooth address of a remote device with which there is an existing connection

Returns: Error code

PhysicalLinkState ( TUint32 & )

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

See also: TBTPhysicalLinkStateNotifier

ParameterDescription
aStateUsed to return the physical link state - as a combination of bit values defined in TBTPhysicalLinkStateNotifier.

Returns: Error code

PreventLowPowerModes ( TUint32 )

IMPORT_C TIntPreventLowPowerModes(TUint32aLowPowerModes)

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
ParameterDescription
aLowPowerModesA mask to specify which power modes are to be prevented. (Combine EHoldMode, ESniffMode, EParkMode or use EAnyLowPowerMode)

Returns: Error code

PreventRoleSwitch ( )

IMPORT_C TIntPreventRoleSwitch()

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

Returns: Error code

RequestChangeSupportedPacketTypes ( TUint16 )

IMPORT_C TIntRequestChangeSupportedPacketTypes(TUint16aPacketTypes)

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

See also: TBTPacketType TBTPacketTypeCombinations

ParameterDescription
aPacketTypesBitmask for packet types to be supported (Combine elements of TBTPacketType (or use TBTPacketTypeCombinations))

Returns: Error code

RequestMasterRole ( )

IMPORT_C TIntRequestMasterRole()

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.

Returns: Error code

RequestSlaveRole ( )

IMPORT_C TIntRequestSlaveRole()

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

Returns: Error code