M4AMRR_CoreReader.h revision b5c7784c96a606890eb8a8b560153ef4a5d1a0d9 
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