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 28extern "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*/ 53typedef 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*/ 80M4OSA_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 101M4OSA_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*/ 119M4OSA_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*/ 142M4OSA_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*/ 162M4OSA_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*/ 186M4OSA_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*/ 201M4OSA_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*/ 217M4OSA_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*/ 230M4OSA_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*/ 244M4OSA_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