1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 #ifndef PVMF_DATA_SOURCE_PLAYBACK_CONTROL_H_INCLUDED 19 #define PVMF_DATA_SOURCE_PLAYBACK_CONTROL_H_INCLUDED 20 21 #ifndef OSCL_BASE_H_INCLUDED 22 #include "oscl_base.h" 23 #endif 24 #ifndef OSCL_VECTOR_H_INCLUDED 25 #include "oscl_vector.h" 26 #endif 27 #ifndef OSCL_MEM_H_INCLUDED 28 #include "oscl_mem.h" 29 #endif 30 #ifndef PV_UUID_H_INCLUDED 31 #include "pv_uuid.h" 32 #endif 33 #ifndef PV_INTERFACE_H_INCLUDED 34 #include "pv_interface.h" 35 #endif 36 #ifndef PVMF_TIMESTAMP_H_INCLUDED 37 #include "pvmf_timestamp.h" 38 #endif 39 #ifndef PVMF_RETURN_CODES_H_INCLUDED 40 #include "pvmf_return_codes.h" 41 #endif 42 43 44 #ifndef PVMF_MEDIA_CLOCK_H_INCLUDED 45 #include "pvmf_media_clock.h" 46 #endif 47 48 #define PVMF_DATA_SOURCE_PLAYBACK_CONTROL_INTERFACE_MIMETYPE "pvxxx/pvmf/pvmfdatasourceplaybackcontrolinterface" 49 #define PvmfDataSourcePlaybackControlUuid PVUuid(0x4d0ff812,0x4fe1,0x4407,0xb9,0x11,0x6b,0x07,0x3a,0xa3,0x43,0x20) 50 51 typedef enum _PVMFDataSourcePositionMode 52 { 53 PVMF_SET_DATA_SOURCE_POSITION_MODE_UNKNOWN = -1, 54 PVMF_SET_DATA_SOURCE_POSITION_MODE_NOW = 0, 55 PVMF_SET_DATA_SOURCE_POSITION_END_OF_CURRENT_PLAY_ELEMENT = 1, 56 PVMF_SET_DATA_SOURCE_POSITION_MODE_END_OF_CURRENT_PLAY_SESSION = 2, 57 } PVMFDataSourcePositionMode; 58 59 class PVMFDataSourcePositionParams 60 { 61 public: PVMFDataSourcePositionParams()62 PVMFDataSourcePositionParams() 63 { 64 iMode = PVMF_SET_DATA_SOURCE_POSITION_MODE_UNKNOWN; 65 iPlayElementIndex = -1; 66 iTargetNPT = 0; 67 iActualNPT = 0; 68 iActualMediaDataTS = 0; 69 iSeekToSyncPoint = true; 70 iPlaylistUri = NULL; 71 }; 72 73 PVMFDataSourcePositionMode iMode; 74 int32 iPlayElementIndex; 75 PVMFTimestamp iTargetNPT; 76 PVMFTimestamp iActualNPT; 77 PVMFTimestamp iActualMediaDataTS; 78 bool iSeekToSyncPoint; 79 uint32 iStreamID; 80 char* iPlaylistUri; 81 }; 82 83 84 // Forward declaration 85 class PVMFPortInterface; 86 87 /** 88 * Configuration interface to control data source nodes for playback 89 */ 90 class PvmfDataSourcePlaybackControlInterface : public PVInterface 91 { 92 public: 93 /** 94 * Asynchronous method to set the position of a data source to a new location. 95 * 96 * The data source will be repositioned to continue providing media data at the 97 * specified destination timestamp. In the case where tracks with synchronization points are 98 * among the source data types provided, there is an option to reposition the 99 * data source to the nearest synchronization point before the specified destination timestamp. 100 * The actual timestamp of the first media data after repositioning will be written to the 101 * aActualTimestamp parameter. Source data for all data tracks will be repositioned to the 102 * actual destination timestamp and the user might need to have knowledge of the difference 103 * between the specified destination timestamp and the actual one for rendering purposes. 104 * This method is asynchronous and the completion of this command will be sent through the 105 * PVMFNodeCmdStatusObserver of the node implementing this interface. 106 * 107 * @param aSessionId The assigned node session ID to use for this request 108 * @param aTargetNPT Target normal-play-time timestamp in milliseconds of the location where the 109 * data source will be repositioned to. 110 * @param aActualNPT The actual normal-play-time timestamp after repositioning will be saved 111 * to this parameter. 112 * @param aActualMediaDataTS The media data timestamp corresponding to the actual NPT time. This 113 * will be the timestamp of the first media data after repositioning. 114 * @param aSeekToSyncPoint If data source provides tracks with synchronization points, enabling this option 115 * will reposition the data source to the nearest synchronization point before the 116 * specified destination. 117 * @param aStreamID Player engine informs the source and sink about the streamID that will apply for the 118 * next playback segment since there needs to be a coordination between the two. 119 * In some cases the engine may want the source to resend the BOS with the same 120 * streamID again. 121 * @param aContext Optional opaque data to be passed back to user with the command response 122 * @returns A unique command ID for asynchronous completion. 123 */ 124 virtual PVMFCommandId SetDataSourcePosition(PVMFSessionId aSessionId, 125 PVMFTimestamp aTargetNPT, 126 PVMFTimestamp& aActualNPT, 127 PVMFTimestamp& aActualMediaDataTS, 128 bool aSeekToSyncPoint = true, 129 uint32 aStreamID = 0, 130 OsclAny* aContext = NULL) = 0; 131 132 133 /** 134 * Asynchronous method to set the position of a data source to a new location. 135 * 136 * The data source will be repositioned to continue providing media data at the 137 * specified destination timestamp. In the case where tracks with synchronization points are 138 * among the source data types provided, there is an option to reposition the 139 * data source to the nearest synchronization point before the specified destination timestamp. 140 * @param aSessionId The assigned node session ID to use for this request 141 * 142 * @param aPVMFDataSourcePositionParams 143 * All the repositioning parameters are contained in PVMFDataSourcePositionParams. 144 * This is a container class for: 145 * #iMode - Playback positon mode indicates when the provided playback position is expected to take effect. 146 * 1) Now => implies that pause any current playback session and start playback from the new position 147 * 2) End of current play element => A play session can be composed of multiple play elements (say a 148 * playlist session) and the provided playlist position is to take effect once the current play 149 * element is complete (say reposition to song 7 after the current song is done) 150 * 3) End of current play session => This playback position is to take effect once the entire current 151 * play session is done. 152 * #iPlayElementIndex - Typically provided in case of a seek within a playsession 153 * with multiple elements. This is the index ON which the position info provided above applies. 154 * Say go to 30 seconds into play element 7. If this value is -1 it means current 155 * play element. 156 * #iTargetNPT Target normal-play-time timestamp in milliseconds of the location where the 157 * data source will be repositioned to. 158 * #iActualNPT The actual normal-play-time timestamp after repositioning will be saved 159 * to this parameter. 160 * #iActualTimestamp - The actual timestamp of the first media data after repositioning will be written 161 * to the iActualTimestamp parameter. Source data for all data tracks will be repositioned to the 162 * actual destination timestamp and the user might need to have knowledge of the difference 163 * between the specified destination timestamp and the actual one for rendering purposes. 164 * #iSeekToSyncPoint If data source provides tracks with synchronization points, enabling this option 165 * will reposition the data source to the nearest synchronization point before the 166 * specified destination. 167 * 168 * This method is asynchronous and the completion of this command will be sent through the 169 * PVMFNodeCmdStatusObserver of the node implementing this interface. 170 * 171 * @param aContext Optional opaque data to be passed back to user with the command response 172 * @returns A unique command ID for asynchronous completion. 173 */ 174 virtual PVMFCommandId SetDataSourcePosition(PVMFSessionId aSessionId, 175 PVMFDataSourcePositionParams& aPVMFDataSourcePositionParams, 176 OsclAny* aContext = NULL) 177 { 178 /* Derived classes can override this method if so desired */ 179 OSCL_UNUSED_ARG(aSessionId); 180 OSCL_UNUSED_ARG(aPVMFDataSourcePositionParams); 181 OSCL_UNUSED_ARG(aContext); 182 183 OSCL_LEAVE(OsclErrNotSupported); 184 return 0; 185 } 186 187 /** 188 * Asynchronous method to query the position of a data source to a new location without changing the position 189 * 190 * In the case where tracks with synchronization point are 191 * among the source data types provided, there is an option to return the 192 * nearest synchronization point before the specified destination timestamp. 193 * This method is asynchronous and the completion of this command will be sent through the 194 * PVMFNodeCmdStatusObserver of the node implementing this interface. 195 * 196 * @param aSessionId The assigned node session ID to use for this request 197 * @param aTargetNPT Target normal-play-time timestamp in milliseconds of the location where the 198 * data source should be if actually repositioning. 199 * @param aActualNPT The actual normal-play-time timestamp after repositioning if it actually occurs 200 * @param aSeekToSyncPoint If data source provides tracks with synchronization points, enabling this option 201 * will set the actual NPT to a synchronization point before the target NPT. 202 * @param aContext Optional opaque data to be passed back to user with the command response 203 * @returns A unique command ID for asynchronous completion. 204 */ 205 virtual PVMFCommandId QueryDataSourcePosition(PVMFSessionId aSessionId, 206 PVMFTimestamp aTargetNPT, 207 PVMFTimestamp& aActualNPT, 208 bool aSeekToSyncPoint = true, 209 OsclAny* aContext = NULL 210 ) = 0; 211 212 /** 213 * Asynchronous method to query the position of a data source to a new location without changing the position 214 * 215 * This overload of QueryDataSourcePosition adds two function arguments, aSyncBeforeTargetNPT and aSyncBeforeTargetNPT 216 * The idea is to let engine make a decision for repositioning, instead of node. 217 * PVMFNodeCmdStatusObserver of the node implementing this interface. 218 * 219 * @param aSessionId The assigned node session ID to use for this request 220 * @param aTargetNPT Target normal-play-time timestamp in milliseconds of the location where the 221 * data source should be if actually repositioning. 222 * @param aSyncBeforeTargetNPT The timestamp of nearest sync point before aTargetNPT 223 * @param aSyncAfterTargetNPT The timestamp of nearest sync point before aTargetNPT 224 * @param aSeekToSyncPoint If data source provides tracks with synchronization points, enabling this option 225 * will set the actual NPT to a synchronization point before the target NPT. 226 * @param aContext Optional opaque data to be passed back to user with the command response 227 * @returns A unique command ID for asynchronous completion. 228 */ 229 virtual PVMFCommandId QueryDataSourcePosition(PVMFSessionId aSessionId, 230 PVMFTimestamp aTargetNPT, 231 PVMFTimestamp& aSyncBeforeTargetNPT, 232 PVMFTimestamp& aSyncAfterTargetNPT, 233 OsclAny* aContext = NULL, 234 bool aSeekToSyncPoint = true 235 ) = 0; 236 237 /** 238 * Asynchronous method to set the playback rate of the data source 239 * 240 * The playback rate is specified as millipercent of the "real-time" playback rate (e.g. 100000=1X, 241 * 400000=4X, -50000=0.5X backward) or as an outside timebase. If the specified rate is not 242 * supported by the data source, the command should complete with an error status. 243 * This method is asynchronous and the completion of this command will be sent through the 244 * PVMFNodeCmdStatusObserver of the node implementing this interface. 245 * 246 * @param aSessionId The assigned node session ID to use for this request 247 * @param aRate The new playback rate expressed as millipercent of "real-time" playback rate 248 * @param aTimebase The timebase specified to use for the playback clock 249 * @param aContext Optional opaque data to be passed back to user with the command response 250 * @returns A unique command ID for asynchronous completion 251 **/ 252 virtual PVMFCommandId SetDataSourceRate(PVMFSessionId aSessionId, 253 int32 aRate, 254 PVMFTimebase* aTimebase = NULL, 255 OsclAny* aContext = NULL) = 0; 256 257 /** 258 * Synchronous method to compute skip timestamp based on actual and target NPT values 259 * Not all source nodes need implement this. Some source node (viz. 3GPP RTSP Streaming) 260 * are "realtime" sources and are constrained by remote server's datatransfer rate,which 261 * typically is realtime. In those cases it makes sense to start rendering from actualNPT 262 * immaterial how engine's repositioning tunables are configured. 263 * 264 * @param aTargetNPT Target normal-play-time timestamp in milliseconds of the location where the 265 * data source will be repositioned to, as provided in a prior SetDataSourcePosition 266 * call. 267 * @param aActualNPT The actual normal-play-time timestamp after repositioning as provided by the 268 * source node in a prior SetDataSourcePosition call. 269 * @param aActualMediaDataTS The media data timestamp corresponding to the actual NPT time. This 270 * will be the timestamp of the first media data after repositioning, as 271 * provided by the source node. 272 * @param aSkipTimeStamp Computed by source node based on aTargetNPT, aActualNPT and aActualMediaDataTS. 273 * @param aStartNPT Computed by source node based on aTargetNPT, aActualNPT and aActualMediaDataTS. 274 * @returns PVMFErrNotSupported if the source node does not care about skip timestamps, else one 275 * of PVMF return codes. 276 **/ ComputeSkipTimeStamp(PVMFTimestamp aTargetNPT,PVMFTimestamp aActualNPT,PVMFTimestamp aActualMediaDataTS,PVMFTimestamp & aSkipTimeStamp,PVMFTimestamp & aStartNPT)277 virtual PVMFStatus ComputeSkipTimeStamp(PVMFTimestamp aTargetNPT, 278 PVMFTimestamp aActualNPT, 279 PVMFTimestamp aActualMediaDataTS, 280 PVMFTimestamp& aSkipTimeStamp, 281 PVMFTimestamp& aStartNPT) 282 { 283 OSCL_UNUSED_ARG(aTargetNPT); 284 OSCL_UNUSED_ARG(aActualNPT); 285 OSCL_UNUSED_ARG(aActualMediaDataTS); 286 OSCL_UNUSED_ARG(aSkipTimeStamp); 287 OSCL_UNUSED_ARG(aStartNPT); 288 return PVMFErrNotSupported; 289 } 290 291 /** 292 * Synchronous method to notify the Target NPT to the Source Node. Some source node 293 * (viz. 3GPP RTSP Streaming) will need to know the Target NPT before Prepare is 294 * called on the node to support PipeLining feature, in which the Source node 295 * will send a SETUP and PLAY request back to back to the streaming server's supporting 296 * PipeLining mode. 297 * 298 * @param aTargetNPT Target normal-play-time timestamp in milliseconds of the location where the 299 * data source will be repositioned to. 300 */ NotifyTargetPositionSync(PVMFTimestamp aTargetNPT)301 virtual PVMFStatus NotifyTargetPositionSync(PVMFTimestamp aTargetNPT) 302 { 303 OSCL_UNUSED_ARG(aTargetNPT); 304 return PVMFErrNotSupported; 305 } 306 }; 307 308 #endif // PVMF_DATA_SOURCE_PLAYBACK_CONTROL_H_INCLUDED 309 310 311 312 313