1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 #ifndef PVMF_EVENT_HANDLING_H_INCLUDED 19 #define PVMF_EVENT_HANDLING_H_INCLUDED 20 21 22 #include "oscl_base.h" 23 #include "oscl_mem_auto_ptr.h" 24 #include "oscl_mem_basic_functions.h" 25 #include "pvmf_return_codes.h" 26 #include "pv_interface.h" 27 28 29 /** 30 Identifies the specific observer session 31 **/ 32 typedef int32 PVMFSessionId; 33 34 /** 35 Identifies the specific API/command that was invoked 36 **/ 37 typedef int32 PVMFCommandType; 38 39 /** 40 A unique command id identifying an invocation of any command 41 **/ 42 typedef int32 PVMFCommandId; 43 44 typedef enum 45 { 46 PVMFCmdRespEvent, 47 PVMFErrorEvent, 48 PVMFInfoEvent, 49 PVMFEventLast 50 } PVMFEventCategory; 51 52 /** 53 Identifies the type of event (error & informational) 54 **/ 55 typedef int32 PVMFEventType; 56 57 58 /** 59 The base class for PVMF callback events 60 **/ 61 class PVMFEventBase 62 { 63 public: 64 PVMFEventBase() {} 65 66 virtual ~PVMFEventBase() {}; 67 68 /** 69 * @return the event's category. 70 */ 71 OSCL_IMPORT_REF virtual PVMFEventCategory IsA() const = 0; 72 }; 73 74 /** 75 * PVMFCmdResp Class 76 * 77 * PVMFCmdResp class is used to pass completion status on previously issued 78 * commands 79 **/ 80 class OSCL_IMPORT_REF PVMFCmdResp : public PVMFEventBase 81 { 82 public: 83 /** 84 * Constructor for PVMFCmdResp 85 */ 86 PVMFCmdResp(PVMFCommandId aId, 87 const OsclAny* aContext, 88 PVMFStatus aStatus, 89 OsclAny* aEventData = NULL): 90 iId(aId), 91 iContext(aContext), 92 iStatus(aStatus), 93 iEventExtInterface(NULL), 94 iEventData(aEventData) 95 { 96 iEventDataLengthAvailable = false; 97 iEventDataLength = 0; 98 } 99 100 /** 101 * Constructor for PVMFCmdResp 102 */ 103 PVMFCmdResp(PVMFCommandId aId, 104 const OsclAny* aContext, 105 PVMFStatus aStatus, 106 PVInterface* aEventExtInterface): 107 iId(aId), 108 iContext(aContext), 109 iStatus(aStatus), 110 iEventExtInterface(aEventExtInterface), 111 iEventData(NULL) 112 { 113 iEventDataLengthAvailable = false; 114 iEventDataLength = 0; 115 } 116 117 /** 118 * Constructor for PVMFCmdResp 119 */ 120 PVMFCmdResp(PVMFCommandId aId, 121 const OsclAny* aContext, 122 PVMFStatus aStatus, 123 PVInterface* aEventExtInterface, 124 OsclAny* aEventData): 125 iId(aId), 126 iContext(aContext), 127 iStatus(aStatus), 128 iEventExtInterface(aEventExtInterface), 129 iEventData(aEventData) 130 { 131 iEventDataLengthAvailable = false; 132 iEventDataLength = 0; 133 } 134 135 virtual ~PVMFCmdResp() {} 136 137 OSCL_IMPORT_REF virtual PVMFEventCategory IsA() const; 138 139 /** 140 * @return Returns the unique ID associated with a command of this type. 141 */ 142 PVMFCommandId GetCmdId()const 143 { 144 return iId; 145 } 146 147 /** 148 * @return Returns the opaque data that was passed in with the command. 149 */ 150 const OsclAny* GetContext()const 151 { 152 return iContext; 153 } 154 155 /** 156 * @return Returns the completion status of the command 157 */ 158 PVMFStatus GetCmdStatus()const 159 { 160 return iStatus; 161 } 162 163 /** 164 * This method is going to be deprecated soon. We intend to remove 165 * the opaque event data and use PVInterface pointer if needed to 166 * retrieve more information regarding command completion 167 * 168 * 169 * @return Returns additional data asociated with the command/event. This is to be interpreted 170 based on the type and the return status 171 */ 172 OsclAny* GetEventData()const 173 { 174 return iEventData; 175 } 176 177 /** 178 * This method is going to be deprecated soon. We intend to remove 179 * the opaque event data and use PVInterface pointer if needed to 180 * retrieve more information regarding command completion.Therefore, 181 * with the removal of event data, setting length of event data wont be of any significance either. 182 * 183 * @param1 - (uint32) length of event data in bytes. 184 * @return PVMFSuccess, if length of event data can be set. 185 PVMFFailure, if length of event data can't be set. 186 */ 187 PVMFStatus SetEventDataLen(uint32 aEventDataLength) 188 { 189 PVMFStatus status = PVMFFailure; 190 if (iEventData) 191 { 192 iEventDataLengthAvailable = true; 193 iEventDataLength = aEventDataLength; 194 status = PVMFSuccess; 195 } 196 return status; 197 } 198 199 /** 200 * This method is going to be deprecated soon. We intend to remove 201 * the opaque event data and use PVInterface pointer if needed to 202 * retrieve more information regarding command completion.Therefore, 203 * with the removal of event data, length if event data wont be needed either. 204 * 205 * @param1 - bool& aEventDataLenAvailable 206 * false - length of event data(in bytes) is not available 207 * true - length of event data(in bytes) is available 208 * @param2 - uint32& aEventDataLength 209 * length of eventdata in bytes 210 */ 211 void GetEventDataLen(bool& aEventDataLenAvailable, uint32& aEventDataLength)const 212 { 213 aEventDataLenAvailable = false; 214 aEventDataLength = 0; 215 if (iEventDataLengthAvailable) 216 { 217 aEventDataLenAvailable = true; 218 aEventDataLength = iEventDataLength; 219 } 220 } 221 222 /** 223 * @return Returns the eventinfointerface 224 */ 225 PVInterface* GetEventExtensionInterface() const 226 { 227 return iEventExtInterface; 228 } 229 230 protected: 231 PVMFCommandId iId; 232 const OsclAny* iContext; 233 PVMFStatus iStatus; 234 PVInterface* iEventExtInterface; 235 /** 236 * We STRONGLY DISCOURAGE use of this. This field will be deprecated 237 * soon. 238 */ 239 OsclAny* iEventData; 240 bool iEventDataLengthAvailable; 241 uint32 iEventDataLength; 242 }; 243 244 245 /** 246 * PVMFAsyncEvent Class 247 * 248 * PVMFAsyncEvent is the base class used to pass unsolicited error and informational 249 * indications to the user. Additional information can be tagged based on the specific 250 * event 251 **/ 252 #define PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE 16 253 class OSCL_IMPORT_REF PVMFAsyncEvent : public PVMFEventBase 254 { 255 public: 256 PVMFAsyncEvent(PVMFEventCategory aEventCategory, 257 PVMFEventType aEventType, 258 OsclAny* aContext, 259 OsclAny* aEventData) : 260 iEventCategory(aEventCategory) 261 , iEventType(aEventType) 262 , iEventExtInterface(NULL) 263 , iLocalBufferSize(0) 264 , iContext(aContext) 265 , iEventData(aEventData) 266 { 267 oscl_memset(iLocalBuffer, 0, PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE); 268 iEventDataLengthAvailable = false; 269 iEventDataLength = 0; 270 } 271 272 PVMFAsyncEvent(PVMFEventCategory aEventCategory, 273 PVMFEventType aEventType, 274 OsclAny* aContext, 275 OsclAny* aEventData, 276 const void* aLocalBuffer, 277 const size_t aLocalBufferSize) : 278 iEventCategory(aEventCategory) 279 , iEventType(aEventType) 280 , iEventExtInterface(NULL) 281 , iLocalBufferSize(aLocalBufferSize) 282 , iContext(aContext) 283 , iEventData(aEventData) 284 { 285 if (aLocalBuffer) 286 { 287 OSCL_ASSERT(iLocalBufferSize <= PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE); 288 if (iLocalBufferSize > PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE) 289 { 290 iLocalBufferSize = PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE; 291 } 292 293 oscl_memcpy(iLocalBuffer, aLocalBuffer, iLocalBufferSize); 294 } 295 iEventDataLengthAvailable = false; 296 iEventDataLength = 0; 297 } 298 299 PVMFAsyncEvent(PVMFEventCategory aEventCategory, 300 PVMFEventType aEventType, 301 OsclAny* aContext, 302 PVInterface* aEventExtInterface, 303 OsclAny* aEventData) : 304 iEventCategory(aEventCategory) 305 , iEventType(aEventType) 306 , iEventExtInterface(aEventExtInterface) 307 , iLocalBufferSize(0) 308 , iContext(aContext) 309 , iEventData(aEventData) 310 { 311 oscl_memset(iLocalBuffer, 0, PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE); 312 iEventDataLengthAvailable = false; 313 iEventDataLength = 0; 314 } 315 316 PVMFAsyncEvent(PVMFEventCategory aEventCategory, 317 PVMFEventType aEventType, 318 OsclAny* aContext, 319 PVInterface* aEventExtInterface, 320 OsclAny* aEventData, 321 const void* aLocalBuffer, 322 const size_t aLocalBufferSize) : 323 iEventCategory(aEventCategory) 324 , iEventType(aEventType) 325 , iEventExtInterface(aEventExtInterface) 326 , iLocalBufferSize(aLocalBufferSize) 327 , iContext(aContext) 328 , iEventData(aEventData) 329 { 330 if (aLocalBuffer) 331 { 332 OSCL_ASSERT(iLocalBufferSize <= PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE); 333 if (iLocalBufferSize > PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE) 334 { 335 iLocalBufferSize = PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE; 336 } 337 338 oscl_memcpy(iLocalBuffer, aLocalBuffer, iLocalBufferSize); 339 } 340 iEventDataLengthAvailable = false; 341 iEventDataLength = 0; 342 } 343 344 virtual ~PVMFAsyncEvent() {} 345 346 OSCL_IMPORT_REF virtual PVMFEventCategory IsA() const; 347 348 /** 349 * @return Returns the unique type identifier of the event. 350 */ 351 PVMFEventType GetEventType()const 352 { 353 return iEventType; 354 } 355 356 /** 357 * This method is going to be deprecated soon. We intend to remove 358 * the opaque event data and use PVInterface pointer if needed to 359 * retrieve more information regarding command completion 360 * 361 * 362 * @return Returns additional data asociated with the event. 363 * This is to be interpreted 364 * based on the type and the return status 365 */ 366 OsclAny* GetEventData() const 367 { 368 return iEventData; 369 } 370 371 /** 372 * This method is going to be deprecated soon. We intend to remove 373 * the opaque event data and use PVInterface pointer if needed to 374 * retrieve more information regarding command completion.Therefore, 375 * with the removal of event data, setting length of event data wont be of any significance either. 376 * 377 * @param1 - (uint32) length of event data in bytes. 378 * @return PVMFSuccess, if length of event data can be set. 379 PVMFFailure, if length of event data can't be set. 380 */ 381 PVMFStatus SetEventDataLen(uint32 aEventDataLength) 382 { 383 PVMFStatus status = PVMFFailure; 384 if (iEventData) 385 { 386 iEventDataLengthAvailable = true; 387 iEventDataLength = aEventDataLength; 388 status = PVMFSuccess; 389 } 390 return status; 391 } 392 393 /** 394 * This method is going to be deprecated soon. We intend to remove 395 * the opaque event data and use PVInterface pointer if needed to 396 * retrieve more information regarding command completion.Therefore, 397 * with the removal of event data, length if event data wont be needed either. 398 * 399 * @param1 - bool& aEventDataLenAvailable 400 * false - length of event data(in bytes) is not available 401 * true - length of event data(in bytes) is available 402 * @param2 - uint32& aEventDataLength 403 * length of eventdata in bytes 404 */ 405 void GetEventDataLen(bool& aEventDataLenAvailable, uint32& aEventDataLength)const 406 { 407 aEventDataLenAvailable = false; 408 aEventDataLength = 0; 409 if (iEventDataLengthAvailable) 410 { 411 aEventDataLenAvailable = true; 412 aEventDataLength = iEventDataLength; 413 } 414 } 415 416 /** 417 * @return Returns the size of the local data asociated with the event. 418 */ 419 size_t GetLocalBufferSize() const 420 { 421 return iLocalBufferSize; 422 } 423 424 /** 425 * @return Returns the local data asociated with the event. 426 * TODO: This is a const method returning a non const ref to some 427 * internal array. 428 */ 429 uint8* GetLocalBuffer() const 430 { 431 return (uint8*)iLocalBuffer; 432 } 433 434 /** 435 * @return Returns the opaque data associated with the callback type. 436 */ 437 const OsclAny* GetContext()const 438 { 439 return iContext; 440 } 441 442 /** 443 * @return Returns the eventinfointerface 444 */ 445 PVInterface* GetEventExtensionInterface() const 446 { 447 return iEventExtInterface; 448 } 449 450 protected: 451 PVMFEventCategory iEventCategory; 452 PVMFEventType iEventType; 453 PVInterface* iEventExtInterface; 454 uint8 iLocalBuffer[PVMF_ASYNC_EVENT_LOCAL_BUF_SIZE]; 455 size_t iLocalBufferSize; 456 OsclAny* iContext; 457 /** 458 * We STRONGLY DISCOURAGE use of this. This field will be deprecated 459 * soon. 460 */ 461 OsclAny* iEventData; 462 bool iEventDataLengthAvailable; 463 uint32 iEventDataLength; 464 }; 465 466 #endif // PVMF_EVENT_HANDLING_H_INCLUDED 467
