MP4DMXReadHeader

Syntax

#include <cafe/mp4dmx.h>

s32
MP4DMXReadHeader(
    void     *data,
    u64      *time_stamp,
    u64      *next_offset,
    s32      *next_size,
    void     *handle
);

Parameters

data Input. The address of the memory region for input MP4 data.
time_stamp Input/output. The time information that is passed to the execute function (get current position, MP4DMXExecute). The time information is only output when this function returns MP4DMX_RET_EXECUTE_NORMAL after being called due to the execute function (get current position, MP4DMXExecute) returning MP4DMX_RET_READ_HEADER.
next_offset Input/output. An offset from the beginning of the MP4 data file. The next offset from the beginning of the MP4 data file to pass to the library.
next_size Input/output. The amount of MP4 data read from the file into the memory region for input MP4 data. The data size to pass to the library with the next call.
handle Input. A pointer referencing an object handle.

Return Values

MP4DMX_RET_EXECUTE_NORMAL Success. Samples can be obtained at the specified timestamp. To get samples, call MP4DMXExecute with control_flag set to 0. When this function returns this value after being called due to the execute process (get current position, MP4DMXExecute) returning MP4DMX_RET_READ_HEADER, use the time_stamp output by this function as an input value for the execute function (get current position, MP4DMXExecute).
MP4DMX_RET_FIND_HEADER This value is returned when the specified timestamp is not in the header information that was read. A size and an offset from the beginning of the MP4 data file are set in next_size and next_offset to find the next header. Read the specified amount of data from the specified offset in the MP4 file and then call this function again.
MP4DMX_RET_INPUT_CONTINUE This is returned when the data is in the middle of a Box and the next input data is requested. A size and an offset from the beginning of the MP4 data file are set in next_size and next_offset to read the next data. Read the specified amount of data from the specified offset in the MP4 file and then call this function again.
MP4DMX_RET_READ_HEADER This is returned when input is requested for another Box that has been split up (while a header is being parsed, during the ordinary process, as well as during the special process). A size and an offset from the beginning of the MP4 data file are set in next_size and next_offset to read the next data or header information. Read the specified amount of data from the specified offset in the MP4 file and then call this function again.
NOTE:
This value is only returned when one or more of the following input parameters has been specified:
DMX_MP4_STTS_READ_BUFFER_SIZE,
DMX_MP4_STSZ_READ_BUFFER_SIZE, or
DMX_MP4_CTTS_READ_BUFFER_SIZE.
MP4DMX_RET_ERROR_BAD_STREAM Failure. This is returned when an error occurs in the memory region for input MP4 data or parameter values are not valid.
MP4DMX_RET_ERROR_NOT_ENOUGH_MEMORY Failure. This error is returned when the necessary memory could not be allocated.
MP4DMX_RET_ERROR_INVALID_POINTER Failure. This error is returned when an argument is NULL.
MP4DMX_RET_ERROR_FATAL Failure. This error is returned when functions are not called in the correct order.

Description

Parses a FileTypeBox, MovieBox, MovieFragmentBox, MovieFragmentRandomAccessBox, or MovieFragmentRandomAccessOffsetBox.

If you are calling this function when the library has not told you to (through a return value), first get the position of a header (call MP4DMXReadHeader).

The user application must decide whether to use the next_size value output when parsing the header MP4DMXFindHeader as is for the next_size input when calling this function. The library cannot know the size of the MP4 data memory reserved by the user application, so if parsing the header MP4DMXFindHeader returns a size that exceeds the range of MP4 data memory, reading the MP4 data file or calling this function with this value can result in an access violation and trigger an exception. When a Box that has been split is specified in the input parameter, the buffer size must be limited, and there is a possibility that the MP4 data memory size exceeds the header data size. The user application must control the value used for the next_size input so that an access violation does not occur. The value output for next_size when finding the header MP4DMXFindHeader is the size of one header processed by this function, but the user application does not need to track the state of header parsing. This function determines whether the value input in next_size is the entire size required for processing and then notifies the user application with the return value, next_size, and next_offset.

Do Not Call From

Background Do not call this function from the background.
Multiple threads This function is not thread-safe.

See Also

MP4DMXOpen
MP4DMXBegin
MP4DMXFindHeader
MP4DMXExecute
MP4DMXEnd
MP4DMXClose

Revision History

2014/07/29 Initial version.


CONFIDENTIAL