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