1 /*
2  * Copyright (c) 2008 The Khronos Group Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining
5  * a copy of this software and associated documentation files (the
6  * "Software"), to deal in the Software without restriction, including
7  * without limitation the rights to use, copy, modify, merge, publish,
8  * distribute, sublicense, and/or sell copies of the Software, and to
9  * permit persons to whom the Software is furnished to do so, subject
10  * to the following conditions:
11  * The above copyright notice and this permission notice shall be included
12  * in all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
18  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
19  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
20  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  *
22  */
23 
24 /** OMX_ContentPipe.h - OpenMax IL version 1.1.2
25  *  The OMX_ContentPipe header file contains the definitions used to define
26  *  the public interface for content piples.  This header file is intended to
27  *  be used by the component.
28  */
29 
30 #ifndef OMX_CONTENTPIPE_H
31 #define OMX_CONTENTPIPE_H
32 
33 #ifndef KD_EACCES
34 /* OpenKODE error codes. CPResult values may be zero (indicating success
35    or one of the following values) */
36 #define KD_EACCES (1)
37 #define KD_EADDRINUSE (2)
38 #define KD_EAGAIN (5)
39 #define KD_EBADF (7)
40 #define KD_EBUSY (8)
41 #define KD_ECONNREFUSED (9)
42 #define KD_ECONNRESET (10)
43 #define KD_EDEADLK (11)
44 #define KD_EDESTADDRREQ (12)
45 #define KD_ERANGE (35)
46 #define KD_EEXIST (13)
47 #define KD_EFBIG (14)
48 #define KD_EHOSTUNREACH (15)
49 #define KD_EINVAL (17)
50 #define KD_EIO (18)
51 #define KD_EISCONN (20)
52 #define KD_EISDIR (21)
53 #define KD_EMFILE (22)
54 #define KD_ENAMETOOLONG (23)
55 #define KD_ENOENT (24)
56 #define KD_ENOMEM (25)
57 #define KD_ENOSPC (26)
58 #define KD_ENOSYS (27)
59 #define KD_ENOTCONN (28)
60 #define KD_EPERM (33)
61 #define KD_ETIMEDOUT (36)
62 #define KD_EILSEQ (19)
63 #endif
64 
65 /** Map types from OMX standard types only here so interface is as generic as possible. */
66 typedef OMX_U32    CPresult;
67 typedef char *     CPstring;
68 typedef void *     CPhandle;
69 typedef OMX_U32    CPuint;
70 typedef OMX_S32    CPint;
71 typedef char       CPbyte;
72 typedef OMX_BOOL   CPbool;
73 
74 /** enumeration of origin types used in the CP_PIPETYPE's Seek function
75  * @ingroup cp
76  */
77 typedef enum CP_ORIGINTYPE {
78     CP_OriginBegin,
79     CP_OriginCur,
80     CP_OriginEnd,
81     CP_OriginKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
82     CP_OriginVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
83     CP_OriginMax = 0X7FFFFFFF
84 } CP_ORIGINTYPE;
85 
86 /** enumeration of contact access types used in the CP_PIPETYPE's Open function
87  * @ingroup cp
88  */
89 typedef enum CP_ACCESSTYPE {
90     CP_AccessRead,
91     CP_AccessWrite,
92     CP_AccessReadWrite ,
93     CP_AccessKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
94     CP_AccessVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
95     CP_AccessMax = 0X7FFFFFFF
96 } CP_ACCESSTYPE;
97 
98 /** enumeration of results returned by the CP_PIPETYPE's CheckAvailableBytes function
99  * @ingroup cp
100  */
101 typedef enum CP_CHECKBYTESRESULTTYPE
102 {
103     CP_CheckBytesOk,                    /**< There are at least the request number
104                                               of bytes available */
105     CP_CheckBytesNotReady,              /**< The pipe is still retrieving bytes
106                                               and presently lacks sufficient bytes.
107                                               Client will be called when they are
108                                               sufficient bytes are available. */
109     CP_CheckBytesInsufficientBytes  ,     /**< The pipe has retrieved all bytes
110                                               but those available are less than those
111                                               requested */
112     CP_CheckBytesAtEndOfStream,         /**< The pipe has reached the end of stream
113                                               and no more bytes are available. */
114     CP_CheckBytesOutOfBuffers,          /**< All read/write buffers are currently in use. */
115     CP_CheckBytesKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
116     CP_CheckBytesVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
117     CP_CheckBytesMax = 0X7FFFFFFF
118 } CP_CHECKBYTESRESULTTYPE;
119 
120 /** enumeration of content pipe events sent to the client callback.
121  * @ingroup cp
122  */
123 typedef enum CP_EVENTTYPE{
124     CP_BytesAvailable,      	    /** bytes requested in a CheckAvailableBytes call are now available*/
125     CP_Overflow,  		           /** enumeration of content pipe events sent to the client callback*/
126     CP_PipeDisconnected  ,  		    /** enumeration of content pipe events sent to the client callback*/
127     CP_EventKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
128     CP_EventVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
129     CP_EventMax = 0X7FFFFFFF
130 } CP_EVENTTYPE;
131 
132 /** content pipe definition
133  * @ingroup cp
134  */
135 typedef struct CP_PIPETYPE
136 {
137     /** Open a content stream for reading or writing. */
138     CPresult (*Open)( CPhandle* hContent, CPstring szURI, CP_ACCESSTYPE eAccess );
139 
140     /** Close a content stream. */
141     CPresult (*Close)( CPhandle hContent );
142 
143     /** Create a content source and open it for writing. */
144     CPresult (*Create)( CPhandle *hContent, CPstring szURI );
145 
146     /** Check the that specified number of bytes are available for reading or writing (depending on access type).*/
147     CPresult (*CheckAvailableBytes)( CPhandle hContent, CPuint nBytesRequested, CP_CHECKBYTESRESULTTYPE *eResult );
148 
149     /** Seek to certain position in the content relative to the specified origin. */
150     CPresult (*SetPosition)( CPhandle  hContent, CPint nOffset, CP_ORIGINTYPE eOrigin);
151 
152     /** Retrieve the current position relative to the start of the content. */
153     CPresult (*GetPosition)( CPhandle hContent, CPuint *pPosition);
154 
155     /** Retrieve data of the specified size from the content stream (advance content pointer by size of data).
156        Note: pipe client provides pointer. This function is appropriate for small high frequency reads. */
157     CPresult (*Read)( CPhandle hContent, CPbyte *pData, CPuint nSize);
158 
159     /** Retrieve a buffer allocated by the pipe that contains the requested number of bytes.
160        Buffer contains the next block of bytes, as specified by nSize, of the content. nSize also
161        returns the size of the block actually read. Content pointer advances the by the returned size.
162        Note: pipe provides pointer. This function is appropriate for large reads. The client must call
163        ReleaseReadBuffer when done with buffer.
164 
165        In some cases the requested block may not reside in contiguous memory within the
166        pipe implementation. For instance if the pipe leverages a circular buffer then the requested
167        block may straddle the boundary of the circular buffer. By default a pipe implementation
168        performs a copy in this case to provide the block to the pipe client in one contiguous buffer.
169        If, however, the client sets bForbidCopy, then the pipe returns only those bytes preceding the memory
170        boundary. Here the client may retrieve the data in segments over successive calls. */
171     CPresult (*ReadBuffer)( CPhandle hContent, CPbyte **ppBuffer, CPuint *nSize, CPbool bForbidCopy);
172 
173     /** Release a buffer obtained by ReadBuffer back to the pipe. */
174     CPresult (*ReleaseReadBuffer)(CPhandle hContent, CPbyte *pBuffer);
175 
176     /** Write data of the specified size to the content (advance content pointer by size of data).
177        Note: pipe client provides pointer. This function is appropriate for small high frequency writes. */
178     CPresult (*Write)( CPhandle hContent, CPbyte *data, CPuint nSize);
179 
180     /** Retrieve a buffer allocated by the pipe used to write data to the content.
181        Client will fill buffer with output data. Note: pipe provides pointer. This function is appropriate
182        for large writes. The client must call WriteBuffer when done it has filled the buffer with data.*/
183     CPresult (*GetWriteBuffer)( CPhandle hContent, CPbyte **ppBuffer, CPuint nSize);
184 
185     /** Deliver a buffer obtained via GetWriteBuffer to the pipe. Pipe will write the
186        the contents of the buffer to content and advance content pointer by the size of the buffer */
187     CPresult (*WriteBuffer)( CPhandle hContent, CPbyte *pBuffer, CPuint nFilledSize);
188 
189     /** Register a per-handle client callback with the content pipe. */
190     CPresult (*RegisterCallback)( CPhandle hContent, CPresult (*ClientCallback)(CP_EVENTTYPE eEvent, CPuint iParam));
191 
192 } CP_PIPETYPE;
193 
194 #endif
195 
196