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

// All rights reserved.

// This component and the accompanying materials are made available

// 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

// which accompanies this distribution, and is available

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

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

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

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

// Implementations of the HCI must derive from CHCIBase.

// 

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef BT_HCIBASE_H_

#define BT_HCIBASE_H_

#include <bttypes.h>

#include <hcierrors.h>

#include <hcitypes.h>

#include <e32base.h>

#include <bluetooth/hci/hciopcodes.h>

#include <bluetooth/hci/aclpacketconsts.h>

#include <bluetooth/hci/hciconsts.h>

#include <bluetooth/hci/basebandpacketconsts.h>

class CHCICommandFrame;

class CHCIACLDataFrame;

class CHCISCODataFrame;

class CHCIBase;

class MHCIEventObserver;

class CESockIniData;

/** Factory for creating CHCIBase derived class.

To provide a new HCI implementation, re-implement this

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

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

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

create the CHCIBase derived object.

@released

@publishedPartner

*/	

NONSHARABLE_CLASS(CHCIFactory) : public CBase

    {

public: 

	CHCIFactory();

    virtual TVersion Version() const;

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

	virtual CHCICommandFrame* NewHCICommandFrameL(THCIOpcode aOpcode);

	virtual CHCIACLDataFrame* NewHCIACLDataFrameL(TUint16 aSize);

	virtual CHCISCODataFrame* NewHCISCODataFrameL(TUint8 aSize);

	};

/** Abstract HCI Interface class.

The Symbian Bluetooth stack uses this abstract class as the 

polymorphic base through which it obtains host controller

access. The actual implementation is dependent on the DLL

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

The concrete class derived from this should be returned

by the CHCIFactory class, located through ordinal 1 in the

polymorphic DLL.

@publishedPartner

@released

@see 

CHCI for detailed description of the functions.

MHCIEventObserver for the callback interface for events received over HCI.

*/ 

NONSHARABLE_CLASS(CHCIBase) : public CBase

	{

public:

	/** Writes command frame.

	 @param aFrame command frame to write

	 @return KErrBcspWriteCommandDataFailed on failure, KErrNone otherwise

	 @released

	 @publishedPartner

	 */

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

	// HCI General exports

	/** Sets option.

	 @param aName option to set

	 @param aData option value

	 @return System wide error code

	 @released

	 @publishedPartner

	 */

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

    /** Gets option.

	 @param aName option to set

	 @param aData desriptor to be filled with option data

	 @return System wide error code

     @released

     @publishedPartner

     */

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

	// HCI Data Calls

    /** Formats ACL Data.

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

	 @param aConnH Connection handle for this frame

	 @param aFlags Flags to be set for this frame

	 @param aData Data for this frame

     @released

     @publishedPartner

     */

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

	/** Formats SCO Data.

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

	 @param aConnH Connection handle for this frame

	 @param aData Data for this frame

     @released

     @publishedPartner

     */

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

    /** Writes ACL Data.

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

	 @param aFrame the formatted ACL payload from the linkmanager

	 @return System wide error code

     @released

     @publishedPartner

     */

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

	/** Writes SCO Data.

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

	 @param aFrame the formatted SCO payload from the linkmanager

	 @return System wide error code

	 @released

	 @publishedPartner

	 */

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

	// HCI Frame information commands

    /** Gets frame connection handle

	 @param aFrame the frame to return the connection handle of

	 @return the connection handle from aFrame

     @released

     @publishedPartner

     */

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

	/** Gets frame opcode.

	 @param aFrame the frame to return the opcode of

	 @return the opcode of aFrame

	 @released

	 @publishedPartner

	 */

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

	// HCI Commands

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

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

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

	 COMMAND_DISALLOWED error

	 @param aFrame The HCI frame to format

	 @param aCode InquiryAccessCode (3 bytes)

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

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

	 @released

	 @publishedPartner

	 */

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

    /** Cancels an ongoing inquiry.

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

     @released

     @publishedPartner

     */

    virtual void InquiryCancel(CHCICommandFrame& aFrame)=0;

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

	 @param aFrame The HCI frame to format

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

	 @param aMin MinPeriodLength 

	 @param aCode InquiryAccessCode (3 bytes)

	 @param aLength InquiryLength (default N=2)

	 @param aNumResponses Number of Responses (default=0)

     @released

     @publishedPartner

     */

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

	/** Exits the periodic inquiry.

	 @param aFrame The HCI frame to format

	 @released

	 @publishedPartner

	 */

    virtual void ExitPeriodicInquiryMode(CHCICommandFrame& aFrame)=0;

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

	 @param aFrame The HCI frame to format

	 @param aBdaddr remove device address

	 @param aPacketType Packet Type

	 @param aPageScanRepetitionMode pages scan repetition mode

	 @param aPageScanMode page scan mode

	 @param aClockOffset Offset between local and remote clock

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

	 @released

	 @publishedPartner

	 */

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

					TUint16 aPacketType=KDM1Packet, TUint8 aPageScanRepetitionMode=0,

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection handle

	 @param aPacketType Packet Type

     @released

     @publishedPartner

     */

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

	/**

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

	@param aFrame The HCI frame to format	

	@param aConnHandle Connection handle (2 bytes)

	@param aTransmitBandwidth (4 bytes)

	@param aReceiveBandwidth  (4 bytes)

	@param aMaxLatency        (2 bytes)

	@param aVoiceSettings     (2 bytes)

	@param aRetransmissionEffort (1 bytes)	

	@param aPacketType 		     (2 bytes)	

	*/

	virtual void SetupSynchronousConnectionCommand(CHCICommandFrame& aFrame, TUint16 aConnHandle,

						TUint aTransmitBandwidth,	TUint aReceiveBandwidth, TUint16 aMaxLatency,

						TUint16 aVoiceSettings,	TUint8  aRetransmissionEffort,

						TUint16 aPacketType)=0;

	/**

	Accepts an incoming connection request for an synchronous connection.

	@param aFrame The HCI frame to format	

	@param aBdaddr BDADDR (6 bytes)

	@param aTransmitBandwidth (4 bytes)

	@param aReceiveBandwidth  (4 bytes)

	@param aMaxLatency        (2 bytes)

	@param aContentFormat        (2 bytes)

	@param aRetransmissionEffort (1 bytes)	

	@param aPacketType           (2 bytes)

	*/					

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

						TUint aTransmitBandwidth,	TUint aReceiveBandwidth, TUint16 aMaxLatency,

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

	/**

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

	@param aFrame The HCI frame to format

	@param aBdaddr BDADDR

	@param THCIErrorCode Reject reason

	*/					

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

    /**	Accepts an incoming connection request.

	 @param aFrame The HCI frame to format

	 @param aBdaddr bluetooth address of remote device

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

     @released

     @publishedPartner

     */

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

    /**	Rejects the connection from the remote device.

	 @param aFrame The HCI frame to format

	 @param aBdaddr Bluetooth address of remote device

	 @param THCIErrorCode Reject reason

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aBdaddr bluetooth address of remote device

	 @param aLinkKey Link key (16 bytes)

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aBdaddr Bluetooth address of remote device

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aBdaddr Bluetooth address of remote device

	 @param aPIN PIN Code (up to 16 bytes)

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aBdaddr Bluetooth address of remote device

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Handle of connection to disconnect

	 @param aReason Reason for disconnection

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

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

	 @released

	 @publishedPartner

	 */

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

	/** Perform authenticaction request.	

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

	 @released

	 @publishedPartner

	 */

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

    /** Sets connection encryption

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

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

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

     @released

     @publishedPartner

     */

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

    /**	Not used.

	 @param aFrame The HCI frame to format

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

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

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

	 @param aPageScanRepetitionMode Page scan repetition mode

	 @param aPageScanMode Page scan mode

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

	 @released

	 @publishedPartner

	 */

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

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

     @released

     @publishedPartner

     */

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

	// HCI Link Policy Commands 

    /**	Write local link policy settings

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

	 @param aSettings @see Bluetooth HCI specification

     @released

     @publishedPartner

     */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle 

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

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

	 @released

	 @publishedPartner

	 */

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

		TBasebandTime aHoldMinInterval)=0;

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

	 @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)

	 @param aSniffMinInterval Min Sniff interval , as above

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

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

	 @released

	 @publishedPartner

	 */

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

		aSniffMinInterval, TBasebandTime aAttempSlots, TBasebandTime aTimeOutSlots)=0;

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

	 @released

	 @publishedPartner

	 */

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

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

	 @param aFrame The HCI frame to format

	 @param aConnHandle Connection Handle

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

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

	 @released

	 @publishedPartner

	 */

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

		TBasebandTime aBeaconMinInterval)=0;

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

	 @param aFrame The HCI frame to format

 	 @param aConnHandle Connection Handle

     @released

     @publishedPartner

     */

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

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