BMediaFile

Derived from: none
Declared in:  be/media/MediaFile.h
Library: libmedia.so
Allocation: Constructor only
Summary:  more...

The BMediaFile class represents a file containing media data. When instantiated a BMediaFile with an entry_ref to an existing media file, it sniffs the file and figures out the right codecs to use when accessing that file.

To read an existing media file, you can then call TrackAt() to instantiate BMediaTrack objects fot the file's tracks; these can in turn be used to decode media data from the file.

You can also write data to the file. In this case, you construct the object by specifying an entry_ref and a media_file_format specification describing the format of the media data you plan to write into the file. You then call CreateTrack() to create each track you want to write into the file. Once each track has been created (but is still empty), you call CommitHeader() to write the file's header to disk, and you can use BMediaTrack functions to write the actual media data into the tracks.

Call CloseFile() when you're finished writing to it (you don't need to call this if you're reading the file).

For an example of how to use BMediaFile to read and write media files, see "Reading and Writing Media Files"

As a general rule, you can't use wildcards in any structures used by BMediaFile functions. You tell BMediaFile what format you have, and BMediaFile will simply tell you whether or not that format is supported.

Constructor and Destructor

BMediaFile()

BMediaFile(const entry_ref *ref) BMediaFile(BDataIO *source) BMediaFile(const entry_ref *ref,       int32 flags = 0) BMediaFile(BDataIO *source,       int32 flags = 0) BMediaFile(const entry_ref *ref,       const media_file_format *fileFormat,       int32 flags = 0) BMediaFile(BDataIO *destination,       const media_file_format *fileFormat,       int32 flags = 0)

The first four forms of the constructor initializes the BMediaFile to read the file specified by ref or by source. Once this has been done, be sure to call InitCheck() to ensure that the file was successfully sniffed. If sniffing was successful, the BMediaFile object can then be used to instantiate the BMediaTrack objects necessary to read the file's data.

The second two forms prepare a BMediaFile object for writing to a media file, which is specified by either ref or destination. The format of the file to be written is specified by fileFormat.

The flags can be a combination of the following values:

Constant	Description
B_MEDIA_FILE_REPLACE_MODE	Replace any existing media file, if writing.
B_MEDIA_FILE_NO_READ_AHEAD	Don't read ahead in the file.
B_MEDIA_FILE_UNBUFFERED	Use smaller reads. This can be handy if you're trying to stream low-bitrate files withou;waiting for the extractor to fill a large outgoing buffer.
B_MEDIA_FILE_BIG_BUFFERS	Use large buffers.

~BMediaFile()

virtual ~BMediaFile(void)

Destructor.

Member Functions

AddChunk()

status_t AddChunk(int32 type, const void *data, size_t size)

Writes a user-defined chunk of data to the file (if doing so is supported by the encoder). The type argument indicates the chunk type, data points to the data to be written, and size indicates the size of the data to write to the file.

The BMediaFile class doesn't automatically perform any locking to prevent multiple writes to the file from occurring at the same time. If you have multiple threads writing into the same BMediaFile, you must use a locking mechanism (such as a semaphore) to keep writes from overlapping.

RETURN CODES

• B_OK. No error.

• B_BAD_TYPE. The BMediaFile doesn't reference a valid file.

• Other errors, depending on the codec.

AddCopyright() , Copyright()

status_t *AddCopyright(const char *data) const char *Copyright(void) const

AddCopyright() sets the file's copyright notice to the string specified by data. Any existing notice is replaced. The string is copied, so the original belongs to you.

Copyright() returns the media file's copyright notice, or NULL if there isn't one. This string belongs to the BMediaFile, so don't delete or change it.

The BMediaFile class doesn't automatically perform any locking to prevent multiple writes to the file from occurring at the same time. If you have multiple threads writing into the same BMediaFile, you must use a locking mechanism (such as a semaphore) to keep writes from overlapping.

RETURN CODES

• B_OK. No error. (AddCopyright() only)

• B_BAD_TYPE. The BMediaFile doesn't reference a valid file. (AddCopyright() only)

• Other errors, depending on the codec. (AddCopyright() only)

CloseFile()

status_t CloseFile(void)

Once all media data has been written to all tracks, you need to call CloseFile() so the BMediaFile object can tidy up the file and finish the writing tasks. If you forget to call CloseFile(), the resulting file may not be complete.

RETURN CODES

• B_OK. No error.

• B_BAD_TYPE. The BMediaFile doesn't reference a valid file.

• Other errors, depending on the codec.

CommitHeader()

status_t CommitHeader(void)

After you've finished adding new tracks to a file, you need to call CommitHeader() to let the BMediaFile set up the file's header. This helps optimize the file writing process.

RETURN CODES

• B_OK. No error.

• B_BAD_TYPE. The BMediaFile doesn't reference a valid file.

• Other errors, depending on the codec.

Copyright() see AddCopyright()

CountTracks()

int32 CountTracks(void) const

Returns the number of tracks in the media file. The return value is undefined if the initialization failed.

CreateTrack()

BMediaTrack *CreateTrack(media_format *mediaFormat,       const media_codec_info *codecInfo) BMediaTrack *CreateTrack(media_format *mediaFormat)

Creates a new track in the file and returns a BMediaTrack object referencing it. The track is configured to use the media format specified by mediaFormat, and will be written using the codec described by codecInfo. You can only use BMediaTrack::WriteFrames() to write into the track.

If you use the second form of the constructor, without a codecInfo argument, the track will be written containing raw media data. You can only use BMediaTrack::WriteChunk() to write into the track.

The mediaFormat indicates the format of the buffers you'll be passing along to the write function, and codecInfo specifies the codec you want to use to encode the data into the track.

The mediaFormat can't contain any wildcards; you have to specify the exact format that you're going to be providing. mediaFormat must also be the same structure you passed to get_net_encoder().

When writing new media files, you should create all your tracks at once before writing any media data. Once all the tracks have been created, be sure to call CommitHeader() to write the header to disk. This is necessary since the header size may vary depending on the number of tracks you put in the file, and once you start writing media data into the tracks, it would be difficult (and inefficient) to resize the header.

If an error occurs while creating the new track, NULL is returned.

GetFileFormatInfo()

status_t GetFileFormatInfo(media_file_format *info) const

Fills the specified media_file_format structure with information describing the file format of the file referenced by the BMediaFile object.

RETURN CODES

• B_OK. No error.

• B_NO_INIT. The BMediaFile doesn't reference a valid file.

GetParameterValue() see SetParameterValue()

GetParameterView()

BView *GetParameterView(void)

Returns a BView containing controls for adjusting the file format's parameters. Returns NULL if there isn't a view available.

InitCheck()

status_t InitCheck(void) const

Returns the result code from the constructor. You should always call this after instantiating a BMediaFile object, but before using it.

RETURN CODES

• B_OK. No error.

• B_MEDIA_NO_HANDLER. No codec available for the required or requested format.

• B_NO_MEMORY. Not enough memory to set up the codec (writing).

• B_BAD_INDEX. The required add-on wasn't found (writing).

• B_MISSING_SYMBOL. The add-on doesn't support writing.

ReleaseTrack() , ReleaseAllTracks()

status_t ReleaseTrack(BMediaTrack *track) status_t ReleaseAllTracks(void)

ReleaseTrack() releases the resources used by the specified track. Doing so reduces your application's memory usage. If you want to release every track you're using, you can call ReleaseAllTracks().

Once released, a track can't be used any longer until you use TrackAt() again.

If the BMediaFile wasn't properly initialized, or the index is invalid, NULL is returned.

RETURN CODES

• B_OK. No error.

• B_ERROR. Couldn't release the track (it may be invalid, or not actually in use).

SetParameterValue() , GetParameterValue()

status_t SetParameterValue(int32 id, const void *value, size_t size) status_t GetParameterValue(int32 id, const void *value, size_t *size)

SetParameterValue() sets the value of the parameter specified by id to the data pointed to by value; this data is size bytes long.

GetParameterValue() returns in value the value of the specified parameter, and the size of the value in bytes in the size argument.

RETURN CODES

• B_OK. No error.

• B_NO_INIT. The BMediaFile doesn't reference a valid file.

TrackAt()

BMediaTrack *TrackAt(int32 index)

Returns a BMediaTrack object referencing the track at the specified index into the file. The index must be a value between 0 and CountTracks() - 1.

If the BMediaFile wasn't properly initialized, or the index is invalid, NULL is returned.

You must call ReleaseTrack() when you're finished with the track.

Web()

BParameterWeb *Web(void)

Returns a BParameterWeb that can be used for configuring the file format's parameters. Returns NULL if the codec doesn't support user configuration.

Constants

Constructor Flags

Declared in:  be/media/MediaFile.h

Constant	Description
B_MEDIA_FILE_REPLACE_MODE	Replace any existing media file, if writing.
B_MEDIA_FILE_NO_READ_AHEAD	Don't read ahead in the file.
B_MEDIA_FILE_UNBUFFERED	Use smaller reads. This can be handy if you're trying to stream low-bitrate files withou;waiting for the extractor to fill a large outgoing buffer.
B_MEDIA_FILE_BIG_BUFFERS	Use large buffers.

These flags control the behavior of the constructor.