1 /* 2 * Copyright (C) 2011 The Android Open Source Project 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 express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 ****************************************************************************** 19 * @file M4AMRR_CoreReader.h 20 * @brief Implementation of AMR parser 21 * @note This file contains the API def. for AMR Parser. 22 ****************************************************************************** 23 */ 24 #ifndef __M4AMR_COREREADER_H__ 25 #define __M4AMR_COREREADER_H__ 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 #include "M4OSA_Types.h" 32 #include "M4OSA_FileReader.h" 33 #include "M4SYS_Stream.h" 34 #include "M4SYS_AccessUnit.h" 35 #include "M4OSA_Time.h" 36 #include "M4TOOL_VersionInfo.h" 37 38 /** 39 ****************************************************************************** 40 * AMR reader Errors & Warnings definition 41 ****************************************************************************** 42 */ 43 #define M4ERR_AMR_INVALID_FRAME_TYPE M4OSA_ERR_CREATE(M4_ERR,M4AMR_READER, 0x000001) 44 #define M4ERR_AMR_NOT_COMPLIANT M4OSA_ERR_CREATE(M4_ERR,M4AMR_READER, 0x000002) 45 46 /** 47 ****************************************************************************** 48 * enumeration M4AMRR_State 49 * @brief This enum defines the AMR reader states 50 * @note These states are used internaly, but can be retrieved from outside the reader. 51 ****************************************************************************** 52 */ 53 typedef enum{ 54 M4AMRR_kOpening = 0x0100, 55 M4AMRR_kOpened = 0x0101, 56 M4AMRR_kReading = 0x0200, 57 M4AMRR_kReading_nextAU = 0x0201, 58 M4AMRR_kClosed = 0x300 59 }M4AMRR_State; 60 61 /** 62 ******************************************************************************* 63 * M4OSA_ERR M4AMRR_openRead (M4OSA_Context* pContext, M4OSA_Void* pFileDescriptor, 64 * M4OSA_FileReaderPointer* pFileFunction); 65 * @brief M4AMRR_OpenRead parses the meta data of the AMR and allocates data structure 66 * @note This function opens the file and creates a context for AMR Parser. 67 * - sets context to null if error occured. 68 * @param pContext(OUT) : AMR Reader context allocated in the function 69 * @param pFileDesscriptor(IN): File descriptor of the input file 70 * @param pFileFunction(IN) : pointer to file function for file access 71 * 72 * @returns M4NO_ERROR : There is no error 73 * @returns M4ERR_PARAMETER : pContext and/or pFileDescriptor is NULL 74 * @returns M4ERR_ALLOC : Memory allocation failed 75 * @returns M4ERR_FILE_NOT_FOUND : file cannot be found 76 * @returns M4AMRR_ERR_AMR_NOT_COMPLIANT : Tthe input is not a AMR file 77 * @returns M4OSA_FILE : See OSAL file Spec. for details. 78 ******************************************************************************* 79 */ 80 M4OSA_ERR M4AMRR_openRead (M4OSA_Context* pContext, M4OSA_Void* pFileDescriptor, 81 M4OSA_FileReadPointer* pFileFunction); 82 83 /** 84 ****************************************************************************** 85 * M4OSA_ERR M4AMRR_getNextStream(M4OSA_Context Context, M4SYS_StreamDescription* pStreamDesc ); 86 * @brief Reads the next available stream in the file 87 * @note Get the stream description of the stream. 88 * - This function assumes that there is only one stream in AMR file. 89 * @param Context(IN/OUT) : AMR Reader context 90 * @param pStreamDesc(OUT): Description of the next read stream 91 * 92 * @returns M4NO_ERROR : There is no error 93 * @returns M4ERR_PARAMETER : atleast one parament is NULL 94 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 95 * @returns M4ERR_ALLOC : Memory allocation failed 96 * @returns M4ERR_STATE : this function cannot be called in this state. 97 * @returns M4AMRR_WAR_NO_MORE_STREAM : There are no more streams in the file. 98 ****************************************************************************** 99 */ 100 101 M4OSA_ERR M4AMRR_getNextStream(M4OSA_Context Context, M4SYS_StreamDescription* pStreamDesc ); 102 103 /** 104 ****************************************************************************** 105 * M4OSA_ERR M4AMRR_startReading(M4OSA_Context Context, M4SYS_StreamID* pStreamIDs ); 106 * @brief Prepares the AMR reading of the specified stream Ids 107 * @note This function changes the state of the reader reading. 108 * @param Context(IN/OUT) : AMR Reader context 109 * @param pStreamIDs(IN) : Array of stream Ids to be prepared. 110 * 111 * @returns M4NO_ERROR : There is no error 112 * @returns M4ERR_PARAMETER : atleast one parament is NULL 113 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 114 * @returns M4ERR_ALLOC : Memory allocation failed 115 * @returns M4ERR_STATE : this function cannot be called in this state. 116 * @returns M4ERR_BAD_STREAM_ID : Atleast one of the stream Id. does not exist. 117 ****************************************************************************** 118 */ 119 M4OSA_ERR M4AMRR_startReading(M4OSA_Context Context, M4SYS_StreamID* pStreamIDs ); 120 121 /** 122 ****************************************************************************** 123 * M4OSA_ERR M4AMRR_nextAU(M4OSA_Context Context, M4SYS_StreamID StreamID, M4SYS_AccessUnit* pAu); 124 * @brief Reads the access unit into the providing stream 125 * @note This function allocates the memory to dataAddress filed and copied the data. 126 * -The Application should not free the dataAddress pointer. 127 * @param Context(IN/OUT) : AMR Reader context 128 * @param StreamID(IN) : Selects the stream 129 * @param pAu(IN/OUT) : Access Unit 130 * 131 * @returns M4NO_ERROR : There is no error 132 * @returns M4ERR_PARAMETER : atleast one parament is NULL 133 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 134 * @returns M4ERR_ALLOC : Memory allocation failed 135 * @returns M4ERR_STATE : this function cannot be called in this state. 136 * @returns M4ERR_BAD_STREAM_ID : Atleast one of the stream Id. does not exist. 137 * @returns M4WAR_NO_DATA_YET : there is no enough data on the stream for new access unit 138 * @returns M4WAR_END_OF_STREAM : There are no more access unit in the stream 139 * @returns M4AMRR_ERR_INVALID_FRAME_TYPE : current frame has no valid frame type. 140 ****************************************************************************** 141 */ 142 M4OSA_ERR M4AMRR_nextAU(M4OSA_Context Context, M4SYS_StreamID StreamID, M4SYS_AccessUnit* pAu); 143 144 /** 145 ****************************************************************************** 146 * M4OSA_ERR M4AMRR_freeAU(M4OSA_Context Context, M4SYS_StreamID StreamID, M4SYS_AccessUnit* pAu); 147 * @brief Notify the ARM Reader that application will no longer use "AU" 148 * @note This function frees the memory pointed by pAu->dataAddress pointer 149 * -Changes the state of the reader back to reading. 150 * @param Context(IN/OUT) : AMR Reader context 151 * @param StreamID(IN) : Selects the stream 152 * @param pAu(IN) : Access Unit 153 * 154 * @returns M4NO_ERROR : There is no error 155 * @returns M4ERR_PARAMETER : atleast one parament is NULL 156 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 157 * @returns M4ERR_ALLOC : Memory allocation failed 158 * @returns M4ERR_STATE : this function cannot be called in this state. 159 * @returns M4ERR_BAD_STREAM_ID : Atleast one of the stream Id. does not exist. 160 ****************************************************************************** 161 */ 162 M4OSA_ERR M4AMRR_freeAU(M4OSA_Context Context, M4SYS_StreamID StreamID, M4SYS_AccessUnit* pAu); 163 164 /** 165 ****************************************************************************** 166 * M4OSA_ERR M4AMRR_seek(M4OSA_Context Context, M4SYS_StreamID* pStreamID, M4OSA_Time time, 167 * M4SYS_seekAccessMode seekMode, M4OSA_Time* pObtainCTS); 168 * @brief The function seeks the targeted time in the give stream by streamId. 169 * @note Each frame is of 20 ms duration,, builds the seek table and points 170 * the file pointer to starting for the required AU. 171 * @param Context(IN/OUT) : AMR Reader context 172 * @param StreamID(IN) : Array of stream IDs. 173 * @param time(IN) : targeted time 174 * @param seekMode(IN) : Selects the seek mode 175 * @param pObtainCTS(OUT) : Returned time nearest to target. 176 * 177 * @returns M4NO_ERROR : There is no error 178 * @returns M4ERR_PARAMETER : atleast one parament is NULL 179 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 180 * @returns M4ERR_ALLOC : Memory allocation failed 181 * @returns M4ERR_STATE : this function cannot be called in this state. 182 * @returns M4ERR_BAD_STREAM_ID : Atleast one of the stream Id. does not exist. 183 * @returns M4WAR_INVALID_TIME : time cannot be reached. 184 ****************************************************************************** 185 */ 186 M4OSA_ERR M4AMRR_seek(M4OSA_Context Context, M4SYS_StreamID* pStreamID, M4OSA_Time time, 187 M4SYS_SeekAccessMode seekMode, M4OSA_Time* pObtainCTS); 188 189 /** 190 ****************************************************************************** 191 * M4OSA_ERR M4AMRR_closeRead(M4OSA_Context Context); 192 * @brief AMR reader closes the file 193 * @param Context(IN?OUT) : AMR Reader context 194 * @returns M4NO_ERROR : There is no error 195 * @returns M4ERR_PARAMETER : atleast one parament is NULL 196 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 197 * @returns M4ERR_ALLOC : Memory allocation failed 198 * @returns M4ERR_STATE : this function cannot be called in this state. 199 ****************************************************************************** 200 */ 201 M4OSA_ERR M4AMRR_closeRead(M4OSA_Context Context); 202 203 /** 204 ****************************************************************************** 205 * M4OSA_ERR M4AMRR_getState(M4OSA_Context Context, M4AMRR_State* pState, M4SYS_StreamID streamId); 206 * @brief Gets the current state of the AMR reader 207 * @param Context(IN/OUT) : AMR Reader context 208 * @param pState(OUT) : Core AMR reader state 209 * @param streamId(IN) : Selects the stream 0 for all 210 * 211 * @returns M4NO_ERROR : There is no error 212 * @returns M4ERR_PARAMETER : atleast one parament is NULL 213 * @returns M4ERR_BAD_CONTEXT : The provided context is not valid 214 * @returns M4ERR_BAD_STREAM_ID : Atleast one of the stream Id. does not exist. 215 ****************************************************************************** 216 */ 217 M4OSA_ERR M4AMRR_getState(M4OSA_Context Context, M4AMRR_State* pState, M4SYS_StreamID streamId); 218 219 220 /** 221 ****************************************************************************** 222 * M4OSA_ERR M4AMRR_getVersion (M4_VersionInfo *pVersion) 223 * @brief Gets the current version of the AMR reader 224 * @param version(OUT) : the structure that stores the version numbers 225 * 226 * @returns M4NO_ERROR : There is no error 227 * @returns M4ERR_PARAMETER : version is NULL 228 ****************************************************************************** 229 */ 230 M4OSA_ERR M4AMRR_getVersion (M4_VersionInfo *pVersion); 231 232 /** 233 ****************************************************************************** 234 * M4OSA_ERR M4AMRR_getmaxAUsize (M4OSA_Context Context, M4OSA_UInt32 *pMaxAuSize) 235 * @brief Computes the maximum access unit size of a stream 236 * 237 * @param Context (IN) Context of the reader 238 * @param pMaxAuSize (OUT) Maximum Access Unit size in the stream 239 * 240 * @return M4NO_ERROR: No error 241 * @return M4ERR_PARAMETER: One of the input pointer is M4OSA_NULL (Debug only) 242 ****************************************************************************** 243 */ 244 M4OSA_ERR M4AMRR_getmaxAUsize(M4OSA_Context Context, M4OSA_UInt32 *pMaxAuSize); 245 246 247 #ifdef __cplusplus 248 } 249 #endif /* __cplusplus*/ 250 #endif /*__M4AMR_COREREADER_H__*/ 251 252
