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 PVMI_DATA_STREAM_INTERFACE_H_INCLUDED 19 #define PVMI_DATA_STREAM_INTERFACE_H_INCLUDED 20 21 #ifndef OSCL_BASE_H_INCLUDED 22 #include "oscl_base.h" 23 #endif 24 #ifndef OSCL_TYPES_H_INCLUDED 25 #include "oscl_types.h" 26 #endif 27 #ifndef PV_UUID_H_INCLUDED 28 #include "pv_uuid.h" 29 #endif 30 #ifndef PV_INTERFACE_H_INCLUDED 31 #include "pv_interface.h" 32 #endif 33 #ifndef PVMF_RETURN_CODES_H_INCLUDED 34 #include "pvmf_return_codes.h" 35 #endif 36 #ifndef PVMF_MEDIA_DATA_H_INCLUDED 37 #include "pvmf_media_data.h" 38 #endif 39 #ifndef PVMF_EVENT_HANDLING_H_INCLUDED 40 #include "pvmf_event_handling.h" 41 #endif 42 43 44 #define PVMI_DATA_STREAM_INTERFACE_MIMETYPE "pvxxx/pvmf/stream" 45 #define PVMIDataStreamSyncInterfaceUuid PVUuid(0x6d32c608,0x6307,0x4538,0x83,0xe7,0x34,0x0e,0x7a,0xba,0xb9,0x8a) 46 47 typedef int32 PvmiDataStreamSession; 48 typedef int32 PvmiDataStreamCommandId; 49 50 class PVMFCmdResp; 51 class PVMFAsyncEvent; 52 53 class PvmiDataStreamObserver 54 { 55 public: 56 virtual void DataStreamCommandCompleted(const PVMFCmdResp& aResponse) = 0; 57 virtual void DataStreamInformationalEvent(const PVMFAsyncEvent& aEvent) = 0; 58 virtual void DataStreamErrorEvent(const PVMFAsyncEvent& aEvent) = 0; 59 virtual ~PvmiDataStreamObserver() {} 60 }; 61 62 63 typedef enum 64 { 65 PVDS_SUCCESS, 66 PVDS_FAILURE, 67 PVDS_NOT_SUPPORTED, 68 PVDS_PERMISSION_DENIED, 69 PVDS_UNSUPPORTED_MODE, 70 PVDS_INVALID_SESSION, 71 PVDS_INVALID_REQUEST, 72 PVDS_UNSUPPORTED_RANDOM_ACCESS, 73 PVDS_END_OF_STREAM, 74 PVDS_PENDING 75 } PvmiDataStreamStatus; 76 77 typedef enum 78 { 79 PVDS_SEQUENTIAL_ACCESS_ONLY, 80 PVDS_REWIND_TO_START_ONLY, 81 PVDS_LIMITED_SEEKING, /* only allows seeking to certain points in stream */ 82 PVDS_FULL_RANDOM_ACCESS 83 } PvmiDataStreamRandomAccessType; 84 85 typedef enum 86 { 87 PVDS_SEEK_SET, 88 PVDS_SEEK_CUR, 89 PVDS_SEEK_END, 90 PVDS_SKIP_SET, /* MBDS only, to trigger http get request, without changing read pointer position */ 91 PVDS_SKIP_CUR, /* MBDS only, to trigger http get request, without changing read pointer position */ 92 PVDS_SKIP_END /* MBDS only, to trigger http get request, without changing read pointer position */ 93 } PvmiDataStreamSeekType; 94 95 typedef enum 96 { 97 PVDS_READ_ONLY, 98 PVDS_WRITE_ONLY, 99 PVDS_READ_WRITE, 100 PVDS_APPEND, 101 PVDS_READ_PLUS, 102 PVDS_REWRITE 103 } PvmiDataStreamMode; 104 105 106 // requests from the data stream to the writer of the stream 107 typedef enum 108 { 109 PVDS_REQUEST_MEM_FRAG_RELEASED, 110 PVDS_REQUEST_REPOSITION 111 } PvmiDataStreamRequest; 112 113 class PVMFDataStreamReadCapacityObserver 114 { 115 public: 116 virtual PvmiDataStreamStatus GetStreamReadCapacity(uint32& aCapacity) = 0; 117 118 virtual ~PVMFDataStreamReadCapacityObserver() {} 119 }; 120 121 122 class PvmiDataStreamRequestObserver 123 { 124 public: 125 virtual PvmiDataStreamCommandId DataStreamRequest(PvmiDataStreamSession aSessionID, 126 PvmiDataStreamRequest aRequestID, 127 OsclAny* aRequestData, 128 OsclAny* aContext) = 0; 129 130 virtual PvmiDataStreamStatus DataStreamRequestSync(PvmiDataStreamSession aSessionID, 131 PvmiDataStreamRequest aRequestID, 132 OsclAny* aRequestData) = 0; 133 134 virtual ~PvmiDataStreamRequestObserver() {} 135 }; 136 137 138 class PVMIDataStreamSyncInterface : public PVInterface 139 { 140 public: 141 /** 142 * Opens a session with the data stream. Returns a session ID in 143 * the output parameter. 144 * 145 * @param aSessionID - [out] this is an output parameter. The session ID 146 * will be written to this parameter if the session can 147 * be established successfully. 148 * 149 * @param aMode - [in] The mode indicates the way the stream will be used 150 * (e.g., read, write, append, etc) 151 * 152 * @param aNonBlocking - [in] The boolean indicates if the access session 153 * being requested ought to be blocking or non-blocking. 154 * Default is blocking. If non-blocking is not supported 155 * this API should return PVDS_UNSUPPORTED_MODE. 156 * 157 * @return returns 0 if successful and a non-zero value otherwise 158 */ 159 virtual PvmiDataStreamStatus OpenSession(PvmiDataStreamSession& aSessionID, 160 PvmiDataStreamMode aMode, 161 bool aNonBlocking = false) = 0; 162 163 /** 164 * Closes a previously established session. Buffers will be flushed 165 * if needed before closing the session. 166 * 167 * @param aSessionID - [in] A valid session ID of a previously opened session. 168 * 169 * @return returns 0 if successful, and a non-zero value otherwise 170 */ 171 virtual PvmiDataStreamStatus CloseSession(PvmiDataStreamSession aSessionID) = 0; 172 173 /** 174 * Query the random access capabilities. This does not require a session 175 * to be established. 176 * 177 * @return returns an enumeration value that characterizes the random 178 * access capability. 179 * 180 */ 181 virtual PvmiDataStreamRandomAccessType QueryRandomAccessCapability() = 0; 182 183 184 /** 185 * Query the current read capacity. The value returned indicates 186 * the amount of data immediately available for reading beyond the 187 * position of the current read pointer. If the data is unavailable 188 * then it will be indicated in the return value. 189 * 190 * @param aSessionID - [in] A valid session ID of a previously opened session. 191 * 192 * @param aCapacity - [out] Amount of data available for immediate reading. 193 * 194 * @return returns 0 if successful, and a non-zero value otherwise 195 * 196 */ 197 virtual PvmiDataStreamStatus QueryReadCapacity(PvmiDataStreamSession aSessionID, 198 uint32& aCapacity) = 0; 199 200 /** 201 * Request notification when the read capacity reaches a certain level. 202 * The observer registered with this request will be used for the callback 203 * when the requested capacity is available. Only one pending notification 204 * is allowed, so if the API is called before a pending notification has 205 * been sent then the new value will replace the previous one. 206 * 207 * @param aSessionID the session identifier of the stream 208 * @param observer the observer that will receive the callback 209 * @param capacity the requested capacity (bytes available past 210 * the read pointer) 211 * @param aContextData An opaque data pointer that would be returned in the callback. 212 * 213 * @return This will return a non-zero command id on success. 214 * if the asynchronous notification is not supported this method 215 * leaves with OsclErrNotSupported 216 */ 217 virtual PvmiDataStreamCommandId RequestReadCapacityNotification(PvmiDataStreamSession aSessionID, 218 PvmiDataStreamObserver& aObserver, 219 uint32 aCapacity, 220 OsclAny* aContextData = NULL) = 0; 221 222 223 /** 224 * Query the current write capacity. The value returned indicates 225 * the amount of data immediately available for writing beyond the 226 * position of the current write pointer. If the data is unavailable 227 * then it will be indicated in the return value. 228 * 229 * @param aSessionID - [in] A valid session ID of a previously opened session. 230 * 231 * @param aCapacity - [out] Amount of data available for immediate writing. 232 * 233 * @return returns 0 if successful, and a non-zero value otherwise 234 */ 235 virtual PvmiDataStreamStatus QueryWriteCapacity(PvmiDataStreamSession aSessionID, 236 uint32& aCapacity) = 0; 237 238 /** 239 * Request notification when the write capacity reaches a certain level. 240 * The observer registered with this request will be used for the callback 241 * when the requested capacity is available. Only one pending notification 242 * is allowed, so if the API is called before a pending notification has 243 * been sent then the new value will replace the previous one. 244 * 245 * @param aSessionID the session identifier of the stream 246 * @param observer the observer that will receive the callback 247 * @param capacity the requested capacity (bytes available past 248 * the write pointer) 249 * @param aContextData An opaque data pointer that would be returned in the callback. 250 * 251 * @return This will return a non-zero command id on success. 252 * if the asynchronous notification is not supported this method 253 * leaves with OsclErrNotSupported 254 * 255 */ 256 virtual PvmiDataStreamCommandId RequestWriteCapacityNotification(PvmiDataStreamSession aSessionID, 257 PvmiDataStreamObserver& aObserver, 258 uint32 aCapacity, 259 OsclAny* aContextData = NULL) = 0; 260 261 /** 262 * Cancel notification for either write or read capacity that was issued earlier. 263 * The observer registered with this request will be used for the callback 264 * when the notification is cancelled. 265 * 266 * @param aSessionID the session identifier of the stream 267 * @param observer the observer that will receive the callback 268 * @param capacity the command id of the command that needs to be cancelled 269 * @param aContextData An opaque data pointer that would be returned in the callback. 270 * 271 * @return This will return a non-zero command id on success. 272 * if the asynchronous notification is not supported this method 273 * leaves with OsclErrNotSupported 274 * 275 */ 276 virtual PvmiDataStreamCommandId CancelNotification(PvmiDataStreamSession aSessionID, 277 PvmiDataStreamObserver& observer, 278 PvmiDataStreamCommandId aID, 279 OsclAny* aContextData = NULL) = 0; 280 /** 281 * Cancel notification for either write or read capacity that was issued earlier. 282 * Cancellation is done synchronously. 283 * 284 * @param aSessionID the session identifier of the stream 285 * 286 * @return status of the cancel operation 287 * 288 */ 289 virtual PvmiDataStreamStatus CancelNotificationSync(PvmiDataStreamSession aSessionID) 290 { 291 OSCL_UNUSED_ARG(aSessionID); 292 return PVDS_NOT_SUPPORTED; 293 } 294 295 296 /** 297 * Reads from the data stream into the buffer a maximum of 'numelements' 298 * of size 'size'. 299 * 300 * @param aSessionID the session identifier of the stream 301 * @param buffer pointer to buffer of type uint8* 302 * @param size element size in bytes 303 * @param numelements 304 * max number of elements to read. The value will be updated 305 * with the actual number of elements read. 306 * 307 * The number of full elements actually read, which 308 * may be less than count if an error occurs or if the end 309 * of the file is encountered before reaching count. Also if 310 * non-blocking mode is used it may return a smaller count. 311 * The return status will indicate why it returned a smaller value. 312 */ 313 virtual PvmiDataStreamStatus Read(PvmiDataStreamSession aSessionID, 314 uint8* aBuffer, 315 uint32 aSize, 316 uint32& aNumElements) = 0; 317 318 /** 319 * Writes from the buffer to the data stream a maximum of 'numelements' 320 * of size 'size'. 321 * 322 * @param aSessionID the session identifier of the stream 323 * @param frag pointer to OsclRefCounterMemFrag containing the mem frag info 324 * @param numelements 325 * returns the number of elements actually written 326 * 327 * @return status 328 */ 329 virtual PvmiDataStreamStatus Write(PvmiDataStreamSession aSessionID, 330 OsclRefCounterMemFrag* frag, 331 uint32& aNumElements) 332 { 333 OSCL_UNUSED_ARG(aSessionID); 334 OSCL_UNUSED_ARG(frag); 335 OSCL_UNUSED_ARG(aNumElements); 336 return PVDS_NOT_SUPPORTED; 337 } 338 339 /** 340 * Writes from the buffer to the data stream a maximum of 'numelements' 341 * of size 'size'. 342 * 343 * @param aSessionID the session identifier of the stream 344 * @param buffer pointer to buffer of type uint8* 345 * @param size element size in bytes 346 * @param numelements 347 * max number of elements to read 348 * 349 * The number of full elements actually read, which 350 * may be less than count if an error occurs or if the end 351 * of the file is encountered before reaching count. Also 352 * if non-blocking mode is used it may return a smaller count. 353 * The return status will indicate the cause of the error. 354 */ 355 virtual PvmiDataStreamStatus Write(PvmiDataStreamSession aSessionID, 356 uint8* aBuffer, 357 uint32 aSize, 358 uint32& aNumElements) = 0; 359 360 /** 361 * Seek operation 362 * Sets the position for the read/write pointer. 363 * 364 * @param aSessionID the session identifier of the stream 365 * @param offset offset from the specified origin. 366 * @param origin starting point 367 * 368 * @return returns the status of the operation. 369 */ 370 virtual PvmiDataStreamStatus Seek(PvmiDataStreamSession aSessionID, 371 int32 aOffset, 372 PvmiDataStreamSeekType aOrigin) = 0; 373 374 /** 375 * Returns the current position (i.e., byte offset from the beginning 376 * of the data stream for the read/write pointer. 377 */ 378 virtual uint32 GetCurrentPointerPosition(PvmiDataStreamSession aSessionID) = 0; 379 380 381 /** 382 * On a stream with write capability causes any buffered 383 * but unwritten data to be flushed. 384 * 385 * @return returns the status of the operation. 386 */ 387 virtual PvmiDataStreamStatus Flush(PvmiDataStreamSession aSessionID) = 0; 388 389 /** 390 * Sometimes datastream implementations need to rely on an external source 391 * to provide them with updated stream size (take a case of progressive dowmnload 392 * where in module A is doing the download and module B is doing the reads). This 393 * API is one way to make these datastreams connect with each other. 394 * 395 * @leaves by default, derived implementations can choose to override if needed 396 */ 397 virtual void SetStreamReadCapacityObserver(PVMFDataStreamReadCapacityObserver* aObs) 398 { 399 OSCL_UNUSED_ARG(aObs); 400 OSCL_LEAVE(OsclErrNotSupported); 401 } 402 403 /** 404 * Sets the content length, if known, of the media clip 405 * Used in progressive playback where the HTTP server sends the content length 406 * in the HEAD response 407 * 408 * @param aLength length of clip in bytes 409 */ 410 virtual void SetContentLength(uint32 aLength) 411 { 412 OSCL_UNUSED_ARG(aLength); 413 } 414 415 416 /** 417 * Returns the content length, if known, of the media clip 418 * Used in progressive playback where the HTTP server sends the content length 419 * in the HEAD response 420 * 421 * @return returns the content lenght (0 = unknown) 422 */ 423 virtual uint32 GetContentLength() 424 { 425 return 0; 426 } 427 428 /** 429 * @brief Sets the data stream buffering capacity and trim margin. 430 * 431 * Currently, this is only implemented for the Memory Buffer Data 432 * Stream class (MBDS). 433 * 434 * Care should be taken when setting the capacity or trim margin of 435 * the MBDS for progressive playback to not set the capacity or trim 436 * margin higher than the socket node memory pool size. Otherwise, the 437 * graph could deadlock with the socket node waiting for free memory 438 * fragments while the download manager waits for the MBDS to fill. 439 * 440 * The trim margin is the amount of data behind the read pointer that 441 * is kept in the cache for future reference. The trim margin is 442 * useful when the data stream reader is randomly accessing the data 443 * stream contents. If the reader only reads the data stream 444 * sequentially, the trim margin can be set to 0. 445 * 446 * @param[in] aMinCapacity Minimum capacity being requested. 447 * @param[in] aTrimMargin Amount of stale data to keep cached. 448 * 449 * @return PVDS_NOT_SUPPORTED if data stream is not an MBDS. 450 * PVDS_SUCCESS if successful. 451 */ 452 virtual PvmiDataStreamStatus SetBufferingCapacityAndTrimMargin(uint32 aMinCapacity, uint32 aTrimMargin) 453 { 454 //This method is currently only supported by Memory Buffer Data Streams. 455 return PVDS_NOT_SUPPORTED; 456 } 457 458 /** 459 * Returns the data stream buffering capacity, if it is a memory buffer data stream (MBDS) 460 * Used in progressive playback where MBDS has a finite cache size 461 * 462 * @return returns buffering capacity (0 = not MBDS) 463 * 464 */ 465 virtual uint32 QueryBufferingCapacity() 466 { 467 return 0; 468 } 469 470 471 /** 472 * @brief Returns the data stream buffering trim margin; the amount of 473 * "stale" data (data behind the current read position) that is 474 * kept cached. 475 * 476 * Currently only implemented for Memory Buffer Data Streams (MBDS). 477 * 478 * @return buffering trim margin 479 * 480 */ 481 virtual uint32 QueryBufferingTrimMargin() 482 { 483 return 0; 484 } 485 486 487 488 /** 489 * Sets the request observer usually in the stream writer 490 * Used in progressive playback for repositioning requests, etc 491 * 492 * @param aObserver the observer 493 * 494 * @return returns the status of the operation. 495 */ 496 virtual PvmiDataStreamStatus SetSourceRequestObserver(PvmiDataStreamRequestObserver& aObserver) 497 { 498 OSCL_UNUSED_ARG(aObserver); 499 return PVDS_NOT_SUPPORTED; 500 } 501 502 /** 503 * Callback from stream writer when request has completed 504 * Used in progressive playback when reposition requests are sent to the writer (protocol engine) 505 * which in turn issues HTTP GET requests with Range header to the server 506 * 507 * @param aResponse command response 508 */ 509 virtual void SourceRequestCompleted(const PVMFCmdResp& aResponse) 510 { 511 OSCL_UNUSED_ARG(aResponse); 512 } 513 514 /** 515 * Keep the data in a persistent storage during playback 516 * Used in progressive playback, mainly for moov atom storage 517 * 518 * @param aOffset file offset of data 519 * @param aSize bytes from file offset to be made persistent 520 * 521 * @return returns the status of the operation. 522 */ 523 virtual PvmiDataStreamStatus MakePersistent(int32 aOffset, uint32 aSize) 524 { 525 OSCL_UNUSED_ARG(aOffset); 526 OSCL_UNUSED_ARG(aSize); 527 return PVDS_NOT_SUPPORTED; 528 } 529 530 /** 531 * Informs the MBDS that the source has been disconnected 532 * Used in progressive playback when the network connection times out 533 * 534 */ 535 virtual void SourceDisconnected() 536 { 537 ; 538 } 539 540 /** 541 * For reader to find out the byte range in the memory buffer data stream 542 * Used in progressive playback 543 * 544 * @return aCurrentFirstByteOffset first byte offset inclusive 545 * @return aCurrentLastByteOffset last byte offset inclusive 546 */ 547 virtual void GetCurrentByteRange(uint32& aCurrentFirstByteOffset, uint32& aCurrentLastByteOffset) 548 { 549 aCurrentFirstByteOffset = 0; 550 aCurrentLastByteOffset = 0; 551 } 552 }; 553 554 555 556 #endif //PVMI_DATA_STREAM_INTERFACE_H_INCLUDED 557 558
