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    M4MP4W_Writer.h
20 * @brief   Core MP4 writer interface
21 * @note    This file declares the MP4 writer interface functions.
22 *          The MP4 writer specific types are defined in file M4MP4W_Types.h
23 ******************************************************************************
24 */
25#ifndef M4MP4W_WRITER_H
26#define M4MP4W_WRITER_H
27
28#ifdef __cplusplus
29extern "C" {
30#endif /* __cplusplus */
31
32#include "NXPSW_CompilerSwitches.h"
33
34#ifndef _M4MP4W_USE_CST_MEMORY_WRITER
35
36/* includes */
37#include "M4OSA_Types.h"
38#include "M4OSA_Error.h"
39#include "M4OSA_FileWriter.h"
40#include "M4OSA_FileReader.h"
41#include "M4SYS_AccessUnit.h"
42#include "M4MP4W_Types.h"
43
44/**
45 ******************************************************************************
46 * MP4W Errors & Warnings definition
47 ******************************************************************************
48 */
49#define M4WAR_MP4W_OVERSIZE         M4OSA_ERR_CREATE(M4_WAR, M4MP4_WRITER ,0x000001)
50#define M4WAR_MP4W_NOT_EVALUABLE    M4OSA_ERR_CREATE(M4_WAR, M4MP4_WRITER ,0x000002)
51
52/**
53 ******************************************************************************
54 * @brief    Get MP4W version
55 * @param    major            (OUT) Pointer to the 'major' version number.
56 * @param    minor            (OUT) Pointer to the 'minor' version number.
57 * @param    revision         (OUT) Pointer to the 'revision' number.
58 * @return   M4NO_ERROR:         No error
59 * @return   M4ERR_PARAMETER:    At least one parameter is null
60 ******************************************************************************
61 */
62M4OSA_ERR M4MP4W_getVersion(M4OSA_UInt8* major,
63                            M4OSA_UInt8* minor,
64                            M4OSA_UInt8* revision);
65
66/**
67 ******************************************************************************
68 * @brief    Initiation of the MP4 file creation
69 * @param    contextPtr             (OUT) Pointer to the MP4 writer context to create.
70 * @param    outputFileDescriptor   (IN)  Descriptor of the output file to open.
71 * @param    fileWriterFunction     (IN)  Pointer to structure containing the set of
72 *                                          OSAL file write functions.
73 * @param    tempFileDescriptor     (IN)  Descriptor of the temporary file to open.
74 * @param    fileReaderFunction     (IN)  Pointer to structure containing the set of
75 *                                          OSAL file read functions.
76 * @return    M4NO_ERROR:         No error
77 * @return    M4ERR_PARAMETER:    At least one parameter is null or incorrect
78 * @return    M4ERR_ALLOC:        Memory allocation failed
79 ******************************************************************************
80 */
81M4OSA_ERR M4MP4W_openWrite( M4OSA_Context*                  contextPtr,
82                            void*                           outputFileDescriptor,
83                            M4OSA_FileWriterPointer*        fileWriterFunction,
84                            void*                           tempFileDescriptor,
85                            M4OSA_FileReadPointer*          fileReaderFunction );
86
87/**
88 ******************************************************************************
89 * @brief    Add a new track
90 * @param    context              (IN/OUT)  MP4 writer context.
91 * @param    streamDescPtr        (IN)      Pointer to the structure containing the
92                                            parameters for the new track.
93 * @return    M4NO_ERROR:         No error
94 * @return    M4ERR_PARAMETER:    At least one parameter is null or incorrect
95 * @return    M4ERR_ALLOC:        Memory allocation failed
96 * @return    M4ERR_STATE:        Invalid state
97 * @return    M4ERR_BAD_CONTEXT:  An audio (resp.video) stream has already been added
98 *                                to this context while attempting to add another one,
99 *                                which is forbidden.
100 ******************************************************************************
101 */
102M4OSA_ERR M4MP4W_addStream( M4OSA_Context                context,
103                            M4SYS_StreamDescription*     streamDescPtr);
104
105/**
106 ******************************************************************************
107 * @brief   Signal to the core MP4 writer that there is no more tracks to add
108 * @param   context             (IN/OUT) MP4 writer context.
109 * @return  M4NO_ERROR:         No error
110 * @return  M4ERR_PARAMETER:    At least one parameter is null or incorrect
111 * @return  M4ERR_ALLOC:        Memory allocation failed
112 * @return  M4ERR_STATE:        Invalid state
113 * @return  M4ERR_BAD_CONTEXT:  Audio size estimation is required but not two streams
114 *                              have been added.
115 ******************************************************************************
116 */
117M4OSA_ERR M4MP4W_startWriting( M4OSA_Context context);
118
119/**
120 ******************************************************************************
121 * @brief   Asks the core MP4 writer to initiate the access unit creation in
122 *          the streamID track
123 * @param   context             (IN/OUT) MP4 writer context.
124 * @param   streamID            (IN) Stream ID of the track.
125 * @param   auPtr               (IN/OUT) Access unit.
126 * @return    M4NO_ERROR:         No error
127 * @return    M4ERR_PARAMETER:    At least one parameter is null or incorrect
128 * @return    M4ERR_BAD_STREAM_ID:Unknown stream ID
129 * @return    M4ERR_ALLOC:        Memory allocation failed
130 * @return    M4ERR_STATE:        Invalid state
131 ******************************************************************************
132 */
133M4OSA_ERR M4MP4W_startAU( M4OSA_Context        context,
134                          M4SYS_StreamID       streamID,
135                          M4SYS_AccessUnit*    auPtr);
136
137/**
138 ******************************************************************************
139 * @brief   Ask the core MP4 writer to write the access unit in the streamID track
140 * @note    If M4MP4W_WAR_OVERSIZE is returned, M4MP4W_startAU must not be called anymore,
141 *          but directly M4MP4W_closeWrite().
142 * @param   context             (IN/OUT)   MP4 writer context.
143 * @param   streamID            (IN)       Stream ID of the track.
144 * @param   auPtr               (IN/OUT)   Access unit.
145 * @return    M4NO_ERROR:                 No error
146 * @return    M4ERR_PARAMETER:            At least one parameter is null or incorrect
147 * @return    M4ERR_BAD_STREAM_ID:        Unknown stream ID
148 * @return    M4ERR_ALLOC:                Memory allocation failed
149 * @return    M4ERR_STATE:                Invalid state
150 * @return    M4WAR_MP4W_NOT_EVALUABLE:   It is not possible to evaluate audio size if audio
151 *                                        samples don't have a constant size.
152 * @return    M4WAR_MP4W_OVERSIZE:        Max file size was reached
153 ******************************************************************************
154 */
155M4OSA_ERR M4MP4W_processAU( M4OSA_Context        context,
156                            M4SYS_StreamID       streamID,
157                            M4SYS_AccessUnit*    auPtr);
158
159/**
160 ******************************************************************************
161 * @brief     Close the MP4 file
162 * @note      In previous versions of the MP4 writer, the M4MP4W_freeContext method
163 *            was in the interface, which is not the case anymore.
164 *            The context is now always deallocated in the M4MP4W_closeWrite function.
165 * @param     context             (IN/OUT) MP4 writer context.
166 * @return    M4NO_ERROR:         No error
167 * @return    M4ERR_PARAMETER:    At least one parameter is null or incorrect
168 ******************************************************************************
169 */
170M4OSA_ERR M4MP4W_closeWrite( M4OSA_Context context);
171
172/**
173 ******************************************************************************
174 * @brief    Ask the core MP4 writer to return the value associated with the optionID
175 * @param    context                (IN)    MP4 writer context.
176 * @param    option                 (IN)    Option ID.
177 * @param    valuePtr               (OUT)   Pointer to the option value.
178 * @return    M4NO_ERROR:             No error
179 * @return    M4ERR_PARAMETER:        At least one parameter is null or incorrect
180 * @return    M4ERR_NOT_IMPLEMENTED:  Not implemented in the current version
181 * @return    M4ERR_BAD_OPTION_ID:    Unknown optionID
182 * @return    M4ERR_BAD_STREAM_ID:    Bad stream ID in the option value
183 ******************************************************************************
184 */
185M4OSA_ERR M4MP4W_getOption( M4OSA_Context        context,
186                            M4OSA_OptionID        option,
187                            M4OSA_DataOption    *valuePtr);
188
189/**
190 ******************************************************************************
191 * @brief    Ask the core MP4 writer to set the value associated with the optionID.
192 * @param    context              (IN/OUT)  MP4 writer context.
193 * @param    option               (IN)      Option ID.
194 * @param    value                (IN)      Option value.
195 * @return    M4NO_ERROR:             No error
196 * @return    M4ERR_PARAMETER:        At least one parameter is null or incorrect
197 * @return    M4ERR_NOT_IMPLEMENTED:  Not implemented in the current version
198 * @return    M4ERR_BAD_OPTION_ID:    Unknown optionID
199 * @return    M4ERR_BAD_STREAM_ID:    Bad stream ID in the option value
200 * @return    M4ERR_ALLOC:            A memory allocation failed
201 ******************************************************************************
202 */
203M4OSA_ERR M4MP4W_setOption( M4OSA_Context       context,
204                            M4OSA_OptionID      option,
205                            M4OSA_DataOption    value);
206
207/**
208 ******************************************************************************
209 * @brief    Ask the core MP4 writer to return its state.
210 * @note     By selecting a specific streamID (not null), the caller can obtain
211 *           the state of a specific stream. By using 0 as streamID the returned
212 *           state is not stream specific.
213 * @param    context                (IN/OUT) MP4 writer context.
214 * @param    context                (IN)     Pointer to the state enumeration.
215 * @param    context                (IN/OUT) streamID of the stream to retrieve the
216 *                                           micro-state (0 for global state).
217 * @return    M4NO_ERROR:             No error
218 * @return    M4ERR_BAD_STREAM_ID:    Unknown stream ID
219 * @return    M4ERR_PARAMETER:        At least one parameter is null or incorrect
220 ******************************************************************************
221 */
222M4OSA_ERR M4MP4W_getState( M4OSA_Context    context,
223                           M4MP4W_State*    statePtr,
224                           M4SYS_StreamID   streamID);
225
226/**
227 ******************************************************************************
228 * @brief    Get the currently expected file size
229 * @param    context             (IN/OUT) MP4 writer context.
230 * @return   M4NO_ERROR:         No error
231 * @return   M4ERR_PARAMETER:    At least one parameter is null
232 ******************************************************************************
233 */
234M4OSA_ERR M4MP4W_getCurrentFileSize( M4OSA_Context        context,
235                                     M4OSA_UInt32*        currentFileSize);
236
237#endif /* _M4MP4W_USE_CST_MEMORY_WRITER */
238
239#ifdef __cplusplus
240}
241#endif /* __cplusplus */
242
243
244#endif /*M4MP4W_WRITER_H*/
245
246