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 /** 19 * @file pvmf_media_clock.h 20 * @brief Provides a time clock that can be paused and resumed, 21 * set the start time, adjusted based on outside source feedback, 22 * and accepts user specified source for the free running clock. 23 * 24 */ 25 26 #ifndef PVMF_MEDIA_CLOCK_H_INCLUDED 27 #define PVMF_MEDIA_CLOCK_H_INCLUDED 28 29 #ifndef OSCL_BASE_H_INCLUDED 30 #include "oscl_base.h" 31 #endif 32 33 #ifndef OSCL_TICKCOUNT_H_INCLUDED 34 #include "oscl_tickcount.h" 35 #endif 36 37 #ifndef OSCL_INT64_UTILS_H_INCLUDED 38 #include "oscl_int64_utils.h" 39 #endif 40 41 #ifndef OSCL_VECTOR_H_INCLUDED 42 #include "oscl_vector.h" 43 #endif 44 45 #ifndef OSCL_MEM_H_INCLUDED 46 #include "oscl_mem.h" 47 #endif 48 49 #ifndef PVMF_RETURN_CODES_H_INCLUDED 50 #include "pvmf_return_codes.h" 51 #endif 52 53 #ifndef PVMF_TIMESTAMP_H_INCLUDED 54 #include "pvmf_timestamp.h" 55 #endif 56 57 #ifndef OSCL_PRIQUEUE_H_INCLUDED 58 #include "oscl_priqueue.h" 59 #endif 60 61 #ifndef OSCL_SCHEDULER_AO_H_INCLUDED 62 #include "oscl_scheduler_ao.h" 63 #endif 64 65 #ifndef PV_INTERFACE_H_INCLUDED 66 #include "pv_interface.h" 67 #endif 68 69 #ifndef TIME_COMPARISON_UTILS_H_INCLUDED 70 #include "time_comparison_utils.h" 71 #endif 72 73 #ifndef PVLOGGER_H_INCLUDED 74 #include "pvlogger.h" 75 #endif 76 77 #define MSECS_IN_30_MINS 0x1B7740 78 79 80 #define PVMFMediaClockControlInterfaceUuid PVUuid(0xca20319a,0x33f9,0x484f,0x8d,0x1c,0xa5,0x1e,0x23,0x4c,0xe6,0x03) 81 #define PVMFMediaClockAccessInterfaceUuid PVUuid(0xca20319a,0x33f9,0x484f,0x8d,0x1c,0xa5,0x1e,0x23,0x4c,0xe6,0x04) 82 #define PVMFMediaClockNPTClockPositionAccessInterfaceUuid PVUuid(0xca20319a,0x33f9,0x484f,0x8d,0x1c,0xa5,0x1e,0x23,0x4c,0xe6,0x05) 83 84 //playback rate unit is milli-percent of real time 85 #define REALTIME_PLAYBACK_RATE 100000 86 87 class PVMFMediaClock; 88 89 90 /* 91 * Enum for the time units used in OSCL Media Clock 92 */ 93 enum PVMFMediaClock_TimeUnits 94 { 95 PVMF_MEDIA_CLOCK_USEC = 0, 96 PVMF_MEDIA_CLOCK_MSEC = 1, 97 PVMF_MEDIA_CLOCK_SEC = 2, 98 PVMF_MEDIA_CLOCK_MIN = 3, 99 PVMF_MEDIA_CLOCK_HOUR = 4, 100 PVMF_MEDIA_CLOCK_DAY = 5 101 }; 102 103 /* 104 * Enum for return error codes for AdjustClock32() API 105 */ 106 enum PVMFMediaClockAdjustTimeStatus 107 { 108 PVMF_MEDIA_CLOCK_ADJUST_SUCCESS, 109 PVMF_MEDIA_CLOCK_ADJUST_ERR_INVALID_STATE, // If adjustment is attempted when clock is not running. 110 PVMF_MEDIA_CLOCK_ADJUST_ERR_INVALID_TIMEBASE_TIME, // If Adjustment is older than latest adjustment 111 PVMF_MEDIA_CLOCK_ADJUST_ERR_CORRUPT_CLOCK_TIME // If Clock time arg passed is later than current time 112 }; 113 114 115 class PVMFMediaClockNotificationsObsBase 116 { 117 public: ~PVMFMediaClockNotificationsObsBase()118 virtual ~PVMFMediaClockNotificationsObsBase() {} 119 /** 120 * This event happens when the clock has been Reset or destroyed and notification 121 * interface object that observer is using has been destroyed. Observer should 122 * set its pointer to PVMFMediaClockNotificationsInterface object as NULL. 123 */ 124 virtual void NotificationsInterfaceDestroyed() = 0; 125 }; 126 127 /** 128 PVMFMediaClockNotificationsObs is an observer class for PVMFMediaClock for Callbacks. 129 ProcessCallBack() is called when the timer expires. 130 */ 131 class PVMFMediaClockNotificationsObs : public virtual PVMFMediaClockNotificationsObsBase 132 { 133 public: 134 /** 135 * This callback function is called when a callback expires or has become invalid. 136 * @param callBackID Callback ID of the timer that has expired 137 * Units is msec. 138 * @param aTimerAccuracy Accuracy of timer. Value is from enum PVTimeComparisonUtils::MediaTimeStatus 139 * @param aDelta delta of scheduled callback time and actual time of callback 140 * @param aContextData Context data passed while setting the timer 141 * @param aStatus Status of timer. Value can be PVMFSuccess, PVMFErrCallbackClockStopped 142 * or PVMFErrCallbackHasBecomeInvalid. aStatus is PVMFErrCallbackHasBecomeInvalid 143 * if the direction of NPT Clock has changed. aStatus can be PVMFErrCallbackHasBecomeInvalid 144 * only for a NPT callback. 145 * @return NONE 146 * 147 */ 148 virtual void ProcessCallBack(uint32 callBackID, PVTimeComparisonUtils::MediaTimeStatus aTimerAccuracy, uint32 aDelta, 149 const OsclAny* aContextData, PVMFStatus aStatus) = 0; 150 151 /** 152 * This callback function is called when the notification interface 153 * being used by the object has been destroyed. 154 */ 155 virtual void NotificationsInterfaceDestroyed() = 0; 156 }; 157 158 /** 159 PVMFMediaClockObserver is an observer class for PVMFMediaClock. Modules 160 can optionally register themselves as clock observers. There 161 can be multiple observers for a single clock. 162 */ 163 class PVMFMediaClockObserver : public virtual PVMFMediaClockNotificationsObsBase 164 { 165 public: 166 167 /** 168 * This callback function is called when the timebase for this clock 169 * has been updated 170 */ 171 virtual void ClockTimebaseUpdated() = 0; 172 173 /** 174 * This callback function is called for counting timebases only, when the 175 * count has been updated. 176 */ 177 virtual void ClockCountUpdated() = 0; 178 179 /** 180 * This callback function is called when the clock has been adjusted. 181 */ 182 virtual void ClockAdjusted() = 0; 183 ~PVMFMediaClockObserver()184 virtual ~PVMFMediaClockObserver() {} 185 }; 186 187 /** 188 PVMFMediaClockStateObserver is an observer class for PVMFMediaClock. Modules 189 can optionally register themselves as clock state observers. There 190 can be multiple observers for a single clock. 191 */ 192 class PVMFMediaClockStateObserver : public virtual PVMFMediaClockNotificationsObsBase 193 { 194 public: 195 /** 196 * This callback function is called when the clock state changes. 197 */ 198 virtual void ClockStateUpdated() = 0; 199 ~PVMFMediaClockStateObserver()200 virtual ~PVMFMediaClockStateObserver() {} 201 }; 202 203 /** 204 PVMFCountTimebase is an extension to the standard timebase to allow 205 controlled stepping rather than continuous flow timebase. 206 */ 207 class PVMFCountTimebase 208 { 209 public: 210 /** 211 * Set a new value for the count. Will trigger a ClockCountUpdated callback 212 * to all observers of the clock in which this timebase resides. 213 * @param aCount (input): the new count 214 */ 215 virtual void SetCount(int32 aCount) = 0; 216 217 /** 218 * Read current value of the count. 219 * @param aCount (output): the current count 220 */ 221 virtual void GetCount(int32& aCount) = 0; 222 ~PVMFCountTimebase()223 virtual ~PVMFCountTimebase() {} 224 private: 225 /** 226 * Each PVMFCountTimebase will be contained within an PVMFMediaClock 227 * class. That PVMFMediaClock instance will set itself as the observer of 228 * the PVMFCountTimebase. To get notices from the timebase, modules 229 * can register through the SetClockObserver method of the PVMFMediaClock. 230 */ 231 friend class PVMFMediaClock; 232 virtual void SetClockObserver(PVMFMediaClockObserver* aObserver) = 0; 233 }; 234 235 /** 236 PVMFTimebase is a base class to obtain the timebase clock time. 237 Common source of the timebase clock is the system tickcount which is implemented 238 as PVMFTimebase_Tickcount further below. PVMFTimebase is expected to return the time 239 in units of microseconds even if the timebase itself does not have the resolution of microseconds. 240 */ 241 class PVMFTimebase 242 { 243 public: 244 ~PVMFTimebase()245 virtual ~PVMFTimebase() {} 246 247 /** 248 * Gets the timebase clock's smallest time resolution in microseconds 249 * @param aResolution: unsigned 32-bit value for the clock resolution 250 */ 251 virtual void GetTimebaseResolution(uint32& aResolution) = 0; 252 253 /** 254 * Returns the timebase clock's smallest time resolution in microseconds 255 * @param aResolution: unsigned 32-bit value for the clock resolution 256 */ 257 258 /** 259 * Read current value of the count. 260 * @param aResolution: unsigned 32-bit value. Playback rate unit is milli-percent of real time 261 */ 262 virtual int32 GetRate(void) = 0; 263 264 /** 265 * Returns current tickcount. PVMFMediaClock sources this value from the timebase. If no 266 * timebase is set, aTimebaseTickCount is set to 0. 267 * @param aTime: a reference to an unsigned 32-bit integer to return the current time 268 * @param aUnits: the requested time units for aTime 269 * @param aTimebaseTime: a reference to an unsigned 32-bit integer to return the timebase time 270 */ 271 virtual void GetCurrentTick32(uint32& aTimebaseTickCount, bool& aOverflow) = 0; 272 273 /** 274 * This API returns pointer to clock's timebase if timebase being used is a PVMFCountTimebase 275 * object. Otherwise, NULL is returned. PVMFCountTimebase is used for a stepping clock. 276 * @return pointer to PVMFCountTimebase implementation, or NULL if not supported. 277 */ 278 virtual PVMFCountTimebase* GetCountTimebase() = 0; 279 280 }; 281 282 /* 283 PVMFMediaClockControlInterface interface class is implemented by PVMFMediaClock. 284 This class contains methods for controlling PVMFMediaClock 285 */ 286 class PVMFMediaClockControlInterface: public PVInterface 287 { 288 public: 289 /** 290 * Starts the clock from the start time or 291 * resumes the clock from the last paused time. Clock goes to RUNNING state. 292 * @return true if the clock is resumed or started, false otherwise 293 */ 294 295 virtual OSCL_IMPORT_REF bool Start() = 0; 296 297 /** 298 * Pauses the running clock. Saves the clock time when pausing as the paused time. 299 * Clock goes to PAUSED state. Returns true if the clock is paused, false otherwise. 300 * Will trigger a ClockStateUpdated notice to all state observers of this clock. 301 * @return true if the clock is paused, false otherwise 302 */ 303 virtual OSCL_IMPORT_REF bool Pause() = 0; 304 305 /** 306 * Stops the running or paused clock and start time is reset to 0. Clock goes to STOPPED state. 307 * Will trigger a ClockStateUpdated notice to all state observers of this clock. State 308 * observers and clock observers are not automatically removed when clock is stopped. However, 309 * any active callbacks will be fired with error code PVMFErrCallbackClockStopped. 310 * 311 * @return true if the clock is stopped, false otherwise 312 */ 313 virtual OSCL_IMPORT_REF bool Stop() = 0; 314 315 /** 316 * Sets the starting clock time with unsigned 32-bit integer in the specified time units 317 * while in STOPPED state. Clock's internal timekeeping units are changed to usecs if aUnits 318 * is usecs. Otherwise, internal units remain msecs(default). High probability of overflow if 319 * units are given as usecs. 320 * @param aTime: a reference to an unsigned 32-bit integer to set the start time 321 * @param aUnits: the time units of aTime 322 * @param aOverFlow: true if operation resulted in overflow, false otherwise 323 * @return true if start time was set, false otherwise 324 */ 325 virtual OSCL_IMPORT_REF bool SetStartTime32(uint32& aTime, PVMFMediaClock_TimeUnits aUnits, bool& aOverFlow) = 0; 326 327 /** 328 * Adjusts the clock time with unsigned 32-bit integer in the specified time units while in 329 * RUNNING state. For backward adjustments, clock freezes internally till the adjusted time. 330 * @param aClockTime: a reference to an unsigned 32-bit integer to the observation clock time 331 * @param aTimebaseTime: a reference to an unsigned 32-bit integer to the observation timebase time 332 * @param aAdjustedTime: a reference to an unsigned 32-bit integer to the adjusted clock time 333 * @param aUnits: the time units of aClockTime and aAdjustedTime 334 * @return true if AdjustClockTime32 is successful 335 */ 336 virtual OSCL_IMPORT_REF PVMFMediaClockAdjustTimeStatus AdjustClockTime32(uint32& aClockTime, uint32& aTimebaseTime, uint32& aAdjustedTime, PVMFMediaClock_TimeUnits aUnits, bool& aOverFlow) = 0; 337 338 /** 339 * Stops the running or paused clock and start time is reset to 0. Clock goes to STOPPED state. 340 * Will trigger a ClockStateUpdated notice to all state observers of this clock.Clock observers 341 * and clock state observers are automatically removed when clock is Reset. Any active callbacks 342 * will be fired with error code PVMFErrCallbackClockStopped. All PVMFMediaClockNotificationsInterface 343 * objects are deleted. 344 * @return true if reset is successful. 345 */ 346 virtual OSCL_IMPORT_REF bool Reset() = 0; 347 addRef()348 void addRef() {} removeRef()349 void removeRef() {} queryInterface(const PVUuid & uuid,PVInterface * & iface)350 bool queryInterface(const PVUuid& uuid, PVInterface*& iface) 351 { 352 OSCL_UNUSED_ARG(uuid); 353 OSCL_UNUSED_ARG(iface); 354 return false; 355 } 356 }; 357 358 /* 359 PVMFMediaClockAccessInterface interface class is implemented by PVMFMediaClock. 360 This class contains method for accessing start time from PVMFMediaClock. 361 */ 362 class PVMFMediaClockAccessInterface: public PVInterface 363 { 364 public: 365 366 /** 367 * Gets the starting clock time as an unsigned 32-bit integer in the specified time units 368 * @param aTime: a reference to an unsigned 32-bit integer to copy the start time 369 * @param aOverflow: a reference to a flag which is set if time value cannot fit in unsigned 32-bit integer 370 * @param aUnits: the requested time units for aTime 371 */ 372 virtual OSCL_IMPORT_REF void GetStartTime32(uint32& aTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits) = 0; 373 374 /** 375 * Gets the starting clock time as an unsigned 32-bit integer in the specified time units 376 * @param aClockTime: a reference to an unsigned 32-bit integer to return current time in specified time units 377 * @param aOverflow: a reference to a flag which is set if time value cannot fit in unsigned 32-bit integer 378 * @param aUnits: the requested time units for aTime 379 */ 380 virtual OSCL_IMPORT_REF void GetCurrentTime32(uint32& aClockTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits) = 0; 381 382 /** 383 * This API is used to get current clock time in time units specified. If the value does not fit 384 * in 32 bit uint (aTime), aOverflow flag is set. This API also provides current timebase tickcount. 385 * This is not the absolute tickcount value from timebase. PVMFMediaClock uses scaled version of 386 * timebase tickcount by subtracting the tickcount value at clock start time from the current tickcount value. 387 * Thus, the clock starts from tickcount value 0 and probability of overflow is reduced. 388 * @param aClockTime: a reference to an unsigned 32-bit integer to return current time in specified time units 389 * @param aOverflow: a reference to a flag which is set if time value cannot fit in unsigned 32-bit integer 390 * @param aUnits: the requested time units for aTime 391 * @param aTimebaseTime: uint32 value used to return current (scaled) timebase tickcount 392 */ 393 virtual OSCL_IMPORT_REF void GetCurrentTime32(uint32& aClockTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits, uint32& aTimebaseTime) = 0; 394 addRef()395 void addRef() {} removeRef()396 void removeRef() {} queryInterface(const PVUuid & uuid,PVInterface * & iface)397 bool queryInterface(const PVUuid& uuid, PVInterface*& iface) 398 { 399 OSCL_UNUSED_ARG(uuid); 400 OSCL_UNUSED_ARG(iface); 401 return false; 402 } 403 }; 404 405 /* 406 PVMFMediaClockNotificationsInterface interface is implemented by 407 PVMFMediaClockNotificationsInterfaceImpl class. This interface contains all callbacks related methods. 408 This class has methods related to both regular callbacks and NPT callbacks. 409 */ 410 411 class PVMFMediaClockNotificationsInterface 412 { 413 public: 414 415 /*!********************************************************************* 416 ** 417 ** Function: SetCallbackAbsoluteTime 418 ** 419 ** Synopsis: Set a callback timer specifying an absolute time in clock for timer expiry. 420 ** 421 ** Arguments : 422 ** @param [absoluteTime] -- absolute time in clock when callBack should be called. 423 ** Units is msec. 424 ** @param [window] -- Error tolerance available in callback time. If T is the desired 425 ** callback time and w is the allowed tolerance window, then callback 426 ** can come between T-w to T+w time. 427 ** @param [aObserver] -- observer object to be called on timeout. 428 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 429 ** not. Making callback threadsafe might add overheads. 430 ** @param [aContextData] -- context pointer that will be returned back with the callback. 431 ** @param [callBackID] -- ID used to identify the timer for cancellation 432 ** 433 ** Returns: 434 ** @return PVMFStatus -- success or error code 435 ** 436 ** 437 ** Notes: 438 ** 439 **********************************************************************/ 440 virtual OSCL_IMPORT_REF PVMFStatus SetCallbackAbsoluteTime( 441 /*IN*/ uint32 aAbsoluteTime, 442 /*IN*/ uint32 aWindow, 443 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 444 /*IN*/ bool aThreadLock, 445 /*IN*/ const OsclAny* aContextData, 446 /*OUT*/ uint32& aCallBackID) = 0; 447 448 /*!********************************************************************* 449 ** 450 ** Function: SetCallbackDeltaTime 451 ** 452 ** Synopsis: Set a callback timer specifying a delta time from current time for timer expiry. 453 ** 454 ** Arguments : 455 ** @param [deltaTime] -- delta time in clock when callBack should be called. 456 ** Units is msec. 457 ** @param [window] -- Error tolerance available in callback time. If T is the desired 458 ** callback time and w is the allowed tolerance window, then callback 459 ** can come between T-w to T+w time. 460 ** @param [aObserver] -- observer object to be called on timeout. 461 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 462 ** not. Making callback threadsafe might add overheads. 463 ** @param [aContextData] -- context pointer that will be returned back with the callback. 464 ** @param [callBackID] -- ID used to identify the timer for cancellation 465 ** 466 ** Returns: 467 ** @return PVMFStatus -- success or error code 468 ** 469 ** 470 ** Notes: 471 ** 472 **********************************************************************/ 473 virtual OSCL_IMPORT_REF PVMFStatus SetCallbackDeltaTime( 474 /*IN*/ uint32 aDeltaTime, 475 /*IN*/ uint32 aWindow, 476 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 477 /*IN*/ bool aThreadLock, 478 /*IN*/ const OsclAny* aContextData, 479 /*OUT*/ uint32 &aCallBackID) = 0; 480 481 /*!********************************************************************* 482 ** 483 ** Function: CancelCallback 484 ** 485 ** Synopsis: Cancel callback timer set with SetCallBackDeltaTime() or SetCallbackAbsoluteTime() 486 ** 487 ** Arguments : 488 ** @param [callbackID] -- timer ID returned by SetCallBackDeltaTime() 489 ** or SetCallbackAbsoluteTime() 490 ** @param : [aThreadLock] -- whether this call needs to be threadsafe 491 ** Returns: 492 ** @return PVMFStatus 493 ** 494 ** Notes: 495 ** 496 **********************************************************************/ 497 virtual OSCL_IMPORT_REF PVMFStatus CancelCallback( 498 /*IN*/ uint32 aCallbackID, bool aThreadLock) = 0; 499 500 /*!********************************************************************* 501 ** 502 ** Function: SetNPTCallbackAbsoluteTime 503 ** 504 ** Synopsis: Set a callback timer specifying an absolute time in clock for timer expiry. 505 ** 506 ** Arguments : 507 ** @param [absoluteTime] -- absolute time in clock when callBack should be called. 508 ** Units is msec. 509 ** @param [window] -- Error tolerance available in callback time. If T is the desired 510 ** callback time and w is the allowed tolerance window, then callback 511 ** can come between T-w to T+w time. 512 ** @param [aObserver] -- observer object to be called on timeout. 513 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 514 ** not. Making callback threadsafe might add overheads. 515 ** @param [aContextData] -- context pointer that will be returned back with the callback. 516 ** @param [callBackID] -- ID used to identify the timer for cancellation 517 ** 518 ** Returns: 519 ** @return PVMFStatus -- success or error code 520 ** 521 ** 522 ** Notes: 523 ** 524 **********************************************************************/ 525 526 virtual OSCL_IMPORT_REF PVMFStatus SetNPTCallbackAbsoluteTime( 527 /*IN*/ uint32 aAbsoluteTime, 528 /*IN*/ uint32 aWindow, 529 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 530 /*IN*/ bool aThreadLock, 531 /*IN*/ const OsclAny* aContextData, 532 /*OUT*/ uint32& aCallBackID) = 0; 533 534 /*!********************************************************************* 535 ** 536 ** Function: SetNPTCallbackDeltaTime 537 ** 538 ** Synopsis: Set a callback timer specifying a delta time from current time for timer expiry. 539 ** 540 ** Arguments : 541 ** @param [deltaTime] -- delta time in clock when callBack should be called. 542 ** Units is msec. 543 ** @param [window] -- Error tolerance available in callback time. If T is the desired 544 ** callback time and w is the allowed tolerance window, then callback 545 ** can come between T-w to T+w time. 546 ** @param [aObserver] -- observer object to be called on timeout. 547 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 548 ** not. Making callback threadsafe might add overheads. 549 ** @param [aContextData] -- context pointer that will be returned back with the callback. 550 ** @param [callBackID] -- ID used to identify the timer for cancellation 551 ** 552 ** Returns: 553 ** @return PVMFStatus -- success or error code 554 ** 555 ** 556 ** Notes: 557 ** 558 **********************************************************************/ 559 virtual OSCL_IMPORT_REF PVMFStatus SetNPTCallbackDeltaTime( 560 /*IN*/ uint32 aDeltaTime, 561 /*IN*/ uint32 aWindow, 562 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 563 /*IN*/ bool aThreadLock, 564 /*IN*/ const OsclAny* aContextData, 565 /*OUT*/ uint32& aCallBackID) = 0; 566 567 /*!********************************************************************* 568 ** 569 ** Function: CancelCallback 570 ** 571 ** Synopsis: Cancel callback timer set with SetCallBackDeltaTime() or SetCallbackAbsoluteTime() 572 ** 573 ** Arguments : 574 ** @param [callbackID] -- timer ID returned by SetCallBackDeltaTime() 575 ** or SetCallbackAbsoluteTime() 576 ** @param : [aThreadLock] -- whether this call needs to be threadsafe 577 ** Returns: 578 ** @return PVMFStatus 579 ** 580 ** Notes: 581 ** 582 **********************************************************************/ 583 virtual OSCL_IMPORT_REF PVMFStatus CancelNPTCallback( 584 /*IN*/ uint32 aCallbackID, bool aThreadLock) = 0; 585 586 /** 587 * This API sets the object passed as a ClockObserver. The object's callback 588 * functions (ClockTimebaseUpdated(),ClockCountUpdated(),ClockAdjusted() ) 589 * will be called on corresponding events. 590 * @param aObserver: the observer implemenation 591 */ 592 virtual OSCL_IMPORT_REF void SetClockObserver(PVMFMediaClockObserver& aObserver) = 0; 593 594 /** 595 * This API removes aObserver obeject from the list of ClockObservers if aObserver 596 * is set as an observer. 597 * @param aObserver: the observer implemenation 598 */ 599 virtual OSCL_IMPORT_REF void RemoveClockObserver(PVMFMediaClockObserver& aObserver) = 0; 600 601 /** 602 * This API sets the object passed as a ClockStateObserver. The object's callback 603 * function ClockStateUpdated() will be called on clock state change. 604 * @param aObserver: the observer implemenation 605 */ 606 virtual OSCL_IMPORT_REF void SetClockStateObserver(PVMFMediaClockStateObserver& aObserver) = 0; 607 608 /** 609 * Removes an observer for this clock. If the observer is not registered, this 610 * call does nothing. 611 * @param aObserver: the observer implemenation 612 */ 613 virtual OSCL_IMPORT_REF void RemoveClockStateObserver(PVMFMediaClockStateObserver& aObserver) = 0; 614 ~PVMFMediaClockNotificationsInterface()615 virtual ~PVMFMediaClockNotificationsInterface() {} 616 }; 617 618 /* 619 PVMFMediaClockNotificationsImplInterface class is implemented by PVMFMediaClock. This class contains 620 corresponding PVMFMediaClock side functions of interface PVMFMediaClockNotifications. 621 */ 622 623 class PVMFMediaClockNotificationsImplInterface 624 { 625 public: 626 627 /*!********************************************************************* 628 ** 629 ** Function: SetCallbackAbsoluteTime 630 ** 631 ** Synopsis: Set a callback timer specifying an absolute time in clock for timer expiry. 632 ** 633 ** Arguments : 634 ** @param [absoluteTime] -- absolute time in clock when callBack should be called. 635 ** Units is msec. 636 ** @param [window] -- Error tolerance available in callback time. If T is the desired 637 ** callback time and w is the allowed tolerance window, then callback 638 ** can come between T-w to T+w time. 639 ** @param [aObserver] -- observer object to be called on timeout. 640 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 641 ** not. Making callback threadsafe might add overheads. 642 ** @param [aContextData] -- context pointer that will be returned back with the callback. 643 ** @param [callBackID] -- ID used to identify the timer for cancellation 644 ** @param [aInterfaceObject] -- self pointer of interface object which calls this function 645 ** Returns: 646 ** @return PVMFStatus -- success or error code 647 ** 648 ** 649 ** Notes: 650 ** 651 **********************************************************************/ 652 virtual OSCL_IMPORT_REF PVMFStatus SetCallbackAbsoluteTime( 653 /*IN*/ uint32 aAbsoluteTime, 654 /*IN*/ uint32 aWindow, 655 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 656 /*IN*/ bool aThreadLock, 657 /*IN*/ const OsclAny* aContextData, 658 /*OUT*/ uint32& aCallBackID, 659 /*IN*/ const OsclAny* aInterfaceObject) = 0; 660 661 /*!********************************************************************* 662 ** 663 ** Function: SetCallbackDeltaTime 664 ** 665 ** Synopsis: Set a callback timer specifying a delta time from current time for timer expiry. 666 ** 667 ** Arguments : 668 ** @param [deltaTime] -- delta time in clock when callBack should be called. 669 ** Units is msec. 670 ** @param [window] -- Error tolerance available in callback time. If T is the desired 671 ** callback time and w is the allowed tolerance window, then callback 672 ** can come between T-w to T+w time. 673 ** @param [aObserver] -- observer object to be called on timeout. 674 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 675 ** not. Making callback threadsafe might add overheads. 676 ** @param [aContextData] -- context pointer that will be returned back with the callback. 677 ** @param [callBackID] -- ID used to identify the timer for cancellation 678 ** @param [aInterfaceObject] -- self pointer of interface object which calls this function 679 ** Returns: 680 ** @return PVMFStatus -- success or error code 681 ** 682 ** 683 ** Notes: 684 ** 685 **********************************************************************/ 686 virtual OSCL_IMPORT_REF PVMFStatus SetCallbackDeltaTime( 687 /*IN*/ uint32 aDeltaTime, 688 /*IN*/ uint32 aWindow, 689 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 690 /*IN*/ bool aThreadLock, 691 /*IN*/ const OsclAny* aContextData, 692 /*OUT*/ uint32 &aCallBackID, 693 /*IN*/ const OsclAny* aInterfaceObject) = 0; 694 695 /*!********************************************************************* 696 ** 697 ** Function: CancelCallback 698 ** 699 ** Synopsis: Cancel callback timer set with SetCallBackDeltaTime() or SetCallbackAbsoluteTime() 700 ** 701 ** Arguments : 702 ** @param [callbackID] -- timer ID returned by SetCallBackDeltaTime() 703 ** or SetCallbackAbsoluteTime() 704 ** @param : [aThreadLock] -- whether this call needs to be threadsafe 705 ** Returns: 706 ** @return PVMFStatus 707 ** 708 ** Notes: 709 ** 710 **********************************************************************/ 711 virtual OSCL_IMPORT_REF PVMFStatus CancelCallback( 712 /*IN*/ uint32 aCallbackID, bool aThreadLock) = 0; 713 714 /*!********************************************************************* 715 ** 716 ** Function: SetNPTCallbackAbsoluteTime 717 ** 718 ** Synopsis: Set a callback timer specifying an absolute time in clock for timer expiry. 719 ** 720 ** Arguments : 721 ** @param [absoluteTime] -- absolute time in clock when callBack should be called. 722 ** Units is msec. 723 ** @param [window] -- Error tolerance available in callback time. If T is the desired 724 ** callback time and w is the allowed tolerance window, then callback 725 ** can come between T-w to T+w time. 726 ** @param [aObserver] -- observer object to be called on timeout. 727 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 728 ** not. Making callback threadsafe might add overheads. 729 ** @param [aContextData] -- context pointer that will be returned back with the callback. 730 ** @param [callBackID] -- ID used to identify the timer for cancellation 731 ** @param [aInterfaceObject] -- self pointer of interface object which calls this function 732 ** Returns: 733 ** @return PVMFStatus -- success or error code 734 ** 735 ** 736 ** Notes: 737 ** 738 **********************************************************************/ 739 740 virtual OSCL_IMPORT_REF PVMFStatus SetNPTCallbackAbsoluteTime( 741 /*IN*/ uint32 aAbsoluteTime, 742 /*IN*/ uint32 aWindow, 743 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 744 /*IN*/ bool aThreadLock, 745 /*IN*/ const OsclAny* aContextData, 746 /*OUT*/ uint32& aCallBackID, 747 /*IN*/ const OsclAny* aInterfaceObject) = 0; 748 749 /*!********************************************************************* 750 ** 751 ** Function: SetNPTCallbackDeltaTime 752 ** 753 ** Synopsis: Set a callback timer specifying a delta time from current time for timer expiry. 754 ** 755 ** Arguments : 756 ** @param [deltaTime] -- delta time in clock when callBack should be called. 757 ** Units is msec. 758 ** @param [window] -- Error tolerance available in callback time. If T is the desired 759 ** callback time and w is the allowed tolerance window, then callback 760 ** can come between T-w to T+w time. 761 ** @param [aObserver] -- observer object to be called on timeout. 762 ** @param [threadLock] -- If threadLock is true, callback will to be threadsafe otherwise 763 ** not. Making callback threadsafe might add overheads. 764 ** @param [aContextData] -- context pointer that will be returned back with the callback. 765 ** @param [callBackID] -- ID used to identify the timer for cancellation 766 ** @param [aInterfaceObject] -- self pointer of interface object which calls this function 767 ** Returns: 768 ** @return PVMFStatus -- success or error code 769 ** 770 ** 771 ** Notes: 772 ** 773 **********************************************************************/ 774 virtual OSCL_IMPORT_REF PVMFStatus SetNPTCallbackDeltaTime( 775 /*IN*/ uint32 aDeltaTime, 776 /*IN*/ uint32 aWindow, 777 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 778 /*IN*/ bool aThreadLock, 779 /*IN*/ const OsclAny* aContextData, 780 /*OUT*/ uint32& aCallBackID, 781 /*IN*/ const OsclAny* aInterfaceObject) = 0; 782 783 /*!********************************************************************* 784 ** 785 ** Function: CancelCallback 786 ** 787 ** Synopsis: Cancel callback timer set with SetCallBackDeltaTime() or SetCallbackAbsoluteTime() 788 ** 789 ** Arguments : 790 ** @param [callbackID] -- timer ID returned by SetCallBackDeltaTime() 791 ** or SetCallbackAbsoluteTime() 792 ** @param : [aThreadLock] -- whether this call needs to be threadsafe 793 ** Returns: 794 ** @return PVMFStatus 795 ** 796 ** Notes: 797 ** 798 **********************************************************************/ 799 virtual OSCL_IMPORT_REF PVMFStatus CancelNPTCallback( 800 /*IN*/ uint32 aCallbackID, bool aThreadLock) = 0; 801 802 /** 803 * Adds an observer for this clock. 804 * @param aObserver: the observer implemenation 805 */ 806 virtual OSCL_IMPORT_REF void SetClockObserver(PVMFMediaClockObserver& aObserver) = 0; 807 808 /** 809 * Removes an observer for this clock. If the observer is not registered, this 810 * call does nothing. 811 * @param aObserver: the observer implemenation 812 */ 813 virtual OSCL_IMPORT_REF void RemoveClockObserver(PVMFMediaClockObserver& aObserver) = 0; 814 815 /** 816 * Sets an observer for this clock. May leave if memory allocation fails. 817 * @param aObserver: the observer implemenation 818 */ 819 virtual OSCL_IMPORT_REF void SetClockStateObserver(PVMFMediaClockStateObserver& aObserver) = 0; 820 821 /** 822 * Removes an observer for this clock. If the observer is not registered, this 823 * call does nothing. 824 * @param aObserver: the observer implemenation 825 */ 826 virtual OSCL_IMPORT_REF void RemoveClockStateObserver(PVMFMediaClockStateObserver& aObserver) = 0; 827 ~PVMFMediaClockNotificationsImplInterface()828 virtual ~PVMFMediaClockNotificationsImplInterface() {} 829 }; 830 831 832 /* 833 PVMFMediaClockNPTClockPositionAccessInterface interface class is implemented by PVMFMediaClock. 834 This class contains methods for accessing and updating NPT clock position values 835 */ 836 837 class PVMFMediaClockNPTClockPositionAccessInterface: public PVInterface 838 { 839 840 public: 841 842 /** 843 * NPT clock position is not same as playback clock position. PVMFMediaClock 844 * can store the mapping between the two clocks. UpdateNPTClockPosition() API is 845 * called by the user to update change in NPT clock position. User can change the 846 * direction of NPT by specifying aIsPlayBackDirectionBackwards flag. 847 * @param aStartNPT: uint32 value containing new startNPT value 848 * @param aIsPlayBackDirectionBackwards: Should be set as false if 849 * NPT playback direction is forward from this point and should 850 * be set as true if NPT clock direction is backwards. 851 */ 852 virtual void UpdateNPTClockPosition( 853 /*IN*/ uint32 aStartNPT, 854 /*IN*/ bool aIsPlayBackDirectionBackwards) = 0; 855 856 /** 857 * Gets NPT clock position 858 * @param aCurrentPosition: uint32 value to store the current NPT clock position. 859 * @return PVMFSuccess/PVMFErrArgument. PVMFErrArgument is returned when there is 860 * overflow i.e. 32 bit aCurrentPosition is not enough to store current NPT 861 * clock value or if there is an internal overflow. 862 */ 863 virtual PVMFStatus GetNPTClockPosition( 864 /*OUT*/ uint32& aCurrentPosition) = 0; 865 866 /** 867 * This API clears the NPT clock mapping and resets internal variables to 0. 868 */ 869 virtual void ClearNPTClockPosition() = 0; 870 871 /** 872 * This API is used to schedule a NPT clock transition(time change) in future. All 873 * parameters are described above. 874 * @param aMediaClockPosition: Absolute media clock position when NPT clock change 875 * should take place. 876 * @param aStartNPT: new startNPT value to be set 877 * @param aIsPlayBackDirectionBackwards: flag specifying if NPT clock should run 878 * backwards after NPT time update. 879 * @param aWindow: margin window for scheduling the time change. i.e. NPT clock 880 * time change can be scheduled within window [aMediaClockPosition-aWindow, 881 * aMediaClockPosition+aWindow]. 882 * @param aClockTransitionEventID: clockTransitionID returned to user. This can be used 883 * to cancel a transition after it has been set. 884 * @return PVMFSuccess/PVMFFailure 885 */ 886 virtual PVMFStatus QueueNPTClockTransitionEvent(uint32 aMediaClockPosition, uint32 aStartNPT, 887 bool aIsPlayBackDirectionBackwards, uint32 aWindow, uint32& aClockTransitionEventID) = 0; 888 889 /** 890 * This API is used to cancel a NPTClockTransition event set by using QueueNPTClockTransitionEvent() 891 * @param aClockTransitionEventID: ID returned from QueueNPTClockTransitionEvent()function. 892 * @return PVMFSuccess/PVMFFailure 893 */ 894 virtual PVMFStatus CancelNPTClockTransitionEvent(uint32 aClockTransitionEventID) = 0; 895 addRef()896 void addRef() {} removeRef()897 void removeRef() {} queryInterface(const PVUuid & uuid,PVInterface * & iface)898 bool queryInterface(const PVUuid& uuid, PVInterface*& iface) 899 { 900 OSCL_UNUSED_ARG(uuid); 901 OSCL_UNUSED_ARG(iface); 902 return false; 903 } 904 }; 905 906 /* 907 PVMFMediaClockNotificationsInterfaceImpl is the implementation class for 908 PVMFMediaClockNotificationsInterface. 909 */ 910 911 class PVMFMediaClockNotificationsInterfaceImpl: public PVMFMediaClockNotificationsInterface 912 { 913 914 public: 915 916 //constructor 917 918 OSCL_IMPORT_REF PVMFMediaClockNotificationsInterfaceImpl(PVMFMediaClock *, uint32 aLatency, 919 PVMFMediaClockNotificationsObsBase& aNotificationInterfaceDestroyedCallback); 920 921 /** 922 The default destructor 923 */ 924 OSCL_IMPORT_REF ~PVMFMediaClockNotificationsInterfaceImpl(); 925 926 //From PVMFMediaClockNotificationsInterface 927 928 OSCL_IMPORT_REF PVMFStatus SetCallbackAbsoluteTime( 929 /*IN*/ uint32 aAbsoluteTime, 930 /*IN*/ uint32 aWindow, 931 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 932 /*IN*/ bool aThreadLock, 933 /*IN*/ const OsclAny* aContextData, 934 /*OUT*/ uint32& aCallBackID); 935 936 OSCL_IMPORT_REF PVMFStatus SetCallbackDeltaTime( 937 /*IN*/ uint32 aDeltaTime, 938 /*IN*/ uint32 aWindow, 939 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 940 /*IN*/ bool aThreadLock, 941 /*IN*/ const OsclAny* aContextData, 942 /*OUT*/ uint32& aCallBackID); 943 944 OSCL_IMPORT_REF PVMFStatus CancelCallback( 945 /*IN*/ uint32 aCallbackID, bool aThreadLock); 946 947 OSCL_IMPORT_REF PVMFStatus SetNPTCallbackAbsoluteTime( 948 /*IN*/ uint32 aAbsoluteTime, 949 /*IN*/ uint32 aWindow, 950 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 951 /*IN*/ bool aThreadLock, 952 /*IN*/ const OsclAny* aContextData, 953 /*OUT*/ uint32& aCallBackID); 954 955 OSCL_IMPORT_REF PVMFStatus SetNPTCallbackDeltaTime( 956 /*IN*/ uint32 aDeltaTime, 957 /*IN*/ uint32 aWindow, 958 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 959 /*IN*/ bool aThreadLock, 960 /*IN*/ const OsclAny* aContextData, 961 /*OUT*/ uint32& aCallBackID); 962 963 OSCL_IMPORT_REF PVMFStatus CancelNPTCallback( 964 /*IN*/ uint32 aCallbackID, bool aThreadLock); 965 966 OSCL_IMPORT_REF void SetClockObserver(PVMFMediaClockObserver& aObserver); 967 968 OSCL_IMPORT_REF void RemoveClockObserver(PVMFMediaClockObserver& aObserver); 969 970 OSCL_IMPORT_REF void SetClockStateObserver(PVMFMediaClockStateObserver& aObserver); 971 972 OSCL_IMPORT_REF void RemoveClockStateObserver(PVMFMediaClockStateObserver& aObserver); 973 974 //End PVMFMediaClockNotificationsInterface 975 976 protected: 977 978 /*PVMFMediaClock will have a vector of PVMFMediaClockNotificationsInterfaceImpl 979 instances. PVMFMediaClock will access iLatency from this class*/ 980 friend class PVMFMediaClock; 981 PVMFMediaClockStateObserver *iClockStateObserver; 982 uint32 iLatency; 983 //this value is iLatency - min latency among all objects present. 984 uint32 iAdjustedLatency; 985 //This value is the delay after which clock start notification will be sent. 986 uint32 iLatencyDelayForClockStartNotification; 987 PVMFMediaClock *iContainer; 988 PVMFMediaClockNotificationsObsBase* iNotificationInterfaceDestroyedCallback; 989 }; 990 991 /*This structure represents one callback element inserted in PVMFMediaClock's internal timer queues */ 992 class PVMFMediaClockTimerQueueElement 993 { 994 public: 995 /** 996 * Equality comparison for use with OsclPriorityQueue 997 */ 998 bool operator==(const PVMFMediaClockTimerQueueElement &other) const 999 { 1000 return callBackID == other.callBackID; 1001 } 1002 uint32 timeOut; 1003 uint32 callBackID; 1004 bool isNPTTimer; 1005 uint32 window; 1006 PVMFMediaClockNotificationsObs* obs; 1007 const OsclAny* contextData; 1008 const OsclAny* pInterfaceObject; 1009 } ; 1010 1011 1012 /*This structure represents one NPT Clock transition event */ 1013 typedef struct _PVMFMediaClockNPTTransitionEventElement 1014 { 1015 uint32 mediaClockPosition; 1016 uint32 startNPT; 1017 bool isPlayBackDirectionBackwards; 1018 uint32 window; 1019 uint32 eventID; 1020 } PVMFMediaClockNPTTransitionEventElement; 1021 1022 /*This structure represents one clock start notification event */ 1023 typedef struct _PVMFMediaClockStartNotificationEventElement 1024 { 1025 PVMFMediaClockStateObserver *clockStateObserver; 1026 uint32 eventID; 1027 } PVMFMediaClockStartNotificationEventElement; 1028 1029 /*This is the comparison class supplied to PVMFMediaClock's priority queues */ 1030 class PVMFMediaClockTimerQueueCompareLess 1031 { 1032 public: compare(PVMFMediaClockTimerQueueElement & a,PVMFMediaClockTimerQueueElement & b)1033 int compare(PVMFMediaClockTimerQueueElement& a, PVMFMediaClockTimerQueueElement& b) const 1034 { 1035 uint32 delta = 0; 1036 return PVTimeComparisonUtils::IsEarlier(b.timeOut, a.timeOut, delta); 1037 } 1038 }; 1039 1040 /*This comparison class is used for backwards NPT priority queue. This queue needs to maintain timers in 1041 Descending fashion*/ 1042 class PVMFMediaClockTimerQueueCompareLessForNPTBackwards 1043 { 1044 public: compare(PVMFMediaClockTimerQueueElement & a,PVMFMediaClockTimerQueueElement & b)1045 int compare(PVMFMediaClockTimerQueueElement& a, PVMFMediaClockTimerQueueElement& b) const 1046 { 1047 uint32 delta = 0; 1048 return PVTimeComparisonUtils::IsEarlier(a.timeOut, b.timeOut, delta); 1049 } 1050 }; 1051 1052 1053 class PVMFMediaClock : public OsclTimerObject, 1054 public PVMFTimebase, 1055 public PVMFMediaClockObserver, 1056 public PVMFMediaClockControlInterface, 1057 public PVMFMediaClockAccessInterface, 1058 public PVMFMediaClockNPTClockPositionAccessInterface, 1059 public PVMFMediaClockNotificationsImplInterface, 1060 public PVMFMediaClockNotificationsObs /*Media clock uses itself to set callback*/ 1061 { 1062 1063 public: 1064 1065 /** 1066 The default constructor initializes the clock to 0 and goes to STOPPED state 1067 */ 1068 OSCL_IMPORT_REF PVMFMediaClock(); 1069 1070 /** 1071 The default destructor 1072 */ 1073 OSCL_IMPORT_REF ~PVMFMediaClock(); 1074 1075 /** 1076 * Sets the timebase to use for this clock. 1077 * Will trigger an ClockTimebaseUpdated notice to all observers of this clock. 1078 * The clock timebase can only be set while in STOPPED and PAUSED states. 1079 * @param aTimebase: a reference to an PVMFTimebase-derived object 1080 * @return true if the new clock timebase has been accepted, false otherwise 1081 */ 1082 OSCL_IMPORT_REF bool SetClockTimebase(PVMFTimebase& aTimebase); 1083 1084 /** 1085 * This API constructs a PVMFMediaClockNotificationsInterface object. This API does not 1086 * work when clock is in running state and if called while clock is running, it returns 1087 * PVMFErrInvalidState. Object created using this API must be explicitly destroyed using 1088 * DestroyMediaClockNotificationsInterface(). 1089 * @param aIface: PVMFMediaClockNotificationsInterface* variable to store reference to 1090 * constructed notifications object. 1091 * @param aNotificationInterfaceDestroyedCallback: Implementation of callback function 1092 * which would be called when the interface 1093 * is destroyed. 1094 * @param aLatency: uint32 variable containing latency value associated with the module. 1095 * @return true if the new clock timebase has been accepted, false otherwise 1096 */ 1097 OSCL_IMPORT_REF PVMFStatus ConstructMediaClockNotificationsInterface(PVMFMediaClockNotificationsInterface*& aIface, 1098 PVMFMediaClockNotificationsObsBase &aNotificationInterfaceDestroyedCallback, uint32 aLatency = 0); 1099 1100 /* This API destroys the PVMFMediaClockNotificationsInterface object created 1101 * by ConstructMediaClockNotificationsInterface(). 1102 * @param aIface: PVMFMediaClockNotificationsInterface* variable containing reference to 1103 * object to be destroyed. 1104 */ 1105 OSCL_IMPORT_REF void DestroyMediaClockNotificationsInterface(PVMFMediaClockNotificationsInterface* aInf); 1106 1107 1108 1109 // From PVMFTimebase 1110 1111 OSCL_IMPORT_REF void GetCurrentTick32(uint32& aTimebaseTickCount, bool& aOverflow); 1112 GetCountTimebase()1113 PVMFCountTimebase* GetCountTimebase() 1114 { 1115 if (iClockTimebase) 1116 return iClockTimebase->GetCountTimebase(); 1117 return NULL; 1118 } 1119 1120 OSCL_IMPORT_REF void GetTimebaseResolution(uint32& aResolution); 1121 1122 1123 OSCL_IMPORT_REF int32 GetRate(void); 1124 1125 1126 // From PVMFMediaClockControlInterface 1127 1128 OSCL_IMPORT_REF bool Start(); 1129 1130 OSCL_IMPORT_REF bool Pause(); 1131 1132 OSCL_IMPORT_REF bool Stop(); 1133 1134 OSCL_IMPORT_REF bool SetStartTime32(uint32& aTime, PVMFMediaClock_TimeUnits aUnits, bool& aOverFlow); 1135 1136 OSCL_IMPORT_REF PVMFMediaClockAdjustTimeStatus AdjustClockTime32(uint32& aClockTime, uint32& aTimebaseTime, uint32& aAdjustedTime, PVMFMediaClock_TimeUnits aUnits, bool& aOverFlow); 1137 1138 OSCL_IMPORT_REF bool Reset(); 1139 1140 // End PVMFMediaClockControlInterface 1141 1142 // From PVMFMediaClockAccessInterface 1143 1144 OSCL_IMPORT_REF void GetStartTime32(uint32& aTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits); 1145 OSCL_IMPORT_REF void GetCurrentTime32(uint32& aTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits, uint32& aTimebaseTime); 1146 OSCL_IMPORT_REF void GetCurrentTime32(uint32& aTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits); 1147 1148 // End PVMFMediaClockAccessInterface 1149 1150 1151 OSCL_IMPORT_REF bool QueryInterface(const PVUuid& uuid, PVInterface*& iface); 1152 1153 // From PVMFMediaClockNPTClockPositionAccessInterface 1154 1155 void UpdateNPTClockPosition( 1156 /*IN*/ uint32 aStartNPT, 1157 /*IN*/ bool aIsPlayBackDirectionBackwards); 1158 1159 PVMFStatus GetNPTClockPosition( 1160 /*OUT*/ uint32& aCurrentPosition); 1161 1162 void ClearNPTClockPosition(); 1163 1164 PVMFStatus QueueNPTClockTransitionEvent(uint32 aMediaClockPosition, uint32 aStartNPT, 1165 bool aIsPlayBackDirectionBackwards, uint32 aWindow, uint32& aClockTransitionEventID); 1166 1167 PVMFStatus CancelNPTClockTransitionEvent(uint32 aClockTransitionEventID); 1168 // End PVMFMediaClockNPTClockPositionAccessInterface 1169 1170 /* 1171 * Enum for PVMFMediaClock's internal states 1172 */ 1173 enum PVMFMediaClockState 1174 { 1175 STOPPED, 1176 RUNNING, 1177 PAUSED 1178 }; 1179 1180 /*Returns the current state of MediaClock*/ GetState()1181 PVMFMediaClockState GetState() 1182 { 1183 return iState; 1184 } 1185 1186 1187 protected: 1188 1189 friend class PVMFMediaClockNotificationsInterfaceImpl; 1190 1191 //start PVMFMediaClockNotificationsImplInterface functions 1192 /** 1193 Sets an observer for this clock. May leave if memory allocation fails. 1194 @param aObserver: the observer implemenation 1195 */ 1196 OSCL_IMPORT_REF void SetClockObserver(PVMFMediaClockObserver& aObserver); 1197 1198 /** 1199 Removes an observer for this clock. If the observer is not registered, this 1200 call does nothing. 1201 @param aObserver: the observer implemenation 1202 */ 1203 OSCL_IMPORT_REF void RemoveClockObserver(PVMFMediaClockObserver& aObserver); 1204 1205 /** 1206 Sets an observer for this clock. May leave if memory allocation fails. 1207 @param aObserver: the observer implemenation 1208 */ SetClockStateObserver(PVMFMediaClockStateObserver & aObserver)1209 void SetClockStateObserver(PVMFMediaClockStateObserver& aObserver) 1210 {/*Dummy function*/ 1211 OSCL_UNUSED_ARG(aObserver); 1212 } 1213 /** 1214 Removes an observer for this clock. If the observer is not registered, this 1215 call does nothing. 1216 @param aObserver: the observer implemenation 1217 */ RemoveClockStateObserver(PVMFMediaClockStateObserver & aObserver)1218 void RemoveClockStateObserver(PVMFMediaClockStateObserver& aObserver) 1219 {/*Dummy function*/ 1220 OSCL_UNUSED_ARG(aObserver); 1221 } 1222 1223 1224 PVMFStatus SetCallbackAbsoluteTime( 1225 /*IN*/ uint32 aAbsoluteTime, 1226 /*IN*/ uint32 aWindow, 1227 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 1228 /*IN*/ bool aThreadLock, 1229 /*IN*/ const OsclAny* aContextData, 1230 /*OUT*/ uint32& aCallBackID, 1231 /*IN*/ const OsclAny* aInterfaceObject); 1232 1233 PVMFStatus SetCallbackDeltaTime( 1234 /*IN*/ uint32 aDeltaTime, 1235 /*IN*/ uint32 aWindow, 1236 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 1237 /*IN*/ bool aThreadLock, 1238 /*IN*/ const OsclAny* aContextData, 1239 /*OUT*/ uint32& aCallBackID, 1240 /*IN*/ const OsclAny* aInterfaceObject); 1241 1242 PVMFStatus CancelCallback( 1243 /*IN*/ uint32 aCallbackID, bool aThreadLock); 1244 1245 PVMFStatus SetNPTCallbackAbsoluteTime( 1246 /*IN*/ uint32 aAbsoluteTime, 1247 /*IN*/ uint32 aWindow, 1248 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 1249 /*IN*/ bool aThreadLock, 1250 /*IN*/ const OsclAny* aContextData, 1251 /*OUT*/ uint32& aCallBackID, 1252 /*IN*/ const OsclAny* aInterfaceObject); 1253 1254 PVMFStatus SetNPTCallbackDeltaTime( 1255 /*IN*/ uint32 aDeltaTime, 1256 /*IN*/ uint32 aWindow, 1257 /*IN*/ PVMFMediaClockNotificationsObs* aObs, 1258 /*IN*/ bool aThreadLock, 1259 /*IN*/ const OsclAny* aContextData, 1260 /*OUT*/ uint32& aCallBackID, 1261 /*IN*/ const OsclAny* aInterfaceObject); 1262 1263 PVMFStatus CancelNPTCallback( 1264 /*IN*/ uint32 aCallbackID, bool aThreadLock); 1265 1266 //End PVMFMediaClockNotificationsInterface 1267 /** 1268 Changes the clock's state to the specified state 1269 @param aState: the new state to change to 1270 */ 1271 void SetClockState(PVMFMediaClockState aState); 1272 /** 1273 Updates the iLatestTime and iLatestSourceVal to specified values 1274 @param aTime: the new iLatestTime value to change to 1275 @param aSourceVal: the new iLatestSourceVal value to change to 1276 */ 1277 void UpdateLatestTimes(uint32 aTime, uint32 aSourceVal); 1278 1279 /* Gets delta between iStartTimebaseTickValue and current tickcount*/ 1280 void GetScaledTimebaseTickCount(uint32& aScaledTickCount, bool& aOverFlow); 1281 /** 1282 Updates the iLatestRunningClockTime and iLatestRunningTimebaseTime to new units 1283 */ 1284 void AdjustClockInternalsToNewUnits(bool& aOverFlow); 1285 /** 1286 Converts a time value in the specified time units to microseconds 1287 @param aSrcVal: unsigned 32-bit time value in units specified by aSrcUnits 1288 @param aSrcUnits: time units of aSrcVal 1289 @param aUSecVal: reference to unsigned 32-bit integer to store the microsecond time value 1290 */ 1291 void ToClockUnit(uint32& aSrcVal, PVMFMediaClock_TimeUnits aSrcUnits, uint32& aDestVal, bool& aOverFlow); 1292 /** 1293 Converts a millisecond time value to the specified time units 1294 @param aUSecVal: unsigned 32-bit integer in microsecond time value 1295 @param aDstVal: reference to unsigned 32-bit integer which will contain aUSecVal in the 1296 specified aDstUnits time units 1297 @param aDstUnits: requested time units for aDstVal 1298 */ 1299 1300 void FromClockUnit(uint32& aClockUnitVal, uint32& aDstVal, 1301 PVMFMediaClock_TimeUnits aDstUnits, bool& aOverFlow); 1302 1303 /** 1304 Converts a time value in the specified time units to microseconds 1305 @param aSrcVal: unsigned 32-bit time value in units specified by aSrcUnits 1306 @param aSrcUnits: time units of aSrcVal 1307 @param aUSecVal: reference to unsigned 32-bit integer to store the microsecond time value 1308 */ 1309 void ToUSec(uint32& aSrcVal, PVMFMediaClock_TimeUnits aSrcUnits, 1310 uint32& aUSecVal, bool& aOverflow); 1311 1312 /** 1313 Converts timebase ticks to clock units 1314 @param aDelta: unsigned 32-bit tickcount value 1315 @param aDeltaTime: reference to unsigned 32-bit integer to store time 1316 */ 1317 void ConvertTickcountToClockUnits(uint32 aTickcount, uint32& aTimeValue, bool& aOverflowFlag); 1318 /** 1319 Updates the internal clock parameters based on the adjustment information provided. 1320 This function can be overridden in the derived classes to allow variety in the adjustment algorithm 1321 @param aObsTime: unsigned 32-bit integer in microsecond for the observed clock time 1322 @param aObsTimebase: unsigned 32-bit integer in microsecond for the observed timebase time 1323 @param aAdjTime: unsigned 32-bit integer in microsecond for the adjusted clock time 1324 @param aCurrentTime: unsigned 32-bit integer in microsecond for the current clock time 1325 @param aCurrentTimebase: unsigned 32-bit integer in microsecond for the current timebase time 1326 */ 1327 virtual PVMFMediaClockAdjustTimeStatus AdjustClock(uint32& aObsTime, uint32& aObsTimebase, uint32& aAdjTime, 1328 uint32& aCurrentTime, uint32& aCurrentTimebase); 1329 1330 /** 1331 Returns the adjusted current clock time when the clock is running 1332 This function can be overridden in the derived classes to allow variety in the adjustment algorithm 1333 @param aDstTime: unsigned 32-bit integer in microseconds to output the adjusted current clock time 1334 @param aTimebaseVal: unsigned 32-bit integer in microseconds of the current timebase time 1335 */ 1336 virtual void GetAdjustedRunningClockTime(uint32& aDstTime, uint32& aTimebaseVal); 1337 1338 //Possible units for time keeping 1339 enum PVMFMediaClock_ClockUnit 1340 { 1341 PVMF_MEDIA_CLOCK_CLOCKUNIT_USEC = 0, 1342 PVMF_MEDIA_CLOCK_CLOCKUNIT_MSEC = 1 1343 }; 1344 1345 PVLogger* iLogger; 1346 1347 1348 // Timebase time is stored as unsigned 32-bit value in microseconds 1349 uint32 iLatestRunningClockTime; // Last reference clock time due to starting/resuming, pausing, and adjustment 1350 uint32 iLatestRunningTimebaseTime; // Timebase time corresponding to the latest running clock time 1351 uint32 iStartTimebaseTickValue; // Timebase tick value at clock start time. 1352 uint32 iStartClockTime; // Starting clock time. Set by the SetStartTime...() APIs 1353 uint32 iPauseClockTime; // Clock time when Pause() API is called. 1354 uint32 iLastAdjustObsTimebaseTime; // The observed timebase time corresponding to the adjusted time passed in 1355 uint32 iAdjustmentTimebaseTime; // The timebase time of the last successful AdjustClockTime...() call 1356 PVMFMediaClock_ClockUnit iClockUnit; // unit of above values in clock implementation 1357 PVMFMediaClock_ClockUnit iPreviousClockUnit; // unit of above values in clock implementation 1358 1359 PVMFMediaClockState iState; // Internal state of the clock 1360 1361 PVMFTimebase* iClockTimebase; // Pointer to this clock's timebase 1362 1363 //vector of clock observers. 1364 Oscl_Vector<PVMFMediaClockObserver*, OsclMemAllocator> iClockObservers; 1365 1366 //from PVMFMediaClockObserver, for callbacks from an PVMFCountTimebase. 1367 void ClockCountUpdated(); 1368 void ClockTimebaseUpdated(); 1369 void ClockAdjusted(); 1370 1371 // for NPT mapping 1372 bool iIsNPTPlayBackDirectionBackwards; 1373 PVMFTimestamp iStartNPT; 1374 PVMFTimestamp iStartMediaClockTS; 1375 1376 //for npt transition queueing 1377 Oscl_Vector<PVMFMediaClockNPTTransitionEventElement, OsclMemAllocator> iNPTTransitionEventQueue; 1378 1379 //for clock-start notification event queuing 1380 Oscl_Vector<PVMFMediaClockStartNotificationEventElement, OsclMemAllocator> iClockStartNotificationEventQueue; 1381 1382 //vector of PVMFMediaClockNotificationsInterfaceImpl objects. Each object represents a session 1383 Oscl_Vector<PVMFMediaClockNotificationsInterfaceImpl*, OsclMemAllocator> iMediaClockSetCallbackObjects; 1384 1385 //callback related functions, members 1386 1387 OsclPriorityQueue < PVMFMediaClockTimerQueueElement, OsclMemAllocator, Oscl_Vector<PVMFMediaClockTimerQueueElement, OsclMemAllocator>, 1388 PVMFMediaClockTimerQueueCompareLess > iTimersPriQueue; 1389 1390 //Mutex for multithreading support 1391 OsclMutex *iMutex; 1392 1393 //For keeping count of active timers 1394 uint32 iActiveTimersCount; 1395 1396 //For keeping track of timer ID count. 1397 uint32 iTimerIDCount; 1398 1399 //This stores the current thread ID when clock is constructed. 1400 TOsclThreadId iOrigThreadID; 1401 1402 // Variables to be used when timebase is swapped. 1403 int32 iLastTimebaseRate; 1404 1405 bool iIsTimebaseCountBased; 1406 1407 //common setCallback() for regular and NPT timers 1408 PVMFStatus SetCallbackCommon(uint32 aDeltaTime, uint32 aWindow, 1409 PVMFMediaClockNotificationsObs* aCallback, bool aThreadLock, const OsclAny* aContextData, 1410 uint32& aCallBackID, const OsclAny* aInterfaceObject, uint32 aCurrentTime, bool aIsNPT); 1411 1412 //common CancelCallback() for regular and NPT timers 1413 PVMFStatus CommonCancelCallback(uint32 aCallbackID, bool aThreadLock, bool aIsNPT); 1414 1415 //This function adjusts latencies of all PVMFMediaClockNotificationsInterfaceImpl objects 1416 //stored in the vector by subtracting largest common latency from all. 1417 void AdjustLatenciesOfSinks(); 1418 1419 /** 1420 This is a generic function for doing fresh scheduling of PVMFMediaClock object 1421 This function is called when a new callback is created. a callback is cancelled or 1422 when clock state changes. 1423 @param aIsNPT: signifies if aCurrentTime is NPT time 1424 @param aCurrentTime: This is passed for optimization. More often than not, the calling 1425 function has the current time value. If no argument is supplied, GetCurrentTime() is called. 1426 */ 1427 void AdjustScheduling(bool aIsNPT = false, uint32 aCurrentTime = 0); 1428 1429 //for AO 1430 void Run(); 1431 1432 //Destoys all callback interface objects created. This is called from the destructor. 1433 void CleanCallbackInfImplObjects(); 1434 1435 /** 1436 This function calculates the optimum time period after which Run() should be called. 1437 @param aIsNPT: signifies if aCurrentTime is NPT time 1438 @param aCurrentTime: This is passed for optimization as calling function has current time value. 1439 @param aDelta: Time value to be passed in RunIfNotActive() 1440 */ 1441 void CalculateRunLTimerValue(bool aIsNPT, uint32 aCurrentTime, int32& aDelta); 1442 1443 //NPT callbacks related members 1444 OsclPriorityQueue < PVMFMediaClockTimerQueueElement, OsclMemAllocator, Oscl_Vector<PVMFMediaClockTimerQueueElement, OsclMemAllocator>, 1445 PVMFMediaClockTimerQueueCompareLess > iTimersPriQueueNPT; 1446 1447 OsclPriorityQueue < PVMFMediaClockTimerQueueElement, OsclMemAllocator, Oscl_Vector<PVMFMediaClockTimerQueueElement, OsclMemAllocator>, 1448 PVMFMediaClockTimerQueueCompareLessForNPTBackwards > iTimersPriQueueNPTBackwards; 1449 1450 //For flushing out queue when playback direction changes. This is done with NPT clock 1451 void ClearPresentNPTQueue(); 1452 1453 void ClearAllQueues(); 1454 1455 //From PVMFMediaClockNotificationsObs interface 1456 void ProcessCallBack(uint32 aCallBackID, PVTimeComparisonUtils::MediaTimeStatus aTimerAccuracy, uint32 delta, 1457 const OsclAny* acontextData, PVMFStatus aStatus); 1458 void NotificationsInterfaceDestroyed(); 1459 1460 void QueueClockStartNotificationEvent(uint32 aDelta, PVMFMediaClockStateObserver *aClockStateObserver); 1461 }; 1462 1463 /** 1464 PVMFTimebase_Tickcount is PVMFTimebase-derived class which uses 1465 the OSCL's system tickcount as the timebase. This class is provided 1466 as the default PVMFTimebase that is available on any platform with OSCL support. 1467 */ 1468 class OSCL_IMPORT_REF PVMFTimebase_Tickcount : public PVMFTimebase 1469 { 1470 public: 1471 /** 1472 Constructor. Retrieves the constant to convert OSCL tickcount value to microseconds 1473 */ PVMFTimebase_Tickcount()1474 PVMFTimebase_Tickcount() 1475 { 1476 iMicrosecPerTick = OsclTickCount::TickCountPeriod(); 1477 iPrevTickcount = 0; 1478 } 1479 1480 /** 1481 Destructor 1482 */ ~PVMFTimebase_Tickcount()1483 ~PVMFTimebase_Tickcount() 1484 { 1485 } 1486 1487 // From PVMFTimebase 1488 /** 1489 Returns the OSCL tickcount's time resolution in microseconds 1490 Implementation of virtual function from PVMFTimebase 1491 @param aResolution: On function completion, contains OSCL tickcount resolution 1492 */ GetTimebaseResolution(uint32 & aResolution)1493 void GetTimebaseResolution(uint32& aResolution) 1494 { 1495 aResolution = iMicrosecPerTick; 1496 } GetRate(void)1497 int32 GetRate(void) 1498 { 1499 return REALTIME_PLAYBACK_RATE; 1500 } 1501 OSCL_IMPORT_REF void GetCurrentTick32(uint32& aTimebaseTickCount, bool& aOverflow); 1502 OSCL_IMPORT_REF void GetCurrentTime32(uint32& aTime, bool& aOverflow, PVMFMediaClock_TimeUnits aUnits); 1503 GetCountTimebase()1504 PVMFCountTimebase* GetCountTimebase() 1505 { 1506 return NULL; 1507 } 1508 1509 protected: 1510 uint32 iMicrosecPerTick; 1511 uint32 iPrevTickcount; 1512 1513 }; 1514 1515 /** 1516 PVMFTimebase_Count is PVMFTimebase-derived class that can be used to 1517 implement a simple count-based timebase. 1518 */ 1519 class PVMFTimebase_Count : public PVMFTimebase, public PVMFCountTimebase 1520 { 1521 public: 1522 /** 1523 Constructor. 1524 */ PVMFTimebase_Count()1525 PVMFTimebase_Count() 1526 { 1527 iCurrentCount = 0; 1528 iObserver = NULL; 1529 } 1530 1531 /** 1532 Destructor 1533 */ ~PVMFTimebase_Count()1534 ~PVMFTimebase_Count() 1535 { 1536 } 1537 1538 // From PVMFTimebase 1539 /** 1540 Returns the OSCL tickcount's time resolution in microseconds 1541 Implementation of virtual function from PVMFTimebase 1542 @param aResolution: On function completion, contains OSCL tickcount resolution 1543 */ GetTimebaseResolution(uint32 & aResolution)1544 void GetTimebaseResolution(uint32& aResolution) 1545 { 1546 aResolution = 0; //not meaningful for a count-based timebase. 1547 } 1548 GetRate(void)1549 int32 GetRate(void) 1550 { 1551 return 0; //not meaningful for a count-based timebase. 1552 } 1553 /** 1554 Returns the current clock time as unsigned 32-bit integer object in the specified time units 1555 @param aTime: a reference to an unsigned 32-bit integer to return the current time 1556 @param aUnits: the requested time units for aTime 1557 @param aTimebaseTime: a reference to an unsigned 32-bit integer to return the timebase time 1558 */ GetCurrentTick32(uint32 & aTick,bool & aOverflow)1559 void GetCurrentTick32(uint32& aTick, bool& aOverflow) 1560 { 1561 //not meaningful for a count-based timebase. 1562 aTick = 0; 1563 aOverflow = false; 1564 } 1565 /** 1566 Returns the PVMFCountTimebase implementation pointer 1567 */ GetCountTimebase()1568 PVMFCountTimebase* GetCountTimebase() 1569 { 1570 return this; 1571 } 1572 1573 //From PVMFCountTimebase 1574 /** 1575 Used to adjust the current count. 1576 @param aCount (input): new count value. 1577 */ SetCount(int32 aCount)1578 void SetCount(int32 aCount) 1579 { 1580 iCurrentCount = aCount; 1581 if (iObserver) 1582 { 1583 iObserver->ClockCountUpdated(); 1584 } 1585 } 1586 1587 /** 1588 Used to retreive the current count. 1589 @param aCount (output): new count value. 1590 */ GetCount(int32 & aCount)1591 void GetCount(int32& aCount) 1592 { 1593 aCount = iCurrentCount; 1594 } 1595 1596 protected: 1597 int32 iCurrentCount; 1598 PVMFMediaClockObserver* iObserver; 1599 1600 private: 1601 friend class PVMFMediaClock; 1602 //From PVMFCountTimebase SetClockObserver(PVMFMediaClockObserver * aObserver)1603 void SetClockObserver(PVMFMediaClockObserver* aObserver) 1604 { 1605 iObserver = aObserver; 1606 } 1607 1608 }; 1609 #endif //PVMF_MEDIA_CLOCK_H_INCLUDED 1610