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 * ============================================================================== 20 * Name : pv_player_interface.h 21 * Part of : 22 * Interface : 23 * Description : Interface class and supporting definitions for the pvPlayer engine 24 * Version : (see RELEASE field in copyright header above) 25 * 26 * ============================================================================== 27 */ 28 29 #ifndef PV_PLAYER_INTERFACE_H_INCLUDED 30 #define PV_PLAYER_INTERFACE_H_INCLUDED 31 32 33 // INCLUDES 34 #ifndef OSCL_BASE_H_INCLUDED 35 #include "oscl_base.h" 36 #endif 37 38 #ifndef OSCL_STRING_H_INCLUDED 39 #include "oscl_string.h" 40 #endif 41 42 #ifndef OSCL_VECTOR_H_INCLUDED 43 #include "oscl_vector.h" 44 #endif 45 46 #ifndef OSCL_MEM_H_INCLUDED 47 #include "oscl_mem.h" 48 #endif 49 50 #ifndef PVLOGGER_H_INCLUDED 51 #include "pvlogger.h" 52 #endif 53 54 #ifndef PVMF_RETURN_CODES_H_INCLUDED 55 #include "pvmf_return_codes.h" 56 #endif 57 58 #ifndef PV_ENGINE_TYPES_H_INCLUDED 59 #include "pv_engine_types.h" 60 #endif 61 62 #ifndef PV_PLAYER_TYPES_H_INCLUDED 63 #include "pv_player_types.h" 64 #endif 65 66 #ifndef PV_PLAYER_EVENTS_H_INCLUDED 67 #include "pv_player_events.h" 68 #endif 69 70 #ifndef PV_PLAYER_DATASOURCE_H_INCLUDED 71 #include "pv_player_datasource.h" 72 #endif 73 74 #ifndef PV_PLAYER_DATASINK_H_INCLUDED 75 #include "pv_player_datasink.h" 76 #endif 77 78 #ifndef PVMI_KVP_H_INCLUDED 79 #include "pvmi_kvp.h" 80 #endif 81 82 #ifndef PVMF_MEDIA_CLOCK_H_INCLUDED 83 #include "pvmf_media_clock.h" 84 #endif 85 86 87 // CLASS DECLARATION 88 /** 89 * PVPlayerInterface is the interface to the pvPlayer SDK, which 90 * allows control of a multimedia playback engine. 91 * The PVPlayerFactory factory class is to be used to create and 92 * delete instances of this object 93 **/ 94 class PVPlayerInterface 95 { 96 public: 97 98 /** 99 * Object destructor function 100 * Releases all resources prior to destruction 101 **/ 102 virtual ~PVPlayerInterface() {}; 103 104 /** 105 * Returns information about all modules currently used by pvPlayer SDK. 106 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 107 * callback handler will be called when this command request completes. 108 * 109 * @param aSDKModuleInfo 110 * A reference to a PVSDKModuleInfo structure which contains the number of modules currently used by 111 * pvPlayer SDK and the PV UUID and description string for each module. The PV UUID and description string 112 * for modules will be returned in one string buffer allocated by the client. If the string buffer 113 * is not large enough to hold the all the module's information, the information will be written 114 * up to the length of the buffer and truncated. 115 * @param aContextData 116 * Optional opaque data that will be passed back to the user with the command response 117 * @leave This method can leave with one of the following error codes 118 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 119 * @returns A unique command ID for asynchronous completion 120 **/ 121 virtual PVCommandId GetSDKModuleInfo(PVSDKModuleInfo &aSDKModuleInfo, const OsclAny* aContextData = NULL) = 0; 122 123 /** 124 * Allows a logging appender to be attached at some point in the 125 * logger tag tree. The location in the tag tree is specified by the 126 * input tag string. A single appender can be attached multiple times in 127 * the tree, but it may result in duplicate copies of log messages if the 128 * appender is not attached in disjoint portions of the tree. 129 * A logging appender is responsible for actually writing the log message 130 * to its final location (e.g., memory, file, network, etc). 131 * This API can be called anytime after creation of pvPlayer. 132 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 133 * callback handler will be called when this command request completes. 134 * 135 * @param aTag 136 * Specifies the logger tree tag where the appender should be attached. 137 * @param aAppender 138 * The log appender to attach. 139 * @param aContextData 140 * Optional opaque data that will be passed back to the user with the command response 141 * @exception This method can leave with one of the following error codes 142 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 143 * @returns A unique command ID for asynchronous completion 144 **/ 145 virtual PVCommandId SetLogAppender(const char* aTag, OsclSharedPtr<PVLoggerAppender>& aAppender, const OsclAny* aContextData = NULL) = 0; 146 147 /** 148 * Allows a logging appender to be removed from the logger tree at the 149 * point specified by the input tag. If the input tag is NULL then the 150 * appender will be removed from locations in the tree. 151 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 152 * callback handler will be called when this command request completes. 153 * 154 * @param aTag 155 * Specifies the logger tree tag where the appender should be removed. 156 * Can be NULL to remove at all locations. 157 * @param aAppender 158 * The log appender to remove. 159 * @param aContextData 160 * Optional opaque data that will be passed back to the user with the command response 161 * 162 * @exception This method can leave with one of the following error codes 163 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 164 * @returns A unique command ID for asynchronous completion 165 **/ 166 virtual PVCommandId RemoveLogAppender(const char* aTag, OsclSharedPtr<PVLoggerAppender>& aAppender, const OsclAny* aContextData = NULL) = 0; 167 168 /** 169 * Allows the logging level to be set for the logging node specified by the 170 * tag. A larger log level will result in more messages being logged. A message 171 * will only be logged if its level is LESS THAN or equal to the current log level. 172 * The aSetSubtree flag will allow an entire subtree, with the specified tag as the root, 173 * to be reset to the specified value. 174 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 175 * callback handler will be called when this command request completes. 176 * 177 * @param aTag 178 * Specifies the logger tree tag where the log level should be set. 179 * @param aLevel 180 * Specifies the log level to set. 181 * @param aSetSubtree 182 * Specifies whether the entire subtree with aTag as the root should 183 * be reset to the log level. 184 * @param aContextData 185 * Optional opaque data that will be passed back to the user with the command response 186 * 187 * @exception This method can leave with one of the following error codes 188 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 189 * @returns A unique command ID for asynchronous completion 190 **/ 191 virtual PVCommandId SetLogLevel(const char* aTag, int32 aLevel, bool aSetSubtree = false, const OsclAny* aContextData = NULL) = 0; 192 193 /** 194 * Allows the logging level to be queried for a particular logging tag. 195 * A larger log level will result in more messages being logged. 196 * In the asynchronous response, this should return the log level along with an 197 * indication of where the level was inherited (i.e., the ancestor tag). 198 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 199 * callback handler will be called when this command request completes. 200 * 201 * @param aTag 202 * Specifies the logger tree tag where the log level should be retrieved. 203 * @param aLogInfo 204 * An output parameter which will be filled in with the log level information. 205 * @param aContextData 206 * Optional opaque data that will be passed back to the user with the command response 207 * @exception This method can leave with one of the following error codes 208 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 209 * @returns A unique command ID for asynchronous completion 210 **/ 211 virtual PVCommandId GetLogLevel(const char* aTag, PVLogLevelInfo& aLogInfo, const OsclAny* aContextData = NULL) = 0; 212 213 /** 214 * This API is to allow for extensibility of the pvPlayer interface. 215 * It allows a caller to ask for all UUIDs associated with a particular MIME type. 216 * If interfaces of the requested MIME type are found within the system, they are added 217 * to the UUIDs array. 218 * Also added to the UUIDs array will be all interfaces which have the requested MIME 219 * type as a base MIME type. This functionality can be turned off. 220 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 221 * callback handler will be called when this command request completes. 222 * 223 * @param aMimeType 224 * The MIME type of the desired interfaces 225 * @param aUuids 226 * An array to hold the discovered UUIDs 227 * @param aExactUuidsOnly 228 * Turns on/off the retrival of UUIDs with aMimeType as a base type 229 * @param aContextData 230 * Optional opaque data that will be passed back to the user with the command response 231 * 232 * @exception This method can leave with one of the following error codes 233 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 234 * @returns A unique command ID for asynchronous completion 235 **/ 236 virtual PVCommandId QueryUUID(const PvmfMimeString& aMimeType, Oscl_Vector<PVUuid, OsclMemAllocator>& aUuids, 237 bool aExactUuidsOnly = false, const OsclAny* aContextData = NULL) = 0; 238 /** 239 * This API is to allow for extensibility of the pvPlayer interface. 240 * It allows a caller to ask for an instance of a particular interface object to be returned. 241 * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with 242 * an interface ID that is a UUID as in DCE and a pointer to the interface object is 243 * returned if it is supported. Otherwise the returned pointer is NULL. 244 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 245 * callback handler will be called when this command request completes. 246 * 247 * @param aUuid 248 * The UUID of the desired interface 249 * @param aInterfacePtr 250 * A reference to the output pointer to the desired interface 251 * @param aContextData 252 * Optional opaque data that will be passed back to the user with the command response 253 254 * @exception This method can leave with one of the following error codes 255 * OsclErrNotSupported if the specified interface UUID is not supported 256 * @returns A unique command ID for asynchronous completion 257 **/ 258 virtual PVCommandId QueryInterface(const PVUuid& aUuid, PVInterface*& aInterfacePtr, const OsclAny* aContextData = NULL) = 0; 259 260 /** 261 * This API is to allow user of the SDK to cancel any specific command which is pending on pvPlayer. 262 * If the request is to cancel a command which still has to be processed pvPlayer will just remove 263 * the command from its queue of commands to be processed. If the request is to cancel a command that 264 * is ongoing then player will attempt to interrupt the ongoing command. The state of player after a cancel 265 * can vary. So the user of pvPlayerSDK must always query for state before issuing any subsequent 266 * commands. 267 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 268 * callback handler will be called when this command request completes. 269 * 270 * @param aCancelCmdId 271 * Command Id to be cancelled. 272 * @param aContextData 273 * Optional opaque data that will be passed back to the user with the command response 274 * @returns A unique command id for asynchronous completion 275 **/ 276 virtual PVCommandId CancelCommand(PVCommandId aCancelCmdId, const OsclAny* aContextData = NULL) = 0; 277 278 /** 279 * This API is to allow the user to cancel all pending requests in pvPlayer. The current request being 280 * processed, if any, will also be aborted. The user of PV-SDK should get the state of 281 * PVPlayer Engine after the command completes and before issuing any other command. 282 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 283 * callback handler will be called when this command request completes. 284 * 285 * @param aContextData 286 * Optional opaque data that will be passed back to the user with the command response 287 * @returns A unique command id for asynchronous completion 288 **/ 289 virtual PVCommandId CancelAllCommands(const OsclAny* aContextData = NULL) = 0; 290 291 /** 292 * This function returns the current state of pvPlayer. 293 * Application may use this info for updating display or determine if the 294 * pvPlayer is ready for the next request. 295 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 296 * callback handler will be called when this command request completes. 297 * 298 * @param aState 299 * A reference to a PVPlayerState. Upon successful completion of this command, 300 * it will contain the current state of pvPlayer. 301 * @param aContextData 302 * Optional opaque data that will be passed back to the user with the command response 303 * @returns A unique command id for asynchronous completion 304 **/ 305 virtual PVCommandId GetPVPlayerState(PVPlayerState& aState, const OsclAny* aContextData = NULL) = 0; 306 307 /** 308 * This function returns the current state of pvPlayer as a synchronous command. 309 * Application may use this info for updating display or determine if the 310 * pvPlayer is ready for the next request. 311 * 312 * @param aState 313 * A reference to a PVPlayerState. Upon successful completion of this command, 314 * it will contain the current state of pvPlayer. 315 * @returns Status indicating whether the command succeeded or not. 316 **/ 317 virtual PVMFStatus GetPVPlayerStateSync(PVPlayerState& aState) = 0; 318 319 /** 320 * This function allows a player data source to be specified for playback. This function must be called 321 * when pvPlayer is in PVP_STATE_IDLE state and before calling Init. The specified data source must be a valid PVPlayerDataSource to 322 * be accepted for use in playback. 323 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 324 * callback handler will be called when this command request completes. 325 * 326 * @param aDataSource 327 * Reference to the player data source to be used for playback 328 * @param aContextData 329 * Optional opaque data that will be passed back to the user with the command response 330 * @leave This method can leave with one of the following error codes 331 * OsclErrNotSupported if the format of the source is incompatible with what the SDK can handle 332 * OsclErrInvalidState if invoked in the incorrect state 333 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 334 * @return A unique command id for asynchronous completion 335 */ 336 virtual PVCommandId AddDataSource(PVPlayerDataSource& aDataSource, const OsclAny* aContextData = NULL) = 0; 337 338 /** 339 * This function switches pvPlayer from PVP_STATE_IDLE state to the PVP_STATE_INITIALIZED state. 340 * During the transition, pvPlayer is in the PVP_STATE_INITIALIZING transitional state and 341 * the data source is being initialized to obtain metadata and track information of the source media. 342 * If initialization fails, pvPlayer will revert to PVP_STATE_IDLE state and the data source 343 * will be closed. 344 * The Command should only be called in PVP_STATE_IDLE. 345 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 346 * callback handler will be called when this command request completes. 347 * 348 * @param aContextData 349 * Optional opaque data that will be passed back to the user with the command response 350 * @leave This method can leave with one of the following error codes 351 * OsclErrInvalidState if invoked in the incorrect state 352 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 353 * @returns A unique command id for asynchronous completion 354 **/ 355 virtual PVCommandId Init(const OsclAny* aContextData = NULL) = 0; 356 357 /** 358 * This function makes a request to return the list of all or segment of available metadata keys in the current pvPlayer state. 359 * The metadata key list is dynamic and can change during the course of pvPlayer usage. 360 * The list can be used to retrieve the metadata values with GetMetadataValues function. 361 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 362 * callback handler will be called when this command request completes. 363 * 364 * @param aKeyList 365 * Reference to a vector to place the metadata key list. 366 * @param aStartingIndex 367 * Input parameter to specify the starting index for aKeyList. This parameter along with aMaxEntries 368 * allows us to retrieve the metadata key list in segments. 369 * @param aMaxEntries 370 * Input parameter to specify the maximum number of entries to be added to aKeyList. If there is no limit, set to -1. 371 * @param aQueryKey 372 * Input parameter to narrow down the list of requested keys. For example, 373 * "track-info/video" indicates all keys related to "track-info/video". for eg: 374 * "track-info/video/width" "track-info/video/height". A NULL value indicates that all 375 * keys are requested. 376 * @param aContextData 377 * Optional opaque data that will be passed back to the user with the command response 378 * @leave This method can leave with one of the following error codes 379 * OsclErrInvalidState if invoked in the incorrect state 380 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 381 * @returns A unique command id for asynchronous completion 382 **/ 383 virtual PVCommandId GetMetadataKeys(PVPMetadataList& aKeyList, int32 aStartingIndex = 0, int32 aMaxEntries = -1, 384 char* aQueryKey = NULL, const OsclAny* aContextData = NULL) = 0; 385 386 /** 387 * The function makes a request to return the metadata value(s) specified by the passed in metadata key list. 388 * If the requeted metadata value is unavailable or the metadata key is invalid, the returned list will not contain 389 * a KVP entry for the key. Note that value indexed in the returned aValueList does not necessary match the same index into 390 * the specified aKeyList since this command can return none or more than one KVP for a specified key. 391 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 392 * callback handler will be called when this command request completes. 393 * 394 * @param aKeyList 395 * Reference to a list of metadata keys for which metadata values are requested. 396 * @param aStartingValueIndex 397 * The starting index refers to the an index into the whole value list specified by the keys in aKeyList. This command 398 * would populate the aValueList starting from the specified index. 399 * @param aMaxValueEntries 400 * Input parameter to specify the maximum number of entries to be added to aValueList. If there is no limit, set to -1. 401 * @param aNumAvailableValueEntries 402 * Output parameter which will be filled with number of available values for the specified key list. 403 * @param aValueList 404 * Reference to a vector of KVP to place the specified metadata values 405 * @param aContextData 406 * Optional opaque data that will be passed back to the user with the command response 407 * @param aMetadataValuesCopiedInCallBack 408 * Boolean to let engine know if metadata values are copied by User of SDK in command complete callback. 409 * By default the SDK assumes this to be the case. If this argument is set to false by the caller, 410 * then SDK assumes that user will call ReleaseMetaDataValues at a later point. 411 * @leave This method can leave with one of the following error codes 412 * OsclErrInvalidState if invoked in the incorrect state 413 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 414 * @returns A unique command id for asynchronous completion 415 **/ 416 virtual PVCommandId GetMetadataValues(PVPMetadataList& aKeyList, int32 aStartingValueIndex, int32 aMaxValueEntries, int32& aNumAvailableValueEntries, 417 Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList, const OsclAny* aContextData = NULL, bool aMetadataValuesCopiedInCallBack = true) = 0; 418 419 /** 420 * The function makes a request to release the metadata value(s) specified by the passed in metadata value list. 421 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 422 * callback handler will be called when this command request completes.If a GetMetaDataValues were called in 423 * PVP_STATE_INITIALIZED state, then corresponding ReleaseMetaDataValues must be called before Reset. 424 * If a GetMetaDataValues were called in PVP_STATE_PREPARED, PVP_STATE_STARTED, PVP_STATE_PAUSED states, 425 * then corresponding ReleaseMetaDataValues must be called before Stop. 426 * 427 * @param aValueList 428 * Reference to a vector of KVP to place the specified metadata values 429 * @param aContextData 430 * Optional opaque data that will be passed back to the user with the command response 431 * @leave This method can leave with one of the following error codes 432 * OsclErrInvalidState if invoked in the incorrect state 433 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 434 * @returns A unique command id for asynchronous completion 435 **/ 436 virtual PVCommandId ReleaseMetadataValues(Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList, const OsclAny* aContextData = NULL) = 0; 437 438 /** 439 * This function allows a player data sink to be specified for playback. This function must be called 440 * when pvPlayer is in PVP_STATE_INITIALIZED state. The specified data sink must be a valid PVPlayerDataSink to 441 * be accepted for use in playback. 442 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 443 * callback handler will be called when this command request completes. 444 * 445 * @param aDataSink 446 * The player data sink to be used for playback. 447 * @param aContextData 448 * Optional opaque data that will be passed back to the user with the command response 449 * @leave This method can leave with one of the following error codes 450 * OsclErrNotSupported if the format of the sink is incompatible with what the SDK can handle 451 * OsclErrInvalidState if invoked in the incorrect state 452 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 453 * @return A unique command id for asynchronous completion 454 **/ 455 virtual PVCommandId AddDataSink(PVPlayerDataSink& aDataSink, const OsclAny* aContextData = NULL) = 0; 456 457 /** 458 * This function sets the begin and end positions for the new playback range or changes the end position of the 459 * current playback range. This function must be called when pvPlayer is in PVP_STATE_INITIALIZED, PVP_STATE_PREPARED, 460 * PVP_STATE_STARTED, or PVP_STATE_PAUSED state. The specified positions must be between beginning of clip and 461 * clip duration. The units of position is specified in the passed-in parameter PVPPlaybackPosition. 462 * If either of the positions is indeterminate, use the indeterminate flag in PVPPlaybackPosition structure. 463 * The queued playback range can be done using aQueueRange flag which is Not Supported as of now by PV-SDK. 464 * This function will overwrite any previous playback range info. The only exception is the changing of end position 465 * for the current playback range during playback. 466 * Command if called in player state as PVP_STATE_INITIALISED or PVP_STATE_PAUSED, will complete in one Engine AO run without actually 467 * changing the position. The change in position will come into affect when Prepare or Resume respectively is called on Engine by the app. 468 * If reposition request is not honored by the source node during Prepare or Resume, engine will continue to complete Prepare or Resume 469 * but will send an informational event "PVMFInfoChangePlaybackPositionNotSupported" to the app informing that the SetPlaybackRange request 470 * could not be honored. 471 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 472 * callback handler will be called when this command request completes. 473 * 474 * @param aBeginPos 475 * Beginning position for the new playback range 476 * @param aEndPos 477 * Ending position for the new playback range. 478 * @param aQueueRange 479 * Input flag to tell pvPlayer to queue the new playback range (Set/true) or use the 480 * new playback range right away (Reset/false) 481 * @param aContextData 482 * Optional opaque data that will be passed back to the user with the command response 483 * @leave This method can leave with one of the following error codes 484 * OsclErrInvalidState if invoked in the incorrect state 485 * @returns A unique command id for asynchronous completion 486 **/ 487 virtual PVCommandId SetPlaybackRange(PVPPlaybackPosition aBeginPos, PVPPlaybackPosition aEndPos, bool aQueueRange, const OsclAny* aContextData = NULL) = 0; 488 489 /** 490 * This function retrieves the playback range information for the current or queued playback range. 491 * The user can choose which playback range by the aQueued flag. This function can be called when pvPlayer is in 492 * PVP_STATE_INITIALIZED, PVP_STATE_PREPARED, PVP_STATE_STARTED, or PVP_STATE_PAUSED state. 493 * The units of position is specified in the passed-in PVPlaybackPosition parameters which will be filled in when the command completes. 494 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 495 * callback handler will be called when this command request completes. 496 * 497 * @param aBeginPos 498 * Reference to place the begin position for the playback range 499 * @param aEndPos 500 * Reference to place the end position for the playback range 501 * @param aQueued 502 * Input flag to choose inof of which playback range to return. Set(true)for queued range. Reset(false) for current range. 503 * @param aContextData 504 * Optional opaque data that will be passed back to the user with the command response 505 * @leave This method can leave with one of the following error codes 506 * OsclErrInvalidState if invoked in the incorrect state 507 * @returns A unique command id for asynchronous completion 508 **/ 509 virtual PVCommandId GetPlaybackRange(PVPPlaybackPosition &aBeginPos, PVPPlaybackPosition &aEndPos, bool aQueued, const OsclAny* aContextData = NULL) = 0; 510 511 /** 512 * This function allows querying of the current playback position. The playback position units 513 * will be in the one specified by the passed-in reference to PVPPlaybackPosition. If no units 514 * are specified, the units will default to milliseconds. 515 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 516 * callback handler will be called when this command request completes. 517 * 518 * @param aPos 519 * Reference to place the current playback position 520 * @param aContextData 521 * Optional opaque data that will be passed back to the user with the command response 522 * @leave This method can leave with one of the following error codes 523 * OsclErrInvalidState if invoked in the incorrect state 524 * @returns A unique command id for asynchronous completion 525 **/ 526 virtual PVCommandId GetCurrentPosition(PVPPlaybackPosition &aPos, const OsclAny* aContextData = NULL) = 0; 527 528 /** 529 * This function allows the setting of the playback rate. The playback rate can be set 530 * as millipercent of "real-time" playback rate. For example, 100000 means 1X "real-time", 400000 531 * means 4X, 25000 means 0.25X, and -100000 means 1X backward. 532 * The playback rate can also be modified by specifying the timebase to use for the playback 533 * clock. This is accomplished by setting the aRate parameter to 0 and passing in a pointer 534 * to an PVMFTimebase. 535 * This function can be called when pvPlayer is in PVP_STATE_PREPARED, PVP_STATE_STARTED, or PVP_STATE_PAUSED state. 536 * Changing to or from an outside timebase is only allowed in PVP_STATE_PREPARED. 537 * Command if called in player state PVP_STATE_PAUSED with a direction change, will complete in one Engine AO run without actually 538 * changing the direction. The change in direction will come into affect when Resume is called on Engine by the app. If the request 539 * is not honored by the source node during Resume, engine will continue to complete Resume but will send an informational event 540 * "PVMFInfoChangePlaybackPositionNotSupported" to the app informing that the SetPlaybackRate request could not be honored. 541 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 542 * callback handler will be called when this command request completes. 543 * 544 * @param aRate 545 * The playback rate specified as millipercent of "real-time". 546 * A millipercent is 1/1000 of a percent. So 2X = 200% of realtime is 547 * 200,000 millipercent. The motivation is to povide precision with an integer parameter. 548 * Negative rates specify backward playback. 549 * The valid range of absolute value of playback rates will be limited to the 550 * minimum and maximum returned by GetPlaybackMinMaxRate(). 551 * @param aTimebase 552 * Reference to an PVMFTimebase which will be used to drive the playback clock. aRate must be 553 * set to 0, 1X, or -1X to use the timebase. 554 * @param aContextData 555 * Optional opaque data that will be passed back to the user with the command response 556 * @leave This method can leave with one of the following error codes 557 * OsclErrArgument if rate or timebase is invalid 558 * @returns A unique command id for asynchronous completion 559 **/ 560 virtual PVCommandId SetPlaybackRate(int32 aRate, PVMFTimebase* aTimebase = NULL, const OsclAny* aContextData = NULL) = 0; 561 562 /** 563 * This function retrieves the current playback rate setting. If the playback rate is set as a millipercent of "real-time" 564 * playback rate, then aRate will be filled in with the milliperecent value when this command completes 565 * successfully. If the playback rate is set by an outside timebase, aRate will be set to 0 and aTimebase pointer 566 * will point to the PVMFTimebase being used when the command completes successfully. 567 * This function can be called when pvPlayer is in 568 * PVP_STATE_PREPARED, PVP_STATE_STARTED, or PVP_STATE_PAUSED state. 569 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 570 * callback handler will be called when this command request completes. 571 * 572 * @param aRate 573 * A reference to an integer which will be filled in with the current playback rate expressed 574 * as millipercent of "real-time" playback rate. If an outside timebase is being used, aRate would 575 * be set to 0. 576 * @param aTimebase 577 * Reference to an PVMFTimebase pointer which will be valid if an outside timebase is being used 578 * for the playback clock. 579 * @param aContextData 580 * Optional opaque data that will be passed back to the user with the command response 581 * @leave This method can leave with one of the following error codes 582 * 583 * @returns A unique command id for asynchronous completion 584 **/ 585 virtual PVCommandId GetPlaybackRate(int32& aRate, PVMFTimebase*& aTimebase, const OsclAny* aContextData = NULL) = 0; 586 587 /** 588 * This function retrieves the minimum and maximum playback rate expressed as a millipercent of "real-time" 589 * playback rate. 590 * This function can be called anytime between pvPlayer instantiation and destruction. 591 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 592 * callback handler will be called when this command request completes. 593 * 594 * @param aMinRate 595 * A reference to an integer which will be filled in with the minimum playback rate allowed expressed 596 * as millipercent of "real-time" playback rate. 597 * @param aMaxRate 598 * A reference to an integer which will be filled in with the maximum playback rate allowed expressed 599 * as millipercent of "real-time" playback rate. 600 * @param aContextData 601 * Optional opaque data that will be passed back to the user with the command response 602 * @leave This method can leave with one of the following error codes 603 * 604 * @returns A unique command id for asynchronous completion 605 **/ 606 virtual PVCommandId GetPlaybackMinMaxRate(int32& aMinRate, int32& aMaxRate, const OsclAny* aContextData = NULL) = 0; 607 608 /** 609 * This function allows querying of the current playback position as a synchronous command. The playback position units 610 * will be in the one specified by the passed-in reference to PVPPlaybackPosition. If no units 611 * are specified, the units will default to milliseconds. 612 * 613 * @param aPos 614 * Reference to place the current playback position 615 * @leave This method can leave with one of the following error codes 616 * OsclErrInvalidState if invoked in the incorrect state 617 * @returns Status indicating whether the command succeeded or not. 618 **/ 619 virtual PVMFStatus GetCurrentPositionSync(PVPPlaybackPosition &aPos) = 0; 620 621 /** 622 * This functions prepares pvPlayer for playback. pvPlayer connects the data source with the data sinks and starts 623 * the data source to queue the media data for playback(e.g. for 3GPP streaming, fills the jitter buffer). 624 * pvPlayer also checks to make sure each component needed for 625 * playback is ready and capable. When successful, pvPlayer will be in PVP_STATE_PREPARED state, 626 * The command should be called only in PVP_STATE_INITIALISED. 627 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 628 * callback handler will be called when this command request completes. 629 * 630 * @param aContextData 631 * Optional opaque data that will be passed back to the user with the command response 632 * @leave This method can leave with one of the following error codes 633 * OsclErrInvalidState if invoked in the incorrect state 634 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 635 * @returns A unique command id for asynchronous completion 636 **/ 637 virtual PVCommandId Prepare(const OsclAny* aContextData = NULL) = 0; 638 639 /** 640 * This function kicks off the actual playback. Media data are sent out from the data source to the data sink(s). 641 * pvPlayer will transition to PVP_STATE_STARTED state after playback starts successfully. 642 * The command should be called only in PVP_STATE_PREPARED. 643 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 644 * callback handler will be called when this command request completes. 645 * 646 * @param aContextData 647 * Optional opaque data that will be passed back to the user with the command response 648 * @leave This method can leave with one of the following error codes 649 * OsclErrInvalidState if invoked in the incorrect state 650 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 651 * @returns A unique command id for asynchronous completion 652 **/ 653 virtual PVCommandId Start(const OsclAny* aContextData = NULL) = 0; 654 655 /** 656 * This function pauses the currently ongoing playback. pvPlayer must be in PVP_STATE_STARTED state 657 * to call this function. When pause successfully completes, pvPlayer will be in PVP_STATE_PAUSED state. 658 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 659 * callback handler will be called when this command request completes. 660 * 661 * @param aContextData 662 * Optional opaque data that will be passed back to the user with the command response 663 * @leave This method can leave with one of the following error codes 664 * OsclErrInvalidState if invoked in the incorrect state 665 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 666 * @returns A unique command id for asynchronous completion 667 **/ 668 virtual PVCommandId Pause(const OsclAny* aContextData = NULL) = 0; 669 670 /** 671 * This function resumes the currently paused playback. pvPlayer must be in 672 * PVP_STATE_PAUSED state to call this function. When resume successfully completes, 673 * pvPlayer will be in PVP_STATE_STARTED state. 674 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 675 * callback handler will be called when this command request completes. 676 * 677 * @param aContextData 678 * Optional opaque data that will be passed back to the user with the command response 679 * @leave This method can leave with one of the following error codes 680 * OsclErrInvalidState if invoked in the incorrect state 681 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 682 * @returns A unique command id for asynchronous completion 683 **/ 684 virtual PVCommandId Resume(const OsclAny* aContextData = NULL) = 0; 685 686 /** 687 * This function stops the current playback and transitions pvPlayer to the PVP_STATE_INITIALIZED 688 * state. During the transition, data transmission from data source to all data sinks are 689 * terminated. Also all connections between data source and data sinks 690 * are torn down. 691 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 692 * callback handler will be called when this command request completes. 693 * 694 * @param aContextData 695 * Optional opaque data that will be passed back to the user with the command response 696 * @leave This method can leave with one of the following error codes 697 * OsclErrInvalidState if invoked in the incorrect state 698 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 699 * @returns A unique command id for asynchronous completion 700 **/ 701 virtual PVCommandId Stop(const OsclAny* aContextData = NULL) = 0; 702 703 /** 704 * This function may be used to close and unbind a data sink that has been previously added. 705 * This function must be called when pvPlayer is in PVP_STATE_INITIALIZED state. If the data sink 706 * is in use for playback, Stop must be called first to stop the playback and free the data sink. 707 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 708 * callback handler will be called when this command request completes. 709 * 710 * @param aDataSink 711 * Reference to the data sink to be removed 712 * @param aContextData 713 * Optional opaque data that will be passed back to the user with the command response 714 * @leave This method can leave with one of the following error codes 715 * OsclErrBadHandle if the passed in sink parameter is invalid 716 * OsclErrInvalidState if invoked in the incorrect state 717 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 718 * @returns A unique command id for asynchronous completion 719 **/ 720 virtual PVCommandId RemoveDataSink(PVPlayerDataSink& aDataSink, const OsclAny* aContextData = NULL) = 0; 721 722 /** 723 * This function cleans up resources used for playback to transition pvPlayer to PVP_STATE_IDLE state. 724 * While processing this command, pvPlayer is in the PVP_STATE_RESETTING state. 725 * If any data sinks are still referenced by pvPlayer when this function is called, the data sinks 726 * will be closed and removed from pvPlayer during the Reset. 727 * If already in PVP_STATE_IDLE state, then nothing will occur. 728 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 729 * callback handler will be called when this command request completes. 730 * 731 * @param aContextData 732 * Optional opaque data that will be passed back to the user with the command response 733 * @leave This method can leave with one of the following error codes 734 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 735 * @returns A unique command id for asynchronous completion 736 **/ 737 virtual PVCommandId Reset(const OsclAny* aContextData = NULL) = 0; 738 739 /** 740 * This function may be used to close and unbind a data source that has been previously added. 741 * This function must be called when pvPlayer is in PVP_STATE_IDLE state. If the data source 742 * has already been initialized, Reset must be called first. 743 * This command request is asynchronous. PVCommandStatusObserver's CommandCompleted() 744 * callback handler will be called when this command request completes. 745 * 746 * @param aDataSource 747 * Reference to the data source to be removed. 748 * @param aContextData 749 * Optional opaque data that will be passed back to the user with the command response 750 * @leave This method can leave with one of the following error codes 751 * OsclErrBadHandle if the passed in sink parameter is invalid 752 * OsclErrInvalidState if invoked in the incorrect state 753 * OsclErrNoMemory if the SDK failed to allocate memory during this operation 754 * @returns A unique command id for asynchronous completion 755 **/ 756 virtual PVCommandId RemoveDataSource(PVPlayerDataSource& aDataSource, const OsclAny* aContextData = NULL) = 0; 757 758 /** 759 * Returns SDK version information about pvPlayer. 760 * 761 * @param aSDKInfo 762 * A reference to a PVSDKInfo structure which contains product name, supported hardware platform, 763 * supported software platform, version, part number, and PV UUID. These fields will contain info 764 * .for the currently instantiated pvPlayer engine when this function returns success. 765 * 766 **/ 767 OSCL_IMPORT_REF static void GetSDKInfo(PVSDKInfo& aSDKInfo); 768 769 }; 770 771 772 773 774 #endif // PV_PLAYER_INTERFACE_H_INCLUDED 775
