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