1 // Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // This is the API that the bluetooth stack expects from the HCI layer.

    15 // It comprises an event notification interface and a command sending interface.

    16 // Implementations of the HCI must derive from CHCIBase.

    17 // 

    18 //

    19 

    20 

    21 

    22 /**

    23  @file

    24  @publishedPartner

    25  @released

    26 */

    27 

    28 #ifndef BT_HCIBASE_H_

    29 #define BT_HCIBASE_H_

    30 

    31 #include <bttypes.h>

    32 #include <hcierrors.h>

    33 #include <hcitypes.h>

    34 #include <e32base.h>

    35 

    36 #include <bluetooth/hci/hciopcodes.h>

    37 #include <bluetooth/hci/aclpacketconsts.h>

    38 #include <bluetooth/hci/hciconsts.h>

    39 #include <bluetooth/hci/basebandpacketconsts.h>

    40 

    41 class CHCICommandFrame;

    42 class CHCIACLDataFrame;

    43 class CHCISCODataFrame;

    44 class CHCIBase;

    45 class MHCIEventObserver;

    46 class CESockIniData;

    47 

    48 /** Factory for creating CHCIBase derived class.

    49 

    50 To provide a new HCI implementation, re-implement this

    51 class in a DLL, which has a factory fucntion at oridnal 1

    52 which returns a TAny* to the instance of this factory.

    53 NewHCIL() will then be called on the factory to actually

    54 create the CHCIBase derived object.

    55 

    56 @released

    57 @publishedPartner

    58 */	

    59 NONSHARABLE_CLASS(CHCIFactory) : public CBase

    60     {

    61 public: 

    62 	CHCIFactory();

    63     virtual TVersion Version() const;

    64     virtual CHCIBase* NewHCIL(MHCIEventObserver* aParent, CESockIniData* aIni=0);

    65 	virtual CHCICommandFrame* NewHCICommandFrameL(THCIOpcode aOpcode);

    66 	virtual CHCIACLDataFrame* NewHCIACLDataFrameL(TUint16 aSize);

    67 	virtual CHCISCODataFrame* NewHCISCODataFrameL(TUint8 aSize);

    68 	};

    69 

    70 

    71 /** Abstract HCI Interface class.

    72  

    73 The Symbian Bluetooth stack uses this abstract class as the 

    74 polymorphic base through which it obtains host controller

    75 access. The actual implementation is dependent on the DLL

    76 loaded at run-time, as specified in the bt.bt.esk file.

    77 The concrete class derived from this should be returned

    78 by the CHCIFactory class, located through ordinal 1 in the

    79 polymorphic DLL.

    80 

    81 @publishedPartner

    82 @released

    83 @see 

    84 CHCI for detailed description of the functions.

    85 MHCIEventObserver for the callback interface for events received over HCI.

    86 */ 

    87 NONSHARABLE_CLASS(CHCIBase) : public CBase

    88 	{

    89 public:

    90 

    91 	/** Writes command frame.

    92 

    93 	 @param aFrame command frame to write

    94 	 @return KErrBcspWriteCommandDataFailed on failure, KErrNone otherwise

    95 	 @released

    96 	 @publishedPartner

    97 	 */

    98 	virtual TInt WriteCommand(const CHCICommandFrame& aFrame)=0;

    99 

   100 	// HCI General exports

   101 	/** Sets option.

   102 

   103 	 @param aName option to set

   104 	 @param aData option value

   105 	 @return System wide error code

   106 	 @released

   107 	 @publishedPartner

   108 	 */

   109     virtual TInt SetOption(TUint aName,const TDesC8& aData)=0;

   110 

   111     /** Gets option.

   112 

   113 	 @param aName option to set

   114 	 @param aData desriptor to be filled with option data

   115 	 @return System wide error code

   116      @released

   117      @publishedPartner

   118      */

   119     virtual TInt GetOption(TUint aName,TDes8& aData)=0;

   120 	

   121 	// HCI Data Calls

   122     /** Formats ACL Data.

   123 

   124 	 @param aFrame Reference to CHCIACLDataFrame which will be formatted with the data supplied in the other params

   125 	 @param aConnH Connection handle for this frame

   126 	 @param aFlags Flags to be set for this frame

   127 	 @param aData Data for this frame

   128      @released

   129      @publishedPartner

   130      */

   131     virtual void FormatACLData(CHCIACLDataFrame& aFrame, THCIConnHandle aConnH,TUint8 aFlags,const TDesC8& aData)=0;

   132     

   133 	/** Formats SCO Data.

   134 

   135 	 @param aFrame Reference to CHCISCODataFrame which will be formatted with the data supplied in the other params

   136 	 @param aConnH Connection handle for this frame

   137 	 @param aData Data for this frame

   138      @released

   139      @publishedPartner

   140      */

   141     virtual void FormatSCOData(CHCISCODataFrame& aFrame, THCIConnHandle aConnH, const TDesC8& aData)=0;

   142 

   143     /** Writes ACL Data.

   144 

   145 	This forwards a write from link layer to host controller.  The descriptor in the frame is owned by the link layer.

   146 

   147 	 @param aFrame the formatted ACL payload from the linkmanager

   148 	 @return System wide error code

   149      @released

   150      @publishedPartner

   151      */

   152 	virtual TInt WriteACLData(const CHCIACLDataFrame& aFrame)=0;

   153 

   154 	/** Writes SCO Data.

   155 

   156 	This forwards a write from link layer to host controller.  The descriptor in the frame is owned by the link layer.

   157 	 

   158 	 @param aFrame the formatted SCO payload from the linkmanager

   159 	 @return System wide error code

   160 	 @released

   161 	 @publishedPartner

   162 	 */

   163     virtual TInt WriteSCOData(const CHCISCODataFrame& aFrame)=0;

   164 

   165 	// HCI Frame information commands

   166     /** Gets frame connection handle

   167 

   168 	 @param aFrame the frame to return the connection handle of

   169 	 @return the connection handle from aFrame

   170      @released

   171      @publishedPartner

   172      */

   173 	virtual THCIConnHandle FrameConnectionHandle(const CHCIACLDataFrame& aFrame) const =0;

   174 

   175 	/** Gets frame opcode.

   176 

   177 	 @param aFrame the frame to return the opcode of

   178 	 @return the opcode of aFrame

   179 	 @released

   180 	 @publishedPartner

   181 	 */

   182 	virtual THCIOpcode FrameOpcode(const CHCICommandFrame& aFrame) const =0;

   183 	

   184 	// HCI Commands

   185 	/**	Commands the host controller to start looking for remote devices within range.

   186   

   187 	 The HCI client should not issue a second  Inquiry() before the first has 

   188 	 completed, because the HC cannot cope with this and will return a 

   189 	 COMMAND_DISALLOWED error

   190 

   191 	 @param aFrame The HCI frame to format

   192 	 @param aCode InquiryAccessCode (3 bytes)

   193 	 @param aLength InquiryLength N where N * 1.28s is the no. of seconds for inquiry

   194 	 @param aNumResponses Number of responses from inquiry before it is halted - default 0 is unlimited number of responses.

   195 	 @released

   196 	 @publishedPartner

   197 	 */

   198     virtual void Inquiry(CHCICommandFrame& aFrame, const TUint aCode=KGIAC, const TUint8 aLength=10, const TUint8 aNumResponses=0)=0;

   199 

   200     /** Cancels an ongoing inquiry.

   201 

   202 	 @param aFrame frame to apply any necessary formatting to for inquiry cancel.

   203      @released

   204      @publishedPartner

   205      */

   206     virtual void InquiryCancel(CHCICommandFrame& aFrame)=0;

   207 

   208     /** Commands the host controller to enter periodic enquiry mode

   209 

   210 	 @param aFrame The HCI frame to format

   211 	 @param aMax MaxPeriodLength. The HC chooses a value between aMax and aMin. 

   212 	 @param aMin MinPeriodLength 

   213 	 @param aCode InquiryAccessCode (3 bytes)

   214 	 @param aLength InquiryLength (default N=2)

   215 	 @param aNumResponses Number of Responses (default=0)

   216      @released

   217      @publishedPartner

   218      */

   219 	virtual void PeriodicInquiryMode(CHCICommandFrame& aFrame, TUint16 aMax,TUint16 aMin, const TUint aCode=0,const TUint8 aLength=2,const TUint8 aNumResponses=0)=0;

   220 

   221 	/** Exits the periodic inquiry.

   222 

   223 	 @param aFrame The HCI frame to format

   224 	 @released

   225 	 @publishedPartner

   226 	 */

   227     virtual void ExitPeriodicInquiryMode(CHCICommandFrame& aFrame)=0;

   228 

   229 	/**	Initiates connection to remote device using the specified baseband packet type.

   230 

   231 	 @param aFrame The HCI frame to format

   232 	 @param aBdaddr remove device address

   233 	 @param aPacketType Packet Type

   234 	 @param aPageScanRepetitionMode pages scan repetition mode

   235 	 @param aPageScanMode page scan mode

   236 	 @param aClockOffset Offset between local and remote clock

   237 	 @param aAllowRoleSwitch Whether the remote device is allowed to role switch the local device

   238 	 @released

   239 	 @publishedPartner

   240 	 */

   241     virtual void CreateConnection(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,

   242 					TUint16 aPacketType=KDM1Packet, TUint8 aPageScanRepetitionMode=0,

   243 					TUint8 aPageScanMode=0, TUint16 aClockOffset=0, TUint8 aAllowRoleSwitch=1)=0;

   244 

   245     /**	Add an SCO connection between the Host Controller and the remote device.

   246 

   247 	 @param aFrame The HCI frame to format

   248 	 @param aConnHandle Connection handle

   249 	 @param aPacketType Packet Type

   250      @released

   251      @publishedPartner

   252      */

   253     virtual void AddSCOConnection(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle,TUint16 aPacketType)=0;

   254 

   255 

   256 

   257 

   258 

   259 

   260 

   261 	/**

   262 	Adds a new or modifies an existing synchronous logical transport (SCO or eSCO)

   263 	@param aFrame The HCI frame to format	

   264 	@param aConnHandle Connection handle (2 bytes)

   265 	@param aTransmitBandwidth (4 bytes)

   266 	@param aReceiveBandwidth  (4 bytes)

   267 	@param aMaxLatency        (2 bytes)

   268 	@param aVoiceSettings     (2 bytes)

   269 	@param aRetransmissionEffort (1 bytes)	

   270 	@param aPacketType 		     (2 bytes)	

   271 	*/

   272 	virtual void SetupSynchronousConnectionCommand(CHCICommandFrame& aFrame, TUint16 aConnHandle,

   273 						TUint aTransmitBandwidth,	TUint aReceiveBandwidth, TUint16 aMaxLatency,

   274 						TUint16 aVoiceSettings,	TUint8  aRetransmissionEffort,

   275 						TUint16 aPacketType)=0;

   276 

   277 	/**

   278 	Accepts an incoming connection request for an synchronous connection.

   279 	@param aFrame The HCI frame to format	

   280 	@param aBdaddr BDADDR (6 bytes)

   281 	@param aTransmitBandwidth (4 bytes)

   282 	@param aReceiveBandwidth  (4 bytes)

   283 	@param aMaxLatency        (2 bytes)

   284 	@param aContentFormat        (2 bytes)

   285 	@param aRetransmissionEffort (1 bytes)	

   286 	@param aPacketType           (2 bytes)

   287 	*/					

   288 	virtual void AcceptSynchronousConnectionRequestCommand(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,

   289 						TUint aTransmitBandwidth,	TUint aReceiveBandwidth, TUint16 aMaxLatency,

   290 						TUint16 aContentFormat, TUint8  aRetransmissionEffort, TUint16 aPacketType)=0;

   291 	/**

   292 	Rejects the synchronous connction from thre remote device (aBdaddr).

   293 

   294 	@param aFrame The HCI frame to format

   295 	@param aBdaddr BDADDR

   296 	@param THCIErrorCode Reject reason

   297 	*/					

   298 	virtual void RejectSynchronousConnectionRequestCommand(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,THCIErrorCode aReason)=0;

   299 																	

   300 

   301 

   302 

   303 

   304 

   305 

   306     /**	Accepts an incoming connection request.

   307 

   308 	 @param aFrame The HCI frame to format

   309 	 @param aBdaddr bluetooth address of remote device

   310 	 @param aRole Role - 0x00=Master, 0x01=Slave.

   311      @released

   312      @publishedPartner

   313      */

   314     virtual void AcceptConnectionRequest(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,TUint8 aRole)=0;

   315 

   316     /**	Rejects the connection from the remote device.

   317 

   318 	 @param aFrame The HCI frame to format

   319 	 @param aBdaddr Bluetooth address of remote device

   320 	 @param THCIErrorCode Reject reason

   321      @released

   322      @publishedPartner

   323      */

   324     virtual void RejectConnectionRequest(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,THCIErrorCode aReason)=0;

   325 

   326     /**	Replies to the remote host with the supplied link key.

   327 

   328 	 @param aFrame The HCI frame to format

   329 	 @param aBdaddr bluetooth address of remote device

   330 	 @param aLinkKey Link key (16 bytes)

   331      @released

   332      @publishedPartner

   333      */

   334     virtual void LinkKeyRequestReply(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,const TDesC8& aLinkKey)=0;

   335 

   336     /**	Notifies the remote host that the link key was not accepted.

   337 

   338 	 @param aFrame The HCI frame to format

   339 	 @param aBdaddr Bluetooth address of remote device

   340      @released

   341      @publishedPartner

   342      */

   343     virtual void LinkKeyRequestNegativeReply(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr)=0;

   344 

   345     /**	Returns to the remote host the requested PIN.

   346 

   347 	 @param aFrame The HCI frame to format

   348 	 @param aBdaddr Bluetooth address of remote device

   349 	 @param aPIN PIN Code (up to 16 bytes)

   350      @released

   351      @publishedPartner

   352      */

   353     virtual void PINCodeRequestReply(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,const TDesC8& aPIN)=0; 

   354 

   355     /**	Notifies the remote host that the PIN code was rejected.

   356 

   357 	 @param aFrame The HCI frame to format

   358 	 @param aBdaddr Bluetooth address of remote device

   359      @released

   360      @publishedPartner

   361      */

   362     virtual void PINCodeRequestNegativeReply(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr)=0; 

   363 

   364     /**	Disconnect the ACL or SCO connection corresponding to the supplied handle.

   365 

   366 	 @param aFrame The HCI frame to format

   367 	 @param aConnHandle Handle of connection to disconnect

   368 	 @param aReason Reason for disconnection

   369      @released

   370      @publishedPartner

   371      */

   372 	virtual void Disconnect(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle,THCIErrorCode aReason)=0;

   373 

   374 	/**	Changes baseband packet type (e.g DH1, DM3 etc.).

   375 

   376 	 @param aFrame The HCI frame to format

   377 	 @param aConnHandle Connection Handle

   378 	 @param aType Packet Type.  This should be one of the consts defined in hcibase.h e.g. KDM1Packet.

   379 	 @released

   380 	 @publishedPartner

   381 	 */

   382 	virtual void ChangeConnectionPacketType(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle,TUint16 aType)=0;

   383 

   384 	/** Perform authenticaction request.	

   385 

   386 	 @param aFrame The HCI frame to format

   387 	 @param aConnHandle Connection Handle

   388 	 @released

   389 	 @publishedPartner

   390 	 */

   391     virtual void AuthenticationRequest(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   392 

   393     /** Sets connection encryption

   394 

   395 	 @param aFrame The HCI frame to format

   396 	 @param aConnHandle Connection Handle

   397 	 @param aEnable Enable flag ETrue=Enable link encryption, EFalse=Disable link encryption

   398      @released

   399      @publishedPartner

   400      */

   401     virtual void SetEncryptionEnable(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle,TBool aEnable)=0;

   402 

   403     /**	Notifies host of need to change connection key for the supplied connection handle.

   404 

   405 	 @param aFrame The HCI frame to format

   406 	 @param aConnHandle Connection Handle

   407      @released

   408      @publishedPartner

   409      */

   410     virtual void ChangeConnectionLinkKey(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   411 

   412     /**	Not used.

   413 

   414 	 @param aFrame The HCI frame to format

   415 	 @param aKeyFlag Link Key Flag. Possible values are ETrue to use temporary link key or EFalse to  use regular link key

   416      @released

   417      @publishedPartner

   418      */

   419     virtual void MasterLinkKey(CHCICommandFrame& aFrame, TBool aKeyFlag)=0;

   420 

   421     /**	Retrieves the remote hosts advertised hardware/firmware features.

   422 

   423 	 @param aFrame The HCI frame to format

   424 	 @param aConnHandle Connection Handle

   425      @released

   426      @publishedPartner

   427      */

   428     virtual void ReadRemoteSupportedFeatures(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   429 

   430     /**	Retrieve remote hosts HW/Firmware revision information.

   431 

   432 	 @param aFrame The HCI frame to format

   433 	 @param aConnHandle Connection Handle

   434      @released

   435      @publishedPartner

   436      */

   437     virtual void ReadRemoteVersionInfo(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   438 

   439 	/** Request on human redable name of remote host.

   440 

   441 	 @param aFrame The HCI frame to format

   442 	 @param aBdaddr The bluetooth address of device on which we seek to find a name

   443 	 @param aPageScanRepetitionMode Page scan repetition mode

   444 	 @param aPageScanMode Page scan mode

   445 	 @param aClockOffset Offset of remote device clock from local device clock

   446 	 @released

   447 	 @publishedPartner

   448 	 */

   449     virtual void RemoteNameRequest(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr, TUint8 aPageScanRepetitionMode=0,

   450 					TUint8 aPageScanMode=0, TBasebandTime aClockOffset=0)=0;

   451 

   452     /**	Retrieve offset of remote clock from local clock.

   453 

   454 	 @param aFrame The HCI frame to format

   455 	 @param aConnHandle Connection Handle

   456      @released

   457      @publishedPartner

   458      */

   459     virtual void ReadClockOffset(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   460 

   461 	// HCI Link Policy Commands 

   462     /**	Write local link policy settings

   463 

   464 	 @param aFrame The HCI frame to format

   465 	 @param aConnHandle Connection Handle

   466 	 @param aSettings @see Bluetooth HCI specification

   467      @released

   468      @publishedPartner

   469      */

   470 	virtual void WriteLinkPolicySettings(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle, TUint16 aSettings)=0;

   471 

   472 	/**	Switch radio and host controller to Hold mode.

   473 

   474 	 @param aFrame The HCI frame to format

   475 	 @param aConnHandle Connection Handle 

   476 	 @param aHoldMaxInterval Max Hold Interval N, where Time of Hold=N*0.625ms (1 baseband slot)

   477 	 @param aHoldMinInterval Min Hold interval N, as above (both up to 40.9 sec)

   478 	 @released

   479 	 @publishedPartner

   480 	 */

   481     virtual void HoldMode(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle, TBasebandTime aHoldMaxInterval, 

   482 		TBasebandTime aHoldMinInterval)=0;

   483 

   484 	/**	Switch radio and host controller to Sniff mode.

   485 

   486 	 @param aFrame The HCI frame to format

   487 	 @param aConnHandle Connection Handle

   488 	 @param aSniffMaxInterval Max Sniff length (Max number of acceptable slots in a sniff period) N, where the interval (time between sniffs)=N*0.625ms (1 baseband slot)

   489 	 @param aSniffMinInterval Min Sniff interval , as above

   490 	 @param aAttemptSlots Sniff Attempt - the period the slave will listen after each sniff interval

   491 	 @param aTimeOutSlots Sniff Timeout - time listening for packets as long as some arrive

   492 	 @released

   493 	 @publishedPartner

   494 	 */

   495     virtual void SniffMode(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle,TBasebandTime aSniffMaxInterval,TBasebandTime

   496 		aSniffMinInterval, TBasebandTime aAttempSlots, TBasebandTime aTimeOutSlots)=0;

   497 

   498 	/**	Switch radio and host out of the Sniff mode.

   499 

   500 	 @param aFrame The HCI frame to format

   501 	 @param aConnHandle Connection Handle

   502 	 @released

   503 	 @publishedPartner

   504 	 */

   505     virtual void ExitSniffMode(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   506 

   507 	/**	Switch radio and host controller to the Park mode.

   508 

   509 	 @param aFrame The HCI frame to format

   510 	 @param aConnHandle Connection Handle

   511 	 @param aBeaconMax Beacon Max Interval Length N where interval between beacons=N*0.625ms

   512 	 @param aBeaconMin Beacon Min Interval Length N where interval between beacons=N*0.625ms

   513 	 @released

   514 	 @publishedPartner

   515 	 */

   516     virtual void ParkMode(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle, TBasebandTime aBeaconMaxInterval, 

   517 		TBasebandTime aBeaconMinInterval)=0;

   518 

   519     /**	Switch radio and host controller off the Park mode.

   520 

   521 	 @param aFrame The HCI frame to format

   522  	 @param aConnHandle Connection Handle

   523      @released

   524      @publishedPartner

   525      */

   526     virtual void ExitParkMode(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   527 

   528 	/**	Initiate role discovery for the supplied connection handle.

   529 

   530 	 @param aFrame The HCI frame to format

   531 	 @param aConnHandle Connection Handle

   532 	 @released

   533 	 @publishedPartner

   534 	 */

   535     virtual void RoleDiscovery(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   536 

   537 	/**	Switch current role (master / slave) for the physical link associated with the bluetooth device address provided.

   538 	

   539 	 @param aFrame The HCI frame to format

   540 	 @param aRole New role 

   541 	 @param aAddr Bluetooth device address of remote device 

   542 	 @released

   543 	 @publishedPartner

   544 	 */

   545 	virtual void SwitchRole(CHCICommandFrame& aFrame, TBTBasebandRole aRole, const TBTDevAddr& aAddr)=0;

   546 

   547 

   548 	// HCI Host Controller and Baseband Commands 

   549 	/**	Sets the mask for the reception or the filtering-out of HCI events from the host controller.

   550 

   551  	 @param aFrame The HCI frame to format

   552 	 @param aMask Event Mask

   553 	 @released

   554 	 @publishedPartner

   555 	 */

   556     virtual void SetEventMask(CHCICommandFrame& aFrame, const THCIEventMask& aMask)=0;

   557 

   558     /**	Resets the Host Controller hardware state. 

   559 

   560 	 @param aFrame The HCI frame to format

   561      @released

   562      @publishedPartner

   563      */

   564     virtual void Reset(CHCICommandFrame& aFrame)=0;

   565 

   566     /**	Set the filter mask for remotely initiated  events.

   567 

   568 	 @param aFrame The HCI frame to format

   569 	 @param aData Denotes the filter 'category' and its particular properties as such its 'category'/type may be EClearAllFilters, EInquiryResultFilter or EConnectionSetupFilter. Then its condition type (aData.iConditionType) can be as defined in the spec

   570      @released

   571      @publishedPartner

   572      */

   573     virtual void SetEventFilter(CHCICommandFrame& aFrame, const THCIEventCondition& aData)=0;

   574 

   575     /**	Flush buffers corresponding to the supplied connection handle.

   576 

   577 	 @param aFrame The HCI frame to format

   578 	 @param aConnHandle Connection Handle

   579      @released

   580      @publishedPartner

   581      */

   582     virtual void Flush(CHCICommandFrame& aFrame, THCIConnHandle aConnHandle)=0;

   583 

   584     /**	Creates a new unit key in the host controller.

   585 

   586 	 @param aFrame The HCI frame to format

   587      @released

   588      @publishedPartner

   589      */

   590     virtual void CreateNewUnitKey(CHCICommandFrame& aFrame)=0;

   591 

   592     /**	Reads out from the host controller the stored link key for given device address

   593 

   594 	 @param aFrame The HCI frame to format

   595 	 @param aBdaddr Bluetooth device address to read the link key for.

   596 	 @param aFlag Read all keys flag

   597      @released

   598      @publishedPartner

   599      */

   600     virtual void ReadStoredLinkKey(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,THCIReadAllKeysFlag aFlag)=0;

   601 

   602 	/**	Writes a Link Key to the Host Controllers volatile storage memory.  You can write as many keys as you want to storage - this function just does one at a time.

   603 	

   604 	 @param aFrame The HCI frame to format

   605 	 @param aNumOfKeysToWrite Number of keys to write to storage

   606 	 @param aBdaddr Bluetooth device address for the associated link key

   607 	 @param aLinkKey The Link Key

   608 	 @released

   609 	 @publishedPartner

   610 	 */

   611     virtual void WriteStoredLinkKey(CHCICommandFrame& aFrame, /*TUint8 aNumOfKeysToWrite,*/

   612 		const TBTDevAddr& aBdaddr,const TDesC8& aLinkKey)=0;

   613 

   614     /**	Delete the link key stored in the host controller's volatile storage.

   615 

   616 	 @param aFrame The HCI frame to format

   617 	 @param aBdaddr Bluetooth device address associated with the link key to delete.

   618 	 @param aFlag Delete options flag

   619      @released

   620      @publishedPartner

   621      */

   622     virtual void DeleteStoredLinkKey(CHCICommandFrame& aFrame, const TBTDevAddr& aBdaddr,THCIDeleteAllKeysFlag aFlag)=0;

   623 

   624     /**	Sets the local Bluetooth device name.

   625 

   626 	 @param aFrame The HCI frame to format

   627 	 @param aName Local device name (max 248 characters as defined in bluetooth specification).

   628      @released

   629      @publishedPartner

   630      */

   631     virtual void ChangeLocalName(CHCICommandFrame& aFrame, const TDesC8& aName)=0;

   632 

   633     /**	Reads out the stored local Bluetooth device name.

   634 	

   635 	 @param aFrame The HCI frame to format

   636      @released

   637      @publishedPartner

   638      */

   639 	virtual void ReadLocalName(CHCICommandFrame& aFrame)=0;

   640 

   641 	/**	Reads out of the Bluetooth device the connection accept timeout, for incoming connections.

   642 

   643 	 @param aFrame The HCI frame to format

   644 	 @released

   645 	 @publishedPartner

   646 	 */

   647     virtual void ReadConnectionAcceptTimeout(CHCICommandFrame& aFrame)=0;

   648 

   649     /**	Sets the connection accept timeout in the host controller.

   650 

   651 	 @param aFrame The HCI frame to format

   652 	 @param aTimeout The connection timeout

   653      @released

   654      @publishedPartner

   655      */

   656     virtual void WriteConnectionAcceptTimeout(CHCICommandFrame& aFrame, TBasebandTime aTimeout)=0;

   657     

   658     /**	Commands the Bluetooth hardware to respond with its Page Timeout.

   659 	

   660 	 @param aFrame The HCI frame to format

   661      @released

   662      @publishedPartner

   663      */

   664 	virtual void ReadPageTimeout(CHCICommandFrame& aFrame)=0;

   665 

   666 	/**	Sets the page timeout in the host controller.

   667 

   668 	 @param aFrame The HCI frame to format

   669 	 @param aTimeout Page Timeout.  This must be between KMaxPageTimeout and KMinPageTimeout.

   670 	 @released

   671 	 @publishedPartner

   672 	 */

   673     virtual void WritePageTimeout(CHCICommandFrame& aFrame, TBasebandTime aTimeout)=0;

   674 

   675     /**	Read out of the host controller the scan options.

   676 	

   677 	 @param aFrame The HCI frame to format

   678      @released

   679      @publishedPartner

   680      */

   681     virtual void ReadScanEnable(CHCICommandFrame& aFrame)=0;

   682 

   683     /**	Sets the scan options on the host controller.

   684 

   685 	 @param aFrame The HCI frame to format

   686 	 @param  aScanEnable Scan enable options

   687      @released

   688      @publishedPartner

   689      */

   690     virtual void WriteScanEnable(CHCICommandFrame& aFrame, THCIScanEnable aEnable=EInquiryAndPageScan)=0;

   691 	

   692     /**	Read out of the host controller the number of supported inquiry access codes.

   693 

   694 	 @param aFrame The HCI frame to format

   695      @released

   696      @publishedPartner

   697      */

   698 	virtual void ReadNumberOfSupportedIAC(CHCICommandFrame& aFrame)=0;

   699 

   700 	/**	Write to the host controller the lower address parts supplied.

   701 

   702 	 @param aFrame The HCI frame to format

   703 	 @param aNumCurrentIAC The number of inquiry access code lower address parts being sent to the hardware

   704 	 @param aIAC_LAP The inquiry access code lower address parts - 3 bytes each: e.g: GIACLAP=0x9e8b33, LIACLAP=0x9e8b00

   705 	 @released

   706 	 @publishedPartner

   707 	 */

   708     virtual void WriteCurrentIACLAP(CHCICommandFrame& aFrame, TUint8 aNumCurrentIAC, TUint aIAC_LAP[])=0;

   709 

   710     /**	Read out the inquiry access code lower address parts.

   711 	

   712 	 @param aFrame The HCI frame to format

   713      @released

   714      @publishedPartner

   715      */

   716 	virtual void ReadCurrentIACLAP(CHCICommandFrame& aFrame)=0;

   717 

   718 	/**	Read out from the host controller whether authentication is enabled.

   719 

   720 	 @param aFrame The HCI frame to format

   721 	 @released

   722 	 @publishedPartner

   723 	 */

   724     virtual void ReadAuthenticationEnable(CHCICommandFrame& aFrame)=0;

   725 

   726     /**	Set/Unset authentication.

   727 

   728 	 @param aFrame The HCI frame to format

   729 	 @param aAuthEnable	Authentication Enable.  Possible values are EFalse for authentication disabled or ETrue for authentication enabled

   730      @released

   731      @publishedPartner

   732      */

   733     virtual void WriteAuthenticationEnable(CHCICommandFrame& aFrame, TBool aAuthEnable)=0;

   734 

   735     /**	Read out the encryption mode.

   736 

   737 	 @param aFrame The HCI frame to format

   738      @released

   739      @publishedPartner

   740      */

   741     virtual void ReadEncryptionMode(CHCICommandFrame& aFrame)=0;

   742 

   743     /**	Set/unset the encryption.

   744 

   745 	 @param aFrame The HCI frame to format

   746 	 @param aFlag Whether to enable encryption.	 Possible values are EFalse to disable encryption or ETrue to enable encryption.

   747      @released

   748      @publishedPartner

   749      */

   750     virtual void WriteEncryptionMode(CHCICommandFrame& aFrame, THCIEncryptModeFlag aFlag)=0;

   751 

   752     /**	Reads out the class of device of the local Bluetooth device.

   753 

   754 	 @param aFrame The HCI frame to format

   755      @released

   756      @publishedPartner

   757      */

   758     virtual void ReadClassOfDevice(CHCICommandFrame& aFrame)=0;

   759 

   760     /**	Sets the local Bluetooth class of device.

   761 

   762 	 @param aFrame The HCI frame to format

   763 	 @param aCoD Class Of Device

   764      @released

   765      @publishedPartner

   766      */

   767     virtual void WriteClassOfDevice(CHCICommandFrame& aFrame, TUint aCoD)=0;

   768 

   769     /**	Read the Bluetooth hardware voice settings.

   770 

   771 	 @param aFrame The HCI frame to format

   772      @released

   773      @publishedPartner

   774      */

   775 	virtual void ReadVoiceSetting(CHCICommandFrame& aFrame)=0;

   776 

   777 	/**	Set the local Bluetooth device voice settings. 

   778 

   779 	 @param aFrame The HCI frame to format

   780 	 @param aVoiceChannelSetting	Voice channel settings as defined by the HCI specification.

   781 	 @released

   782 	 @publishedPartner

   783 	 */

   784 	virtual void WriteVoiceSetting(CHCICommandFrame& aFrame, TInt16 aVoiceChannelSetting)=0;

   785     

   786 	// HCI Informational Parameters Commands

   787 	/**	Retrieve local hardware/firmware revision info.

   788 

   789 	 @param aFrame The HCI frame to format

   790 	 @released

   791 	 @publishedPartner

   792 	 */

   793 	virtual void ReadLocalVersionInformation(CHCICommandFrame& aFrame)=0;

   794 

   795 	/**	Retrieve local hardware/firmware capabilities.

   796 

   797 	 @param aFrame The HCI frame to format

   798 	 @released

   799 	 @publishedPartner

   800 	 */

   801 	virtual void ReadLocalSupportedFeatures(CHCICommandFrame& aFrame)=0;

   802 

   803 	/**	Retrieve from the host controller its buffering capabilities.

   804 

   805 	 @param aFrame The HCI frame to format

   806 	 @released

   807 	 @publishedPartner

   808 	 */

   809     virtual void ReadBufferSize(CHCICommandFrame& aFrame)=0;  

   810   

   811     /**	Retrieve the hardware's intended country code (for security/encryption issues). 

   812 

   813 	 @param aFrame The HCI frame to format

   814      @released

   815      @publishedPartner

   816      */

   817 	virtual void ReadCountryCode(CHCICommandFrame& aFrame)=0;

   818 

   819 	/**	Retrieve local Bluetooth device address.

   820 

   821 	 @param aFrame The HCI frame to format

   822 	 @released

   823 	 @publishedPartner

   824 	 */

   825     virtual void ReadBDADDR(CHCICommandFrame& aFrame)=0;

   826 	

   827 	// Host Controller to Host Data Flow Control

   828     /**	Set/unset notification of delivery of packets, from the host controller to the host.

   829 

   830 	 @param aFrame The HCI frame to format

   831 	 @param aFlowFlag Flow Control Enable flag

   832      @released

   833      @publishedPartner

   834      */

   835     virtual void SetHostControllerToHostFlowControl(CHCICommandFrame& aFrame, TBool aHC2HFlowFlag)=0;// may return KErrNoMemory

   836 

   837     /** Notification to host controller of the number of packets that the above 

   838 	 layers (L2CAP) have consumed.  HostNumberOfCompletedPackets command to be 

   839 	 issued by L2CAP.

   840 

   841 	 @param aFrame The HCI frame to format

   842 	 @param aNumHandles	Number of connectionhandles

   843 	 @param aConnH Connection handle 

   844 	 @param aCompletedPacketsNo	Host num of completed packets

   845      @released

   846      @publishedPartner

   847      */

   848 	virtual void HostNumberOfCompletedPackets(CHCICommandFrame& aFrame, TUint8 aNumHandles, THCIConnHandle aConnH[], TUint16 aCompletedPacketsNo[])=0;

   849 

   850 	/**	Notifies the host controller of the hosts buffering capabilities.

   851 

   852 	 @param aFrame The HCI frame to format

   853 	 @param aACLDataLength	Host's ACL Data Packet Length

   854 	 @param aSCODataLength	Host's SCO Data Packet Length   

   855 	 @param aTotalACLPackets Total Number of ACL Data Packets that the Host can handle

   856 	 @param aTotalSCOPackets Total Number of SCO Data Packets that the Host can handle

   857 	 @released

   858 	 @publishedPartner

   859 	 */

   860 	virtual void HostBufferSize(CHCICommandFrame& aFrame, TUint16 aACLDataLength,TUint8 aSCODataLength,

   861         TUint16 aTotalACLPackets, TUint16 aTotalSCOPackets)=0;

   862 

   863 	/** Writes link supervision timeout.

   864 

   865 	 @param aFrame The HCI frame to format

   866 	 @param aConnH Connection handle

   867 	 @param aTimeout Timeout to write

   868 	 @released

   869 	 @publishedPartner

   870 	 */

   871 	virtual void WriteLinkSupervisionTimeout(CHCICommandFrame& aFrame, THCIConnHandle aConnH, TBasebandTime aTimeout)=0;

   872 

   873 	/** This call allows for a raw HCI command frame to be written to the HC.

   874 

   875     This is intended for vendor specific commands for which the opcode 

   876 	field will be known to the HCI.

   877 

   878     These raw frames should be constructed by calling the HCI factory

   879     function with the opcode constructed of the vendor debug opcode group field

   880 	and the particular OCF required.  This function should then be called with the

   881     appropriately formatted parameters which shall be placed into the frame's

   882     payload.  It should be noted that the client need NOT to be concerned

   883     with the HCTL framing at all.

   884 

   885     The HCI will only then copy this frame to the host controller after putting 

   886 	it in an HCTL frame.

   887 

   888     Note that the client is responsible for policing the size of the descriptor

   889     passed to this function.  The length should be: 0 <= n <= KHCIMaxCommandLength

   890 

   891      @param aFrame The HCI frame to format

   892      @param aData The frame parameters   

   893 	 @released

   894 	 @publishedPartner

   895 	 */

   896 	virtual void WriteVendorRawFrameCommand(CHCICommandFrame& aFrame, const TDesC8& aData)=0;

   897 

   898 

   899 	// HCI Status Parameters Commands

   900 	// not here yet

   901 	

   902 	// HCI Testing Commands

   903 	// not here yet 

   904 	/** Used for testing.

   905 

   906 	 @released

   907 	 @internalComponent

   908 	 */

   909 	virtual TAny *LogIndex() const=0;

   910 

   911 	// methods to allow stack to query HCI about its features

   912 	/** Reads ACL reporting interval.

   913 

   914 	 @return the ACL reporting interval.

   915 	 @released

   916 	 @publishedPartner

   917 	 */

   918 	virtual TUint16 ReadACLReportingInterval() = 0; // Some hardware only reports on the nth ACL data packet being sent

   919 	                                                // this is an opportunity for the HCI to supply a minimum value of n

   920 													// to the Link Manager

   921 

   922 	/** Reads size of HCI framing overhead per frame.

   923 

   924 	 @return size of HCI framing overhead per frame.

   925 	 @released

   926 	 @publishedPartner

   927 	 */

   928 	virtual TUint16 ReadACLFramingOverhead() = 0; // Size of HCI framing overhead per frame

   929 

   930 	// Adaptive Frequency Hopping (AFH)

   931 	

   932 	/**	Notifies the host controller of channels that are known by the host to be bad or to be about to be bad.

   933 	

   934 	 This allows those channels to be avoided if Adaptive Frequency Hopping is active on a connection.

   935 	 

   936 	 @param aFrame The HCI frame to format

   937 	 @param aChannelClassification Bitwise representation of the bad channels

   938 	 @released

   939 	 @publishedPartner

   940 	 */

   941     virtual void SetAFHHostChannelClassification(CHCICommandFrame& aFrame, const TDesC8& aChannelClassification)=0;

   942 

   943 	/**	Retrieves the AFH channel map being used on the specified connection.

   944 	

   945 	 If we are master this will be the local AFH channel map. If we are slave it 

   946 	 will be the remote master's AFH channel map.

   947 	 

   948 	 @param aFrame The HCI frame to format

   949 	 @param aConnH Connection handle 

   950 	 @released

   951 	 @publishedPartner

   952 	*/

   953 	virtual void ReadAFHChannelMap(CHCICommandFrame& aFrame, THCIConnHandle aConnH)=0;

   954 

   955  	/**	Notifies the host controller whether or not it is required to keep checking for busy channels..

   956 	

   957 	 @param aFrame The HCI frame to format

   958 	 @param aEnable Check for busy channels if ETrue, otherwise don't

   959 	 @released

   960 	 @publishedPartner

   961 	 */

   962     virtual void WriteAFHChannelAssessmentMode(CHCICommandFrame& aFrame, TBool aEnable)=0;

   963 

   964  	/**	Asks the host controller whether or not it is checking for busy channels..

   965 	

   966 	 @param aFrame The HCI frame to format

   967 	 @released

   968 	 @publishedPartner

   969 	 */

   970     virtual void ReadAFHChannelAssessmentMode(CHCICommandFrame& aFrame)=0;

   971 

   972     /** HCI level Ioctl

   973 

   974 	 @param aLevel			The Ioctl level

   975 	 @param aName			The Ioctl function number

   976 	 @param aOption			Data associated with this Ioctl

   977 	 @param aStackSAP		A pointer to the SAP, used to track Ioctls

   978      @released

   979      @publishedPartner

   980      */

   981 	virtual void Ioctl(TUint aLevel,TUint aName, TDes8* aOption, TAny* aStackSAP) = 0;

   982 

   983     /** Cancel HCI level Ioctl

   984 

   985 	 @param aLevel			The Ioctl level

   986 	 @param aName			The Ioctl function number

   987 	 @param aStackSAP		A pointer to the SAP, used to track Ioctls

   988      @released

   989      @publishedPartner

   990      */

   991 	virtual void CancelIoctl(TUint aLevel,TUint aName, TAny* aStackSAP) = 0;

   992 	};

   993 

   994 enum THCIErrorCode;

   995 

   996 

   997 

   998 /** Event handler mixin that must be implemented by the client of HCI.

   999 

  1000 A class that implements this interface must be passed into the

  1001 CHCIBase derived class on construction, and will be used by the HCI

  1002 class to notify the client of events received over the HCI interface.

  1003 

  1004 @released

  1005 @publishedPartner

  1006 */

  1007 class MHCIEventObserver

  1008     {   

  1009 public:

  1010 	// Interfaces to allow HCI to notify LL

  1011 	/** This provides command credits.

  1012 

  1013 	 @param aCredits Provided command credits.

  1014 	 @released

  1015 	 @publishedPartner

  1016 	 */

  1017 	virtual void SetCommandCredits(TUint16 aCredits)=0;

  1018 

  1019 	/** Informs of the ACL MTU for this host.

  1020 

  1021 	 @param aMTU Maximum size of ACL packet the host can send.

  1022 	 @released

  1023 	 @publishedPartner

  1024 	 */

  1025 	virtual void HCIMaximumACLPacketSize(TUint16 aMTU)=0;

  1026 

  1027 	/** Called when transport channels have become free.

  1028 

  1029 	 @param aChannel Channel that is free.

  1030 	 @released

  1031 	 @publishedPartner

  1032 	 */

  1033 	virtual void CanSend(THCITransportChannel aChannel = KHCITransportAllChannels)=0;

  1034 

  1035 	// Events as per spec

  1036 	/** Called on an inquiry complete event.

  1037 

  1038 	 @param aNumResponses Number of responses received from the inquiry.  This is zero if not supported or there is an error.

  1039 	 @param aErr HCI specific or system wide error code.

  1040 	 @released

  1041 	 @publishedPartner

  1042 	 */

  1043     virtual void InquiryCompleteEvent(THCIErrorCode aErr, TUint8 aNumResponses)=0;

  1044 

  1045     /** Called on an inquiry result complete event.

  1046 

  1047 	 @param aEntry TInquiryLogEntry containing results of inquiry.

  1048      @param aErr HCI specific or system wide error code.

  1049      @released

  1050      @publishedPartner

  1051      */

  1052     virtual void InquiryResultCompleteEvent(THCIErrorCode aErr,const TInquiryLogEntry& aEntry)=0;

  1053 

  1054     /** Called on a connection complete event.

  1055 

  1056 	 @param aConn Contains information about the completed connection.

  1057      @param aErr HCI specific or system wide error code.

  1058      @released

  1059      @publishedPartner

  1060      */

  1061     virtual void ConnectionCompleteEvent(THCIErrorCode aErr, const TBTConnect &aConn)=0;

  1062 

  1063     /** Called on a connection request event.

  1064 

  1065 	 @param aConn Information about the device requesting the connection.

  1066      @released

  1067      @publishedPartner

  1068      */

  1069     virtual void ConnectionRequestEvent(const TBTConnect &aConn)=0;

  1070 

  1071     /** Called on a disconnection complete event.

  1072 

  1073 	 @param aConnH Connection handle

  1074 	 @param aReason Reason for disconnection.

  1075      @param aErr HCI specific or system wide error code.

  1076      @released

  1077      @publishedPartner

  1078      */

  1079     virtual void DisconnectionCompleteEvent(THCIErrorCode aErr, THCIConnHandle aConnH, THCIErrorCode aReason)=0;

  1080 

  1081     /** Called on an authentication complete event.

  1082 

  1083 	 @param aConnH Connection handle

  1084      @param aErr HCI specific or system wide error code.

  1085      @released

  1086      @publishedPartner

  1087      */

  1088     virtual void AuthenticationCompleteEvent(THCIErrorCode aErr, THCIConnHandle aConnH)=0;

  1089 

  1090     /** Called on a remote name request complete event.

  1091 

  1092 	 @param aBdaddr Bluetooth address of remote device

  1093 	 @param aBuf Name of remote device (max 248 bytes as defined by the bluetooth specification).

  1094      @param aErr HCI specific or system wide error code.

  1095      @released

  1096      @publishedPartner

  1097      */

  1098     virtual void RemoteNameReqCompleteEvent(THCIErrorCode aErr, const TBTDevAddr& aBdaddr, const TDesC8& aBuf)=0;

  1099 

  1100     /** Called on encryption change event.

  1101 

  1102 	 @param aConnH Connection handle

  1103 	 @param aEnable Whether encryption is enabled

  1104      @param aErr HCI specific or system wide error code.

  1105      @released

  1106      @publishedPartner

  1107      */

  1108     virtual void EncryptionChangeEvent(THCIErrorCode aErr, THCIConnHandle aConnH,TBool aEnable)=0;

  1109 

  1110     /** Called on link key complete event.

  1111 

  1112 	 @param Connection handle

  1113      @param aErr HCI specific or system wide error code.

  1114      @released

  1115      @publishedPartner

  1116      */

  1117     virtual void ChangeLinkKeyCompleteEvent(THCIErrorCode aErr, THCIConnHandle aConnH)=0;

  1118 

  1119     /** Called on master link key complete event.

  1120 

  1121 	 @param aConnH Connection handle

  1122 	 @param aKeyFlag See bluetooth specification

  1123      @param aErr HCI specific or system wide error code.

  1124      @released

  1125      @publishedPartner

  1126      */

  1127     virtual void MasterLinkKeyCompleteEvent(THCIErrorCode aErr, THCIConnHandle aConnH,TBool aKeyFlag)=0;

  1128 

  1129     /** Called on read remote supported features complete event.

  1130 

  1131 	 @param aConnH Connection handle

  1132 	 @param aBitMaskList LMP_Features Bit Mask List (8 bytes)

  1133      @param aErr HCI specific or system wide error code.

  1134      @released

  1135      @publishedPartner