isomedia.h

一个用于智能手机的多媒体库适合S60 WinCE的跨平台开发库

				GENERAL API FUNCTIONS
********************************************************************/

/*get the last fatal error that occured in the file
ANY FUNCTION OF THIS API WON'T BE PROCESSED IF THE FILE HAS AN ERROR
Note: some function may return an error while the movie has no error
the last error is a FatalError, and is not always set if a bad 
param is specified...*/
GF_Err gf_isom_last_error(GF_ISOFile *the_file);

/*returns 1 if target file is an IsoMedia file, 0 otherwise*/
Bool gf_isom_probe_file(const char *fileName);

/*Opens an isoMedia File.
tmp_dir: for the 2 edit modes only, specifies a location for temp file. If NULL, the librairy will use the default
OS temporary file management schemes.*/
GF_ISOFile *gf_isom_open(const char *fileName, u32 OpenMode, const char *tmp_dir);

/*close the file, write it if new/edited*/
GF_Err gf_isom_close(GF_ISOFile *the_file);

/*delete the movie without saving it.*/
void gf_isom_delete(GF_ISOFile *the_file);

/*Get the mode of an open file*/
u8 gf_isom_get_mode(GF_ISOFile *the_file);

Bool gf_isom_is_JPEG2000(GF_ISOFile *mov);

/********************************************************************
				STREAMING API FUNCTIONS
********************************************************************/
/*open a movie that can be uncomplete in READ_ONLY mode
to use for http streaming & co

NOTE: you must buffer the data to a local file, this mode DOES NOT handle 
http/ftp/... streaming

BytesMissing is the predicted number of bytes missing for the file to be loaded
Note that if the file is not optimized for streaming, this number is not accurate
If the movie is successfully loaded (the_file non-NULL), BytesMissing is zero
*/
GF_Err gf_isom_open_progressive(const char *fileName, GF_ISOFile **the_file, u64 *BytesMissing);

/*If requesting a sample fails with error GF_ISOM_INCOMPLETE_FILE, use this function
to get the number of bytes missing to retrieve the sample*/
u64 gf_isom_get_missing_bytes(GF_ISOFile *the_file, u32 trackNumber);


/*Fragmented movie extensions*/

/*return 0 if movie isn't fragmented, 1 otherwise*/
u32 gf_isom_is_fragmented(GF_ISOFile *the_file);
/*return 0 if track isn't fragmented, 1 otherwise*/
u32 gf_isom_is_track_fragmented(GF_ISOFile *the_file, u32 TrackID);

/*a file being downloaded may be a fragmented file. In this case only partial info 
is available once the file is successfully open (gf_isom_open_progressive), and since there is 
no information wrt number fragments (which could actually be generated on the fly 
at the sender side), you must call this function on regular bases in order to
load newly downloaded fragments. Note this may result in Track/Movie duration changes
and SampleCount change too ...*/
GF_Err gf_isom_refresh_fragmented(GF_ISOFile *the_file, u64 *MissingBytes);

/*check if file has movie info, eg has tracks & dynamic media. Some files may just use
the base IsoMedia structure without "moov" container*/
Bool gf_isom_has_movie(GF_ISOFile *file);

/********************************************************************
				READING API FUNCTIONS
********************************************************************/

/*return the number of tracks in the movie, or -1 if error*/
u32 gf_isom_get_track_count(GF_ISOFile *the_file);

/*return the timescale of the movie, 0 if error*/
u32 gf_isom_get_timescale(GF_ISOFile *the_file);

/*return the duration of the movie, 0 if error*/
u64 gf_isom_get_duration(GF_ISOFile *the_file);

/*return the creation info of the movie*/
GF_Err gf_isom_get_creation_time(GF_ISOFile *the_file, u64 *creationTime, u64 *modificationTime);

/*return the trackID of track number n, or 0 if error*/
u32 gf_isom_get_track_id(GF_ISOFile *the_file, u32 trackNumber);

/*return the track number of the track of specified ID, or 0 if error*/
u32 gf_isom_get_track_by_id(GF_ISOFile *the_file, u32 trackID);

/*gets the enable flag of a track 0: NO, 1: yes, 2: error*/
u8 gf_isom_is_track_enabled(GF_ISOFile *the_file, u32 trackNumber);

/* determines if the track is encrypted 0: NO, 1: yes, 2: error*/
u8 gf_isom_is_track_encrypted(GF_ISOFile *the_file, u32 trackNumber);

/*get the track duration return 0 if bad param*/
u64 gf_isom_get_track_duration(GF_ISOFile *the_file, u32 trackNumber);

/*return the media type FOUR CHAR code type of the media*/
u32 gf_isom_get_media_type(GF_ISOFile *the_file, u32 trackNumber);

/*return the media type FOUR CHAR code type of the media*/
u32 gf_isom_get_media_subtype(GF_ISOFile *the_file, u32 trackNumber, u32 DescriptionIndex);

/*return the media type FOUR CHAR code type of an MPEG4 media (eg, mp4a, mp4v, enca, encv, etc...)
returns 0 if not MPEG-4 subtype*/
u32 gf_isom_get_mpeg4_subtype(GF_ISOFile *the_file, u32 trackNumber, u32 DescriptionIndex);

/*Get the media (composition) time given the absolute time in the Movie
mediaTime is set to 0 if the media is not playing at that time (empty time segment)*/
GF_Err gf_isom_get_media_time(GF_ISOFile *the_file, u32 trackNumber, u32 movieTime, u64 *MediaTime);

/*Get the number of "streams" stored in the media - a media can have several stream descriptions...*/
u32 gf_isom_get_sample_description_count(GF_ISOFile *the_file, u32 trackNumber);

/*Get the stream description index (eg, the ESD) for a given time IN MEDIA TIMESCALE
return 0 if error or if empty*/
u32 gf_isom_get_sample_description_index(GF_ISOFile *the_file, u32 trackNumber, u64 for_time);

/*returns 1 if samples refering to the given stream description are present in the file
0 otherwise*/
Bool gf_isom_is_self_contained(GF_ISOFile *the_file, u32 trackNumber, u32 sampleDescriptionIndex);

/*get the media duration (without edit) return 0 if no samples (URL streams)*/
u64 gf_isom_get_media_duration(GF_ISOFile *the_file, u32 trackNumber);

/*Get the timeScale of the media. */
u32 gf_isom_get_media_timescale(GF_ISOFile *the_file, u32 trackNumber);

/*return the maximum chunk duration of the track in milliseconds*/
u32 gf_isom_get_max_chunk_duration(GF_ISOFile *the_file, u32 trackNumber);

/*Get the HandlerDescription name. The outName must be:
		 (outName != NULL && *outName == NULL)
the handler name is the string version of the MediaTypes*/
GF_Err gf_isom_get_handler_name(GF_ISOFile *the_file, u32 trackNumber, const char **outName);

/*Check a DataReference of this track (index >= 1)
A Data Reference allows to construct a file without integrating the media data*/
GF_Err gf_isom_check_data_reference(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex);

/*get the location of the data. If URL && URN are NULL, the data is in this file
both strings are const: don't free them.*/
GF_Err gf_isom_get_data_reference(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, const char **outURL, const char **outURN);

/*Get the number of samples - return 0 if error*/
u32 gf_isom_get_sample_count(GF_ISOFile *the_file, u32 trackNumber);

/*Get constant sample size, or 0 if size not constant*/
u32 gf_isom_get_constant_sample_size(GF_ISOFile *the_file, u32 trackNumber);
/*returns total amount of media bytes in track*/
u64 gf_isom_get_media_data_size(GF_ISOFile *the_file, u32 trackNumber);

/*It may be desired to fetch samples with a bigger allocated buffer than their real size, in case the decoder
reads more data than available. This sets the amount of extra bytes to allocate when reading samples from this track
NOTE: the dataLength of the sample does NOT include padding*/
GF_Err gf_isom_set_sample_padding(GF_ISOFile *the_file, u32 trackNumber, u32 padding_bytes);

/*return a sample given its number, and set the StreamDescIndex of this sample
this index allows to retrieve the stream description if needed (2 media in 1 track)
return NULL if error*/
GF_ISOSample *gf_isom_get_sample(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, u32 *StreamDescriptionIndex);

/*same as gf_isom_get_sample but doesn't fetch media data
@StreamDescriptionIndex (optional): set to stream description index
@data_offset (optional): set to sample start offset in file.
	
	  NOTE: when both StreamDescriptionIndex and data_offset are NULL, only DTS, CTS_Offset and RAP indications are 
retrieved (faster)
*/
GF_ISOSample *gf_isom_get_sample_info(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, u32 *StreamDescriptionIndex, u64 *data_offset);

/*retrieves given sample DTS*/
u64 gf_isom_get_sample_dts(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber);

/*returns sample duration in media timeScale*/
u32 gf_isom_get_sample_duration(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber);

/*gets a sample given a desired decoding time IN MEDIA TIME SCALE
and set the StreamDescIndex of this sample
this index allows to retrieve the stream description if needed (2 media in 1 track)
return GF_EOS if the desired time exceeds the media duration
WARNING: the sample may not be sync even though the sync was requested (depends on the media and the editList)
the SampleNum is optional. If non-NULL, will contain the sampleNumber*/
GF_Err gf_isom_get_sample_for_media_time(GF_ISOFile *the_file, u32 trackNumber, u64 desiredTime, u32 *StreamDescriptionIndex, u8 SearchMode, GF_ISOSample **sample, u32 *SampleNum);


/*Track Edition functions*/

/*return a sample given a desired time in the movie. MovieTime is IN MEDIA TIME SCALE , handles edit list.
and set the StreamDescIndex of this sample
this index allows to retrieve the stream description if needed (2 media in 1 track)
sample must be set to NULL before calling. 

result Sample is NULL if an error occured
if no sample is playing, an empty sample is returned with no data and a DTS set to MovieTime when serching in sync modes
if no sample is playing, the closest sample in the edit time-line is returned when serching in regular modes

WARNING: the sample may not be sync even though the sync was requested (depends on the media and the editList)

Note: this function will handle re-timestamping the sample according to the mapping  of the media time-line 
on the track time-line. The sample TSs (DTS / CTS offset) are expressed in MEDIA TIME SCALE 
(to match the media stream TS resolution as indicated in media header / SLConfig)

sampleNumber is optional and gives the number of the sample in the media
*/
GF_Err gf_isom_get_sample_for_movie_time(GF_ISOFile *the_file, u32 trackNumber, u64 movieTime, u32 *StreamDescriptionIndex, u8 SearchMode, GF_ISOSample **sample, u32 *sampleNumber);

/*get the number of edited segment*/
u32 gf_isom_get_edit_segment_count(GF_ISOFile *the_file, u32 trackNumber);

/*Get the desired segment information*/
GF_Err gf_isom_get_edit_segment(GF_ISOFile *the_file, u32 trackNumber, u32 SegmentIndex, u64 *EditTime, u64 *SegmentDuration, u64 *MediaTime, u8 *EditMode);

/*get the number of languages for the copyright*/
u32 gf_isom_get_copyright_count(GF_ISOFile *the_file);
/*get the copyright and its language code given the index*/
GF_Err gf_isom_get_copyright(GF_ISOFile *the_file, u32 Index, const char **threeCharCodes, const char **notice);
/*get the opaque watermark info if any - returns GF_NOT_SUPPORTED if not present*/
GF_Err gf_isom_get_watermark(GF_ISOFile *the_file, bin128 UUID, u8** data, u32* length);

/*get the number of chapter for movie or track if trackNumber !=0*/
u32 gf_isom_get_chapter_count(GF_ISOFile *the_file, u32 trackNumber);
/*get the given movie or track (trackNumber!=0) chapter time and name - index is 1-based
@chapter_time: retrives start time in milliseconds - may be NULL.
@name: retrieves chapter name - may be NULL - SHALL NOT be destroyed by user
*/
GF_Err gf_isom_get_chapter(GF_ISOFile *the_file, u32 trackNumber, u32 Index, u64 *chapter_time, const char **name);

/*
return 0 if the media has no sync point info (eg, all samples are RAPs)
return 1 if the media has sync points (eg some samples are RAPs)
return 2 if the media has empty sync point info (eg no samples are RAPs). This will likely only happen 
			in scalable context
*/
u8 gf_isom_has_sync_points(GF_ISOFile *the_file, u32 trackNumber);

/*returns number of sync points*/
u32 gf_isom_get_sync_point_count(GF_ISOFile *the_file, u32 trackNumber);

/*returns 1 if one sample of the track is found to have a composition time offset (DTS<CTS)*/
Bool gf_isom_has_time_offset(GF_ISOFile *the_file, u32 trackNumber);

/*returns 1 if the track has sync shadow samples*/
Bool gf_isom_has_sync_shadows(GF_ISOFile *the_file, u32 trackNumber);

/*returns 1 if the track has sample dep indications*/
Bool gf_isom_has_sample_dependency(GF_ISOFile *the_file, u32 trackNumber);

/*rough estimation of file size, only works for completely self-contained files and without fragmentation
for the current time*/
u64 gf_isom_estimate_size(GF_ISOFile *the_file);


/*
		MPEG-4 Systems extensions
*/

/*check if files has root OD/IOD or not*/
Bool gf_isom_has_root_od(GF_ISOFile *the_file);

/*return the root Object descriptor of the movie (can be NULL, OD or IOD, you have to check its tag)
YOU HAVE TO DELETE THE DESCRIPTOR
*/
GF_Descriptor *gf_isom_get_root_od(GF_ISOFile *the_file);

/*check the presence of a track in IOD. 0: NO, 1: YES, 2: ERROR*/
u8 gf_isom_is_track_in_root_od(GF_ISOFile *the_file, u32 trackNumber);

/*Get the GF_ESD given the StreamDescriptionIndex - YOU HAVE TO DELETE THE DESCRIPTOR*/
GF_ESD *gf_isom_get_esd(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex);

/*Get the decoderConfigDescriptor given the StreamDescriptionIndex - YOU HAVE TO DELETE THE DESCRIPTOR*/
GF_DecoderConfig *gf_isom_get_decoder_config(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex);

/*sets default TrackID (or ES_ID) for clock references. If trackNumber is 0, default sync track ID is reseted