• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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;
~PvmiDataStreamObserver()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 
~PVMFDataStreamReadCapacityObserver()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 
~PvmiDataStreamRequestObserver()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         */
CancelNotificationSync(PvmiDataStreamSession aSessionID)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         */
Write(PvmiDataStreamSession aSessionID,OsclRefCounterMemFrag * frag,uint32 & aNumElements)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         */
SetStreamReadCapacityObserver(PVMFDataStreamReadCapacityObserver * aObs)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         */
SetContentLength(uint32 aLength)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         */
GetContentLength()423         virtual uint32 GetContentLength()
424         {
425             return 0;
426         }
427 
428         /**
429         * Returns the data stream buffering capacity, if it is a memory buffer data stream (MBDS)
430         * Used in progressive playback where MBDS has a finite cache size
431         *
432         * @return returns buffering capacity (0 = not MBDS)
433         *
434         */
QueryBufferingCapacity()435         virtual uint32 QueryBufferingCapacity()
436         {
437             return 0;
438         }
439 
440 
441         /**
442         * Sets the request observer usually in the stream writer
443         * Used in progressive playback for repositioning requests, etc
444         *
445         * @param aObserver the observer
446         *
447             * @return returns the status of the operation.
448             */
SetSourceRequestObserver(PvmiDataStreamRequestObserver & aObserver)449         virtual PvmiDataStreamStatus SetSourceRequestObserver(PvmiDataStreamRequestObserver& aObserver)
450         {
451             OSCL_UNUSED_ARG(aObserver);
452             return PVDS_NOT_SUPPORTED;
453         }
454 
455         /**
456         * Callback from stream writer when request has completed
457         * Used in progressive playback when reposition requests are sent to the writer (protocol engine)
458         * which in turn issues HTTP GET requests with Range header to the server
459         *
460         * @param aResponse command response
461         */
SourceRequestCompleted(const PVMFCmdResp & aResponse)462         virtual void SourceRequestCompleted(const PVMFCmdResp& aResponse)
463         {
464             OSCL_UNUSED_ARG(aResponse);
465         }
466 
467         /**
468         * Keep the data in a persistent storage during playback
469         * Used in progressive playback, mainly for moov atom storage
470         *
471         * @param aOffset file offset of data
472         * @param aSize bytes from file offset to be made persistent
473         *
474         * @return returns the status of the operation.
475         */
MakePersistent(int32 aOffset,uint32 aSize)476         virtual PvmiDataStreamStatus MakePersistent(int32 aOffset, uint32 aSize)
477         {
478             OSCL_UNUSED_ARG(aOffset);
479             OSCL_UNUSED_ARG(aSize);
480             return PVDS_NOT_SUPPORTED;
481         }
482 
483         /**
484             * Informs the MBDS that the source has been disconnected
485             * Used in progressive playback when the network connection times out
486             *
487             */
SourceDisconnected()488         virtual void SourceDisconnected()
489         {
490             ;
491         }
492 
493         /**
494         * For reader to find out the byte range in the memory buffer data stream
495         * Used in progressive playback
496         *
497         * @return aCurrentFirstByteOffset first byte offset inclusive
498         * @return aCurrentLastByteOffset last byte offset inclusive
499         */
GetCurrentByteRange(uint32 & aCurrentFirstByteOffset,uint32 & aCurrentLastByteOffset)500         virtual void GetCurrentByteRange(uint32& aCurrentFirstByteOffset, uint32& aCurrentLastByteOffset)
501         {
502             aCurrentFirstByteOffset = 0;
503             aCurrentLastByteOffset = 0;
504         }
505 };
506 
507 
508 
509 #endif //PVMI_DATA_STREAM_INTERFACE_H_INCLUDED
510 
511