Class RBTPhysicalLinkAdapter

class RBTPhysicalLinkAdapter;

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...'

Members

Defined in RBTPhysicalLinkAdapter:

• ActivateActiveRequester()Start a facility that will continually attempt to put the physical link into Act...
• ActivateParkRequester()Start a facility that will continually attempt to put the physical link into Par...
• ActivateSniffRequester()Start a facility that will continually attempt to put the physical link into Sni...
• AllowLowPowerModes(TUint32)Ensures this object does not block the use of a specified set of low power modes
• AllowRoleSwitch()Ensures this object does not block a role switch.
• Authenticate()Attempts to authenticate the existing physical link
• CancelLowPowerModeRequester()Cancel a facility that is continually requesting a low power mode
• CancelNextBasebandChangeEventNotifier()Cancel a currently requested notification
• Close()Close the physical link adapter.
• IsOpen()constCheck whether the physical link adapter is open
• NotifyNextBasebandChangeEvent(TBTBasebandEvent &,TRequestStatus &,TUint32)Request a notification
• Open(RSocketServ &,RSocket &)Open a physical link adapter on an existing physical link defined by 'aSocket'.
• Open(RSocketServ &,const TBTDevAddr &)Open a physical link adapter on an existing physical link defined by 'aDevAddr'....
• PhysicalLinkState(TUint32 &)Get the state of the physical link.
• PreventLowPowerModes(TUint32)Blocks the use of a specified set of low power modes
• PreventRoleSwitch()Blocks a role switch
• RBTPhysicalLinkAdapter()Constructor
• RequestChangeSupportedPacketTypes(TUint16)Update the set of baseband packet types that are allowed locally
• RequestMasterRole()Attempt to be the Bluetooth Master of a Piconet.
• RequestSlaveRole()Attempt to be a Bluetooth Slave of a Piconet.

IMPORT_C RBTPhysicalLinkAdapter();

Description

Constructor

IMPORT_C TInt Open(RSocketServ &aSocketServ, RSocket &aSocket);

Pre-Condition

There exists a Bluetooth connection

Description

Open a physical link adapter on an existing physical link defined by 'aSocket'.

Parameters

Return value

IMPORT_C TInt Open(RSocketServ &aSocketServ, const TBTDevAddr &aDevAddr);

Pre-Condition

There exists a Bluetooth connection

Description

Open a physical link adapter on an existing physical link defined by 'aDevAddr'.

Parameters

Return value

IMPORT_C TBool IsOpen() const;

Description

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.

Return value

IMPORT_C void Close();

Description

Close the physical link adapter.

IMPORT_C TInt PhysicalLinkState(TUint32 &aState);

Pre-Condition

One of the Open functions has been called

Description

Get the state of the physical link.

Parameters

Return value

See also:

• TBTPhysicalLinkStateNotifier...

IMPORT_C TInt PreventRoleSwitch();

Pre-Condition

One of the Open functions has been called

Description

Blocks a role switch

Stops a Master/Slave switch occurring until such time as 'AllowRoleSwitch' is called.

Return value

IMPORT_C TInt AllowRoleSwitch();

Pre-Condition

One of the Open functions has been called

Description

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.

Return value

IMPORT_C TInt RequestMasterRole();

Description

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.

Return value

IMPORT_C TInt RequestSlaveRole();

Pre-Condition

One of the Open functions has been called

Description

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.

Return value

IMPORT_C TInt PreventLowPowerModes(TUint32 aLowPowerModes);

Pre-Condition

One of the Open functions has been called

Description

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.

Parameters

Return value

IMPORT_C TInt AllowLowPowerModes(TUint32 aLowPowerModes);

Pre-Condition

One of the Open functions has been called

Description

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: RBTPhysicalLinkAdapter::ActivateSniffRequester(); //sniff requester active PreventLowPowersModes(ESniffMode); //sniff requester dormant .... AllowLowPowersModes(ESniffMode); //sniff requseter active

Parameters

Return value

IMPORT_C TInt ActivateSniffRequester();

Pre-Condition

One of the Open functions has been called

Description

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.

Return value

IMPORT_C TInt ActivateParkRequester();

Pre-Condition

One of the Open functions has been called

Description

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.

Return value

IMPORT_C TInt ActivateActiveRequester();

Pre-Condition

One of the Open functions has been called

Description

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.

Return value

IMPORT_C TInt CancelLowPowerModeRequester();

Pre-Condition

One of the Open functions has been called

Description

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 RBTPhysicalLinkAdapter::ActivateActiveRequester() should be made.

Return value

IMPORT_C TInt RequestChangeSupportedPacketTypes(TUint16 aPacketTypes);

Pre-Condition

One of the Open functions has been called

Description

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.

Parameters

Return value

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

Pre-Condition

One of the Open functions has been called

Description

Request a notification

Request notification the next time one of a user specified selection (see parameter 3) of baseband events occurs.

Parameters

See also:

• TBTPhysicalLinkStateNotifier...

IMPORT_C void CancelNextBasebandChangeEventNotifier();

Pre-Condition

One of the Open functions has been called

Description

Cancel a currently requested notification

Switch off the currently active baseband change event notifier.

IMPORT_C TInt Authenticate();

Pre-Condition

One of the Open functions has been called

Description

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, RBTPhysicalLinkAdapter::NotifyNextBasebandChangeEvent(TBTBasebandEvent &,TRequestStatus &,TUint32) should be issued before this to wait for the completion of this authenticaton (for both authentication success and failure)

Return value