diff -r 000000000000 -r 29b1cd4cb562 bthci/bthci2/CommandsEvents/interface/Event.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/bthci/bthci2/CommandsEvents/interface/Event.h Fri Jan 15 08:13:17 2010 +0200 @@ -0,0 +1,430 @@ +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +/** + @file + @publishedPartner + @released +*/ + +#ifndef THCIEVENTBASE_H +#define THCIEVENTBASE_H + +#include +#include +#include +#include +#include + +class MHCICommandEventObserver; +class MHCIDataEventObserver; + +/** +Represents the common data for a HCI event. + +All of the event classes have been design to be used in a synchronous manner. All data is used by +reference and hence any other object that requires persistence of the event parameters should make +their own copy of them. +*/ +NONSHARABLE_CLASS(THCIEventBase) + { +public: + /** + Getter for the event code. + @return The event code that describes the event. + */ + IMPORT_C THCIEventCode EventCode() const; + + /** + Getter for the error code. + + Although this error code is not defined for all events in the HCI specification, the error code + is in the base class so that the command queue can use the event error in its decisions without casting + to a derived class. + Those events that do not contain an error code in the specification should return with THCIErrorCode::EOK. + + @return The error code contained in the event. + */ + IMPORT_C THCIErrorCode ErrorCode() const; + + /** + Static factory and despatcher method. + + This method creates an object of the appropriate derived type according to the event code + in the event data supplied. Depending upon the type of event, it is then passed to the + supplied Command Event observer or Data Event observer as appropriate. The event object is + created on the stack and is therefore destroyed before CreateAndSendEvent returns. + + @param aEventData The data packet containing the event + @param aEventObserver The observer for handling command-related events + @param aDataEventObserver The observer for handling data-related events + @param aObserver Additional observer parameter to allow the licensee extra future flexibility + */ + IMPORT_C static TInt CreateAndSendEvent(const TDesC8& aEventData, MHCICommandEventObserver& aEventObserver, MHCIDataEventObserver& aDataEventObserver, TAny* aObserver=NULL); + +protected: + /** + Constructor used for creating a faked event + @param aEventCode The event code for the event + @param aParameterTotalLength The total length of the event parameters + @param aEventData Empty buffer where the faked event data will be built. + Every event starts with a one-byte event code and one-byte parameter total length field, so + these are managed in this base class. The data after this is event specific and has length + equal to Parameter Total Length. It is the responsibility of the derived class faking + constructor to populate the rest of the aEventData buffer and then to set the member + variable iEventData to reference this buffer when it is complete. + Note that the aEventData buffer must persist as long as the object itself. It must be + empty intially, and must be big enough to hold all the data for the given event type. + */ + THCIEventBase(THCIEventCode aEventCode, TUint8 aParameterTotalLength, TDes8& aEventData); + /** + Normal constructor. This is used to create an event object to wrap event data received from the Controller + @param aEventData Buffer holding event data received from the Controller + */ + IMPORT_C THCIEventBase(const TDesC8& aEventData); + + /** + Retrieves a TInt8 from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TInt8 AsTInt8(TInt aOffset) const; + + /** + Retrieves a TInt8 from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TUint8s of this event. + + @return Value at offset and index. + */ + IMPORT_C TInt8 AsTInt8(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Retrieves a TUint8 from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TUint8 AsTUint8(TInt aOffset) const; + + /** + Retrieves a TUint8 from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TUint8s of this event. + + @return Value at offset and index. + */ + IMPORT_C TUint8 AsTUint8(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Retrieves a TUint16 from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TUint16 AsTUint16(TInt aOffset) const; + + /** + Retrieves a TUint16 from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TUint16s of this event. + + @return Value at offset and index. + */ + IMPORT_C TUint16 AsTUint16(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Retrieves a TUint32 from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + @param aSize how many bytes to get. + + @return Value at offset. + */ + IMPORT_C TUint32 AsTUint32(TInt aOffset, TUint8 aSize) const; + + /** + Retrieves a TUint32 from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TUint32s of this event. + @param aSize how many bytes to get. + + @return Value at offset and index. + */ + IMPORT_C TUint32 AsTUint32(TInt aOffset, TInt aArrayBlockSize, TInt aIndex, TUint8 aSize) const; + + /** + Retrieves a TUint64 from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TUint64 AsTUint64(TInt aOffset) const; + + /** + Retrieves a TUint64 from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TUint64s of this event. + + @return Value at offset and index. + */ + IMPORT_C TUint64 AsTUint64(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Retrieves a TDesC8& from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TPtrC8 AsString(TInt aOffset) const; + + /** + Retrieves a Null terminated TDesC8& from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TPtrC8 AsNullTerminatedString(TInt aOffset) const; + + /** + Retrieves a Null terminated Bluetooth Device Name from a specified event data descriptor. + + @return Bluetooth Device Name at offset. + */ + IMPORT_C TPtrC8 AsBluetoothDeviceName(TInt aOffset) const; + + /** + Retrieves a TBTDevAddr from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TBTDevAddr AsDevAddr(TInt aOffset) const; + + /** + Retrieves a TBTDevAddr from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TBTDevAddrs of this event. + + @return Value at offset and index. + */ + IMPORT_C TBTDevAddr AsDevAddr(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Retrieves a TBTDevAddr from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TBluetoothSimplePairingHash AsSimplePairingHash(TInt aOffset) const; + + /** + Retrieves a TBTDevAddr from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TBluetoothSimplePairingRandomizer AsSimplePairingRandomizer(TInt aOffset) const; + + + /** + Retrieves a TBTLinkKey from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C TBTLinkKey AsLinkKey(TInt aOffset) const; + + /** + Retrieves a TBTLinkKey from specified offset and index within the event data descriptor. + Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of TBTLinkKeys of this event. + + @return Value at offset and index. + */ + IMPORT_C TBTLinkKey AsLinkKey(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Retrieves a THCIConnectionHandle from specified offset within the event data descriptor. + @param aOffset offset of value in event data. + + @return Value at offset. + */ + IMPORT_C THCIConnectionHandle AsConnectionHandle(TInt aOffset) const; + + /** + Retrieves a THCIConnectionHandle from specified offset and index within the event data + descriptor. Is intended to be used with events returning variable number of parameters. + + @param aOffset offset of value in event data. + @param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. + @param aIndex index into the array of THCIConnectionHandle of this event. + + @return Value at offset and index. + */ + IMPORT_C THCIConnectionHandle AsConnectionHandle(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const; + + /** + Writes an Event code to the event data descriptor. + ALL the write functions are intended to be used ONE AFTER ANOTHER in the order the objects + need to be written to the event data. Thus: + PutEventCode(n); + PutTUint8(int1); + PutTUint16(int2); + will product an event string n int1 int2 + It is NOT possible to write these into the string in the order n, int2, int1 and get them to produce the + event string shown. This is very similar to the way you construct commands. + + @param aValue the event code to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutEventCode(THCIEventCode aValue, TDes8& aEventData); + + /** + Writes a TInt8 to the event data descriptor. + + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutTInt8(TInt8 aValue, TDes8& aEventData); + + /** + Writes a TUint8 to the event data descriptor. + + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutTUint8(TUint8 aValue, TDes8& aEventData); + + /** + Writes a TUint16 to the event data descriptor. + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutTUint16(TUint16 aValue, TDes8& aEventData); + + /** + Writes a TUint32 to the event data descriptor. + @param aValue the value to write + @param aSize how many bytes to write. + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutTUint32(TUint32 aValue, TUint8 aSize, TDes8& aEventData); + + /** + Writes a TUint64 to the event data descriptor. + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutTUint64(TUint64 aValue, TDes8& aEventData); + + /** + Writes a TDesC8& to the event data descriptor. + @param aString the string to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutString(const TDesC8& aString, TDes8& aEventData); + + /** + Writes a TDesC8& to the event data descriptor padding with '\0' up to the required length. + @param aString the string to write + @param aRequiredLength the required length the writen string is to be + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutPaddedString(const TDesC8& aString, TInt aRequiredLength, TDes8& aEventData); + + /** + Writes a TBTDevAddr to the event data descriptor. + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutDevAddr(const TBTDevAddr& aBdaddr, TDes8& aEventData); + + /** + Writes a TBTSimplePairingHashC to the event data descriptor. + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutSimplePairingHash(const TBluetoothSimplePairingHash& aHash, TDes8& aEventData); + + /** + Writes a TBTSimplePairingRandomizerR to the event data descriptor. + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutSimplePairingRandomizer(const TBluetoothSimplePairingRandomizer& aRandomizer, TDes8& aEventData); + + + /** + Writes a TBTLinkKey to the event data descriptor. + @param aValue the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutLinkKey(const TBTLinkKey aValue, TDes8& aEventData); + + /** + Writes a THCIConnectionHandle to the event data descriptor. + @param aConnectionHandle the value to write + @param aEventData modifiable descriptor buffer where the faked event is being created + */ + void PutConnectionHandle(THCIConnectionHandle aConnectionHandle, TDes8& aEventData); + +private: + THCIEventBase(const THCIEventBase&); + + // Helper for CreateAndSendEvent + static TInt CreateAndSendCommandCompleteEvent(const TDesC8& aEventData, + MHCICommandEventObserver&); + +public: + // Event layout constants - lengths/offsets of fields that occur at the start of all the events + const static TUint KEventCodeOffset = 0; + const static TUint KEventCodeLength = 1; + const static TUint KTotalParameterLengthOffset = KEventCodeLength; + const static TUint KTotalParameterLengthLength = 1; + const static TUint KEventCommonFieldsLength = KEventCodeLength + KTotalParameterLengthLength; + +protected: + THCIErrorCode iErrorCode; + TPtrC8 iEventData; + +private: + // Reserved for extending the class while maintaining binary compatability. + TUint32 iReserved1; + TUint32 iReserved2; + }; + +#endif // THCIEVENTBASE_H