1 // Copyright (c) 2006-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 "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @released

    20 */

    21 

    22 #ifndef THCIEVENTBASE_H

    23 #define THCIEVENTBASE_H

    24 

    25 #include <e32def.h>

    26 #include <bluetooth/hci/hcievents.h>

    27 #include <bluetooth/hci/hcierrors.h>

    28 #include <bluetooth/hci/hcitypes.h>

    29 #include <bttypespartner.h>

    30 

    31 class MHCICommandEventObserver;

    32 class MHCIDataEventObserver;

    33 

    34 /**

    35 Represents the common data for a HCI event.

    36 

    37 All of the event classes have been design to be used in a synchronous manner. All data is used by 

    38 reference and hence any other object that requires persistence of the event parameters should make

    39 their own copy of them.

    40 */

    41 NONSHARABLE_CLASS(THCIEventBase)

    42 	{

    43 public:

    44 	/**

    45 	Getter for the event code.

    46 	@return The event code that describes the event.

    47 	*/

    48 	IMPORT_C THCIEventCode EventCode() const;

    49 

    50 	/**

    51 	Getter for the error code.

    52 

    53 	Although this error code is not defined for all events in the HCI specification, the error code

    54 	is in the base class so that the command queue can use the event error in its decisions without casting

    55 	to a derived class.

    56 	Those events that do not contain an error code in the specification should return with THCIErrorCode::EOK.

    57 

    58 	@return The error code contained in the event.

    59 	*/

    60 	IMPORT_C THCIErrorCode ErrorCode() const;

    61 

    62 	/**

    63 	Static factory and despatcher method.

    64 	

    65 	This method creates an object of the appropriate derived type according to the event code

    66 	in the event data supplied. Depending upon the type of event, it is then passed to the

    67 	supplied Command Event observer or Data Event observer as appropriate. The event object is

    68 	created on the stack and is therefore destroyed before CreateAndSendEvent returns.

    69 	

    70 	@param aEventData The data packet containing the event

    71 	@param aEventObserver The observer for handling command-related events

    72 	@param aDataEventObserver The observer for handling data-related events

    73 	@param aObserver Additional observer parameter to allow the licensee extra future flexibility

    74 	*/

    75 	IMPORT_C static	TInt CreateAndSendEvent(const TDesC8& aEventData, MHCICommandEventObserver& aEventObserver, MHCIDataEventObserver& aDataEventObserver, TAny* aObserver=NULL);

    76 	

    77 protected:

    78 	/**

    79 	Constructor used for creating a faked event

    80 	@param aEventCode The event code for the event

    81 	@param aParameterTotalLength The total length of the event parameters

    82 	@param aEventData Empty buffer where the faked event data will be built.

    83 	Every event starts with a one-byte event code and one-byte parameter total length field, so

    84 	these are managed in this base class. The data after this is event specific and has length

    85 	equal to Parameter Total Length. It is the responsibility of the derived class faking

    86 	constructor to populate the rest of the aEventData buffer and then to set the member

    87 	variable iEventData to reference this buffer when it is complete.

    88 	Note that the aEventData buffer must persist as long as the object itself. It must be

    89 	empty intially, and must be big enough to hold all the data for the given event type.

    90 	*/

    91 	THCIEventBase(THCIEventCode aEventCode, TUint8 aParameterTotalLength, TDes8& aEventData);	

    92 	/**

    93 	Normal constructor. This is used to create an event object to wrap event data received from the Controller

    94 	@param aEventData Buffer holding event data received from the Controller

    95 	*/

    96 	IMPORT_C THCIEventBase(const TDesC8& aEventData);	

    97 

    98 	/**

    99 	Retrieves a TInt8 from specified offset within the event data descriptor.

   100 	@param aOffset offset of value in event data.

   101 

   102 	@return Value at offset.

   103 	*/

   104 	IMPORT_C TInt8 AsTInt8(TInt aOffset) const;

   105 

   106 	/**

   107 	Retrieves a TInt8 from specified offset and index within the event data descriptor.

   108 	Is intended to be used with events returning variable number of parameters.

   109 	

   110 	@param aOffset offset of value in event data.

   111 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   112 	@param aIndex index into the array of TUint8s of this event.

   113 

   114 	@return Value at offset and index.

   115 	*/

   116 	IMPORT_C TInt8 AsTInt8(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   117 

   118 	/**

   119 	Retrieves a TUint8 from specified offset within the event data descriptor.

   120 	@param aOffset offset of value in event data.

   121 

   122 	@return Value at offset.

   123 	*/

   124 	IMPORT_C TUint8 AsTUint8(TInt aOffset) const;

   125 

   126 	/**

   127 	Retrieves a TUint8 from specified offset and index within the event data descriptor.

   128 	Is intended to be used with events returning variable number of parameters.

   129 	

   130 	@param aOffset offset of value in event data.

   131 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   132 	@param aIndex index into the array of TUint8s of this event.

   133 

   134 	@return Value at offset and index.

   135 	*/

   136 	IMPORT_C TUint8 AsTUint8(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   137 

   138 	/**

   139 	Retrieves a TUint16 from specified offset within the event data descriptor.

   140 	@param aOffset offset of value in event data.

   141 

   142 	@return Value at offset.

   143 	*/

   144 	IMPORT_C TUint16 AsTUint16(TInt aOffset) const;

   145 

   146 	/**

   147 	Retrieves a TUint16 from specified offset and index within the event data descriptor.

   148 	Is intended to be used with events returning variable number of parameters.

   149 	

   150 	@param aOffset offset of value in event data.

   151 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   152 	@param aIndex index into the array of TUint16s of this event.

   153 

   154 	@return Value at offset and index.

   155 	*/

   156 	IMPORT_C TUint16 AsTUint16(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   157 

   158 	/**

   159 	Retrieves a TUint32 from specified offset within the event data descriptor.

   160 	@param aOffset offset of value in event data.

   161 	@param aSize how many bytes to get.

   162 

   163 	@return Value at offset.

   164 	*/

   165 	IMPORT_C TUint32 AsTUint32(TInt aOffset, TUint8 aSize) const;

   166 

   167 	/**

   168 	Retrieves a TUint32 from specified offset and index within the event data descriptor.

   169 	Is intended to be used with events returning variable number of parameters.

   170 	

   171 	@param aOffset offset of value in event data.

   172 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   173 	@param aIndex index into the array of TUint32s of this event.

   174 	@param aSize how many bytes to get.

   175 

   176 	@return Value at offset and index.

   177 	*/

   178 	IMPORT_C TUint32 AsTUint32(TInt aOffset, TInt aArrayBlockSize, TInt aIndex, TUint8 aSize) const;

   179 

   180 	/**

   181 	Retrieves a TUint64 from specified offset within the event data descriptor.

   182 	@param aOffset offset of value in event data.

   183 

   184 	@return Value at offset.

   185 	*/

   186 	IMPORT_C TUint64 AsTUint64(TInt aOffset) const;

   187 

   188 	/**

   189 	Retrieves a TUint64 from specified offset and index within the event data descriptor.

   190 	Is intended to be used with events returning variable number of parameters.

   191 	

   192 	@param aOffset offset of value in event data.

   193 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   194 	@param aIndex index into the array of TUint64s of this event.

   195 

   196 	@return Value at offset and index.

   197 	*/

   198 	IMPORT_C TUint64 AsTUint64(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   199 

   200 	/**

   201 	Retrieves a TDesC8& from specified offset within the event data descriptor.

   202 	@param aOffset offset of value in event data.

   203 

   204 	@return Value at offset.

   205 	*/

   206 	IMPORT_C TPtrC8 AsString(TInt aOffset) const;

   207 	

   208 	/**

   209 	Retrieves a Null terminated TDesC8& from specified offset within the event data descriptor.

   210 	@param aOffset offset of value in event data.

   211 

   212 	@return Value at offset.

   213 	*/

   214 	IMPORT_C TPtrC8 AsNullTerminatedString(TInt aOffset) const;

   215 

   216 	/**

   217 	Retrieves a Null terminated Bluetooth Device Name from a specified event data descriptor.

   218 

   219 	@return Bluetooth Device Name at offset.

   220 	*/

   221 	IMPORT_C TPtrC8 AsBluetoothDeviceName(TInt aOffset) const;

   222 	

   223 	/**

   224 	Retrieves a TBTDevAddr from specified offset within the event data descriptor.

   225 	@param aOffset offset of value in event data.

   226 

   227 	@return Value at offset.

   228 	*/

   229 	IMPORT_C TBTDevAddr AsDevAddr(TInt aOffset) const;

   230 

   231 	/**

   232 	Retrieves a TBTDevAddr from specified offset and index within the event data descriptor.

   233 	Is intended to be used with events returning variable number of parameters.

   234 	

   235 	@param aOffset offset of value in event data.

   236 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   237 	@param aIndex index into the array of TBTDevAddrs of this event.

   238 

   239 	@return Value at offset and index.

   240 	*/

   241 	IMPORT_C TBTDevAddr AsDevAddr(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   242 

   243 	/**

   244 	Retrieves a TBTDevAddr from specified offset within the event data descriptor.

   245 	@param aOffset offset of value in event data.

   246 

   247 	@return Value at offset.

   248 	*/

   249 	IMPORT_C TBluetoothSimplePairingHash AsSimplePairingHash(TInt aOffset) const;

   250 

   251 	/**

   252 	Retrieves a TBTDevAddr from specified offset within the event data descriptor.

   253 	@param aOffset offset of value in event data.

   254 

   255 	@return Value at offset.

   256 	*/

   257 	IMPORT_C TBluetoothSimplePairingRandomizer AsSimplePairingRandomizer(TInt aOffset) const;

   258 

   259 	

   260 	/**

   261 	Retrieves a TBTLinkKey from specified offset within the event data descriptor.

   262 	@param aOffset offset of value in event data.

   263 

   264 	@return Value at offset.

   265 	*/

   266 	IMPORT_C TBTLinkKey AsLinkKey(TInt aOffset) const;

   267 

   268 	/**

   269 	Retrieves a TBTLinkKey from specified offset and index within the event data descriptor.

   270 	Is intended to be used with events returning variable number of parameters.

   271 	

   272 	@param aOffset offset of value in event data.

   273 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry. 

   274 	@param aIndex index into the array of TBTLinkKeys of this event.

   275 

   276 	@return Value at offset and index.

   277 	*/

   278 	IMPORT_C TBTLinkKey AsLinkKey(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   279 	

   280 	/**

   281 	Retrieves a THCIConnectionHandle from specified offset within the event data descriptor.

   282 	@param aOffset offset of value in event data.

   283 

   284 	@return Value at offset.

   285 	*/

   286 	IMPORT_C THCIConnectionHandle AsConnectionHandle(TInt aOffset) const;

   287 	

   288 	/**

   289 	Retrieves a THCIConnectionHandle from specified offset and index within the event data 

   290 	descriptor. Is intended to be used with events returning variable number of parameters.

   291 

   292 	@param aOffset offset of value in event data.

   293 	@param aArrayBlockSize size of one array entry, i.e. all parameters for an array entry.

   294 	@param aIndex index into the array of THCIConnectionHandle of this event.

   295 

   296 	@return Value at offset and index.

   297 	*/

   298 	IMPORT_C THCIConnectionHandle AsConnectionHandle(TInt aOffset, TInt aArrayBlockSize, TInt aIndex) const;

   299 

   300 	/**

   301 	Writes an Event code to the event data descriptor.

   302 	ALL the write functions are intended to be used ONE AFTER ANOTHER in the order the objects

   303 	need to be written to the event data. Thus:

   304 		PutEventCode(n);

   305 		PutTUint8(int1);

   306 		PutTUint16(int2);

   307 	will product an event string n int1 int2

   308 	It is NOT possible to write these into the string in the order n, int2, int1 and get them to produce the 

   309 	event string shown. This is very similar to the way you construct commands.

   310 	

   311 	@param aValue the event code to write

   312 	@param aEventData modifiable descriptor buffer where the faked event is being created

   313 	*/

   314 	void PutEventCode(THCIEventCode aValue, TDes8& aEventData);

   315 

   316 	/**

   317 	Writes a TInt8 to the event data descriptor.

   318 	

   319 	@param aValue the value to write

   320 	@param aEventData modifiable descriptor buffer where the faked event is being created

   321 	*/

   322 	void PutTInt8(TInt8 aValue, TDes8& aEventData);

   323 

   324 	/**

   325 	Writes a TUint8 to the event data descriptor.

   326 	

   327 	@param aValue the value to write

   328 	@param aEventData modifiable descriptor buffer where the faked event is being created

   329 	*/

   330 	void PutTUint8(TUint8 aValue, TDes8& aEventData);

   331 

   332 	/**

   333 	Writes a TUint16 to the event data descriptor.

   334 	@param aValue the value to write

   335 	@param aEventData modifiable descriptor buffer where the faked event is being created

   336 	*/

   337 	void PutTUint16(TUint16 aValue, TDes8& aEventData);

   338 

   339 	/**

   340 	Writes a TUint32 to the event data descriptor.

   341 	@param aValue the value to write

   342 	@param aSize how many bytes to write.

   343 	@param aEventData modifiable descriptor buffer where the faked event is being created

   344 	*/

   345 	void PutTUint32(TUint32 aValue, TUint8 aSize, TDes8& aEventData);

   346 

   347 	/**

   348 	Writes a TUint64 to the event data descriptor.

   349 	@param aValue the value to write

   350 	@param aEventData modifiable descriptor buffer where the faked event is being created

   351 	*/

   352 	void PutTUint64(TUint64 aValue, TDes8& aEventData);

   353 

   354 	/**

   355 	Writes a TDesC8& to the event data descriptor.

   356 	@param aString the string to write

   357 	@param aEventData modifiable descriptor buffer where the faked event is being created

   358 	*/

   359 	void PutString(const TDesC8& aString, TDes8& aEventData);

   360 

   361 	/**

   362 	Writes a TDesC8& to the event data descriptor padding with '\0' up to the required length.

   363 	@param aString the string to write

   364 	@param aRequiredLength the required length the writen string is to be

   365 	@param aEventData modifiable descriptor buffer where the faked event is being created

   366 	*/

   367 	void PutPaddedString(const TDesC8& aString, TInt aRequiredLength, TDes8& aEventData);

   368 

   369 	/**

   370 	Writes a TBTDevAddr to the event data descriptor.

   371 	@param aValue the value to write

   372 	@param aEventData modifiable descriptor buffer where the faked event is being created

   373 	*/

   374 	void PutDevAddr(const TBTDevAddr& aBdaddr, TDes8& aEventData);

   375 	

   376 	/**

   377 	Writes a TBTSimplePairingHashC to the event data descriptor.

   378 	@param aValue the value to write

   379 	@param aEventData modifiable descriptor buffer where the faked event is being created

   380 	*/

   381 	void PutSimplePairingHash(const TBluetoothSimplePairingHash& aHash, TDes8& aEventData);

   382 

   383 	/**

   384 	Writes a TBTSimplePairingRandomizerR to the event data descriptor.

   385 	@param aValue the value to write

   386 	@param aEventData modifiable descriptor buffer where the faked event is being created

   387 	*/

   388 	void PutSimplePairingRandomizer(const TBluetoothSimplePairingRandomizer& aRandomizer, TDes8& aEventData);

   389 

   390 	

   391 	/**

   392 	Writes a TBTLinkKey to the event data descriptor.

   393 	@param aValue the value to write

   394 	@param aEventData modifiable descriptor buffer where the faked event is being created

   395 	*/

   396 	void PutLinkKey(const TBTLinkKey aValue, TDes8& aEventData);

   397 

   398 	/**

   399 	Writes a THCIConnectionHandle to the event data descriptor.

   400 	@param aConnectionHandle the value to write

   401 	@param aEventData modifiable descriptor buffer where the faked event is being created

   402 	*/

   403 	void PutConnectionHandle(THCIConnectionHandle aConnectionHandle, TDes8& aEventData);

   404 

   405 private:

   406 	THCIEventBase(const THCIEventBase&);

   407 

   408 	// Helper for CreateAndSendEvent

   409 	static TInt CreateAndSendCommandCompleteEvent(const TDesC8& aEventData,

   410 												  MHCICommandEventObserver&);

   411 

   412 public:

   413 	// Event layout constants - lengths/offsets of fields that occur at the start of all the events

   414 	const static TUint KEventCodeOffset = 0;

   415 	const static TUint KEventCodeLength = 1;

   416 	const static TUint KTotalParameterLengthOffset = KEventCodeLength;

   417 	const static TUint KTotalParameterLengthLength = 1;

   418 	const static TUint KEventCommonFieldsLength = KEventCodeLength + KTotalParameterLengthLength;

   419 

   420 protected:

   421 	THCIErrorCode iErrorCode;

   422 	TPtrC8 iEventData;

   423 

   424 private:

   425 	// Reserved for extending the class while maintaining binary compatability.

   426 	TUint32 iReserved1;

   427 	TUint32 iReserved2;

   428 	};

   429 

   430 #endif // THCIEVENTBASE_H