librmff.h File Reference

The RealMedia file format library. More...

#include "os.h"
#include <inttypes.h>
#include <stdio.h>
#include "mb_file_io.h"

Go to the source code of this file.

Data Structures
struct	rmff_object_t
	The common object handler. It precedes all the other headers. More...
struct	rmff_rmf_t
	The main file header. It is located at the very beginning of the file. More...
struct	rmff_prop_t
	The global PROP file header. More...
struct	rmff_cont_t
	Comments about the file in question. More...
struct	rmff_mdpr_t
	The MDPR track headers. More...
struct	rmff_index_entry_t
struct	rmff_frame_t
	A frame or packet of media data. More...
struct	rmff_track_t
struct	rmff_file_t
Defines
#define	RMFF_VERSION_MAJOR   0
#define	RMFF_VERSION_MINOR   6
#define	RMFF_VERSION_MICRO   2
#define	RMFF_VERSION
#define	RMFF_FILE_FLAG_SAVE_ENABLED   0x0001
	The stream may be saved to disc. Can be set in the PROP header.
#define	RMFF_FILE_FLAG_PERFECT_PLAY   0x0002
	Allows the client to use extra buffering. Can be set in the PROP header.
#define	RMFF_FILE_FLAG_LIVE_BROADCAST   0x0004
	The stream is being generated by a live broadcast. Can be set in the PROP header.
#define	RMFF_FILE_FLAG_DOWNLOAD_ENABLED   0x0008
	The stream may be downloaded. Can be set in the PROP header.
#define	RMFF_FRAME_FLAG_RELIABLE   0x01
	The packet is being delivered reliably. Can be set in the rmff_frame_t::flags member.
#define	RMFF_FRAME_FLAG_KEYFRAME   0x02
	The frame is a key frame. Can be set in the rmff_frame_t::flags member.
#define	RMFF_TRACK_TYPE_UNKNOWN   0
	Unknown track type.
#define	RMFF_TRACK_TYPE_AUDIO   1
	The track contains audio data.
#define	RMFF_TRACK_TYPE_VIDEO   2
	The track contains video data.
#define	RMFF_ERR_OK   0
	No error has occured.
#define	RMFF_ERR_NOT_RMFF   -1
	The file is not a valid RealMedia file.
#define	RMFF_ERR_DATA   -2
	The structures/data read from the file were invalid.
#define	RMFF_ERR_EOF   -3
	The end of the file has been reached.
#define	RMFF_ERR_IO   -4
	An error occured during file I/O.
#define	RMFF_ERR_PARAMETERS   -5
	The parameters were invalid.
#define	RMFF_ERR_CHECK_ERRNO   -6
	An error has occured for which errno should be consulted.
#define	rmffFOURCC(a, b, c, d)
	Convert the four bytes into a 'FOURCC' uint32.
#define	RMFF_OPEN_MODE_READING   0
	Open the file for reading.
#define	RMFF_OPEN_MODE_WRITING   1
	Create a new file.
#define	rmff_get_uint32_me(b)   rmff_get_uint32_le(b)
#define	rmff_put_uint32_me(b)   rmff_put_uint32_le(b)
Typedefs
typedef rmff_object_t	rmff_object_t
	The common object handler. It precedes all the other headers.
typedef rmff_rmf_t	rmff_rmf_t
	The main file header. It is located at the very beginning of the file.
typedef rmff_prop_t	rmff_prop_t
	The global PROP file header.
typedef rmff_cont_t	rmff_cont_t
	Comments about the file in question.
typedef rmff_mdpr_t	rmff_mdpr_t
	The MDPR track headers.
typedef rmff_index_entry_t	rmff_index_entry_t
typedef rmff_frame_t	rmff_frame_t
	A frame or packet of media data.
typedef rmff_track_t	rmff_track_t
typedef rmff_file_t	rmff_file_t
Functions
struct	__attribute__ ((__packed__)) real_video_props_t
rmff_file_t *	rmff_open_file (const char *path, int mode)
	Opens a RealMedia file for reading or writing.
rmff_file_t *	rmff_open_file_with_io (const char *path, int mode, mb_file_io_t *io)
	Opens a RealMedia file for reading or writing.
void	rmff_close_file (rmff_file_t *file)
	Close the file and release all resources.
int	rmff_read_headers (rmff_file_t *file)
	Reads the file and track headers.
int	rmff_get_next_frame_size (rmff_file_t *file)
	Retrieves the size of the next frame.
rmff_frame_t *	rmff_read_next_frame (rmff_file_t *file, void *buffer)
	Reads the next frame from the file.
rmff_frame_t *	rmff_allocate_frame (uint32_t size, void *buffer)
	Allocates a frame and possibly a buffer for its contents.
void	rmff_release_frame (rmff_frame_t *frame)
	Frees all resources associated with a frame.
rmff_track_t *	rmff_add_track (rmff_file_t *file, int create_index)
	Creates a new track for a file.
void	rmff_set_std_audio_v4_values (real_audio_v4_props_t *props)
	Set some default values for RealAudio streams.
void	rmff_set_std_audio_v5_values (real_audio_v5_props_t *props)
	Set some default values for RealAudio streams.
void	rmff_set_std_video_values (real_video_props_t *props)
	Set some default values for RealVideo streams.
void	rmff_set_cont_header (rmff_file_t *file, const char *title, const char *author, const char *copyright, const char *comment)
	Sets the contents of the CONT file header .
void	rmff_set_track_data (rmff_track_t *track, const char *name, const char *mime_type)
	Sets the strings in the MDPR track header structure.
void	rmff_set_type_specific_data (rmff_track_t *track, const unsigned char *data, uint32_t size)
	Sets the track_specific_data member of the MDPR header structure.
int	rmff_write_headers (rmff_file_t *file)
	Writes the file and track headers.
int	rmff_fix_headers (rmff_file_t *file)
	Fixes some values in the headers and re-writes them.
int	rmff_write_frame (rmff_track_t *track, rmff_frame_t *frame)
	Writes the frame contents to the file.
int	rmff_write_packed_video_frame (rmff_track_t *track, rmff_frame_t *frame)
	Unpacks a packed video frame into sub packets and writes each.
int	rmff_assemble_packed_video_frame (rmff_track_t *track, rmff_frame_t *frame)
	Parses a sub packet and attempts to assemble a packed video frame.
rmff_frame_t *	rmff_get_packed_video_frame (rmff_track_t *track)
	Retrieve an assembled video frame.
int	rmff_write_index (rmff_file_t *file)
	Creates an index at the end of the file.
void	rmff_copy_track_headers (rmff_track_t *dst, rmff_track_t *src)
	Duplicated the track headers.
rmff_track_t *	rmff_find_track_with_id (rmff_file_t *file, uint16_t id)
	Finds the track the track ID belongs to.
const char *	rmff_get_error_str (int code)
	Map an error code to an error message.
uint16_t	rmff_get_uint16_be (const void *buf)
	Reads a 16bit uint from an address.
uint32_t	rmff_get_uint32_be (const void *buf)
	Reads a 32bit uint from an address.
uint32_t	rmff_get_uint32_le (const void *buf)
	Reads a 32bit uint from an address.
void	rmff_put_uint16_be (void *buf, uint16_t value)
	Write a 16bit uint at an address.
void	rmff_put_uint32_be (void *buf, uint32_t value)
	Write a 32bit uint at an address.
void	rmff_put_uint32_le (void *buf, uint32_t value)
	Write a 32bit uint at an address.
Variables
	real_video_props_t
	real_audio_v4_props_t
	real_audio_v5_props_t
int	rmff_last_error
	The error code of the last function call.
const char *	rmff_last_error_msg
	The error message of the last function call.

---

Detailed Description

The RealMedia file format library.

Author:

Moritz Bunkus <moritz@bunkus.org>

Id

librmff.h 1802 2004-06-24 14:18:15Z mosu

---

Define Documentation

#define RMFF_VERSION

Value: (RMFF_VERSION_MAJOR * 10000 + RMFF_VERSION_MINOR * 100 + \ RMFF_VERSION_MICRO)

#define rmffFOURCC (  a, b, c, d   )

Value: (uint32_t)((((unsigned char)a) << 24) + \ (((unsigned char)b) << 16) + \ (((unsigned char)c) << 8) + \ ((unsigned char)d)) Convert the four bytes into a 'FOURCC' uint32.

---

Typedef Documentation

typedef struct rmff_cont_t rmff_cont_t

Comments about the file in question. This structure contains the parsed values of the CONT header. These strings must not be modified by the application. The function rmff_set_cont_header must be used instead.

typedef struct rmff_frame_t rmff_frame_t

A frame or packet of media data. A new frame can be obtained with rmff_allocate_frame or read from a file with rmff_read_next_frame. In both cases the application can either have librmff allocate a buffer for the frame contents or provide the buffer itself. In the latter case rmff_release_frame will not free the buffer either. Note: The fields in this structure are stored in the machine's byte order which is little endian on x86 systems.

typedef struct rmff_mdpr_t rmff_mdpr_t

The MDPR track headers. Each track in a RealMedia file contains the MDPR header. The values are stored in big endian byte order. The application should use the functions rmff_get_uint16_be, rmff_get_uint32_be, rmff_put_uint16_be and rmff_put_uint32_be for accessing the members.

typedef struct rmff_prop_t rmff_prop_t

The global PROP file header. This header is mandatory for a RealMedia file. It contains statistical and global data. The values are stored in big endian byte order. The application should use the functions rmff_get_uint16_be, rmff_get_uint32_be, rmff_put_uint16_be and rmff_put_uint32_be for accessing the members.

---

Function Documentation

rmff_track_t* rmff_add_track (  rmff_file_t *  file, int  create_index )

Creates a new track for a file. The track will be added to the list of tracks in this file. librmff will allocate a track ID that is unique in this file. Parameters: file  The file the track will be added to. create_index  Indicates if librmff should create an index for this track that'll be written to the file when rmff_write_index is invoked. Returns: A pointer to a newly allocated ::rmff_track_t structure or NULL in case of an error.

rmff_frame_t* rmff_allocate_frame (  uint32_t  size, void *  buffer )

Allocates a frame and possibly a buffer for its contents. Parameters: size  The size of this frame. buffer  A buffer that holds the frame. This parameter may be NULL in which case the buffer will be allocated by the library. If the application provides the buffer it must be large enough. Returns: a pointer to an empty rmff_frame_t structure which can be filled with the frame contents and its metadata. This frame must be freed with rmff_release_frame.

int rmff_assemble_packed_video_frame (  rmff_track_t *  track, rmff_frame_t *  frame )

Parses a sub packet and attempts to assemble a packed video frame. Please see the section about packed video Packed video frames frames for a description of this function. This function takes a sub packet as they are stored in a RealMedia file and attempts to assemble the complete packet. More than one call to this function with consecutive frames read from a file are likely necessary before a complete frame can be assembled. The function rmff_get_packed_video_frame can be used to retrieve the assembled frames. These two functions, rmff_assemble_packed_video_frame and rmff_get_packed_video_frame, are the counterparts to rmff_write_packed_video_frame. Parameters: track  The track this frame belongs to. frame  The sub packet that should be assembled. Returns: one of the other RMFF_ERR_* constants on error and the number of available assembled frames on success.

void rmff_close_file (  rmff_file_t *  file  )

Close the file and release all resources. Closes the file and releases all resources associated with it, including the ::rmff_file_t structure. If the file was open for writing then rmff_fix_headers should be called prior to closing the file as rmff_close_file does not fix the headers itself. Parameters: file  The file to close.

void rmff_copy_track_headers (  rmff_track_t *  dst, rmff_track_t *  src )

Duplicated the track headers. Takes a ::rmff_track_t structure and duplicates its members into another one. The destination must have been created first with rmff_add_track. Everything but the track ID will be copied. Parameters: dst  The destination to write the copies to. src  The structure that should be duplicated.

rmff_track_t* rmff_find_track_with_id (  rmff_file_t *  file, uint16_t  id )

Finds the track the track ID belongs to. Parameters: file  The file whose tracks are to be searched. id  The track ID. Returns: A pointer to a ::rmff_track_t structure or NULL on error.

int rmff_fix_headers (  rmff_file_t *  file  )

Fixes some values in the headers and re-writes them. librmff automatically calculates some header values, e.g. the max_packet_size fields and the offsets in the file headers. This function updates these values and writes them to the file. It should be called before rmff_close_file. Parameters: file  The file whose headers should be fixed and written. Returns: RMFF_ERR_OK on success or one of the other RMFF_ERR_* constants on error.

const char* rmff_get_error_str (  int  code  )

Map an error code to an error message. Returns the error message that corresponds to the error code. Parameters: code  the error code which must be one of the RMFF_ERR_* macros. Returns: the error message or "Unknown error" for unknown error codes, but never NULL.

int rmff_get_next_frame_size (  rmff_file_t *  file  )

Retrieves the size of the next frame. Parameters: file  The file to read from. Returns: the size of the following frame or one of the RMFF_ERR_* constants on error.

rmff_frame_t* rmff_get_packed_video_frame (  rmff_track_t *  track  )

Retrieve an assembled video frame. Please see the section about packed video Packed video frames frames for a description of this function. This function returns one assembled video frame after some calls to rmff_assemble_packed_video_frame. These two functions, rmff_assemble_packed_video_frame and rmff_get_packed_video_frame, are the counterparts to rmff_write_packed_video_frame. Parameters: track  The track an assembled frame should be read from. Returns: an assembled frame on success or NULL if there's none available.

uint16_t rmff_get_uint16_be (  const void *  buf  )

Reads a 16bit uint from an address. The uint is converted from big endian byte order to the machine's byte order. Parameters: buf  The address to read from. Returns: The 16bit uint converted to the machine's byte order.

uint32_t rmff_get_uint32_be (  const void *  buf  )

Reads a 32bit uint from an address. The uint is converted from big endian byte order to the machine's byte order. Parameters: buf  The address to read from. Returns: The 32bit uint converted to the machine's byte order.

uint32_t rmff_get_uint32_le (  const void *  buf  )

Reads a 32bit uint from an address. The uint is converted from little endian byte order to the machine's byte order. Parameters: buf  The address to read from. Returns: The 32bit uint converted to the machine's byte order.

rmff_file_t* rmff_open_file (  const char *  path, int  mode )

Opens a RealMedia file for reading or writing. Can be used to open an existing file for reading or for creating a new file. The file headers will neither be read nor written automatically. This function uses the standard file I/O functions provided by the current operating system. Parameters: path  the name of the file that should be opened mode  either RMFF_OPEN_MODE_READING or RMFF_OPEN_MODE_WRITING Returns: a pointer to ::rmff_file_t structure or NULL if an error occured. In the latter case rmff_last_error will be set. See also: rmff_open_file_with_io

rmff_file_t* rmff_open_file_with_io (  const char *  path, int  mode, mb_file_io_t *  io )

Opens a RealMedia file for reading or writing. Can be used to open an existing file for reading or for creating a new file. The file headers will neither be read nor written automatically. This function uses I/O functions provided by the io parameter. Parameters: path  the name of the file that should be opened mode  either RMFF_OPEN_MODE_READING or RMFF_OPEN_MODE_WRITING io  a set of I/O functions Returns: a pointer to a rmff_file_t structure or NULL if an error occured. In the latter case rmff_last_error will be set. See also: rmff_open_file

void rmff_put_uint16_be (  void *  buf, uint16_t  value )

Write a 16bit uint at an address. The value is converted from the machine's byte order to big endian byte order. Parameters: buf  The address to write to. value  The value to write.

void rmff_put_uint32_be (  void *  buf, uint32_t  value )

Write a 32bit uint at an address. The value is converted from the machine's byte order to big endian byte order. Parameters: buf  The address to write to. value  The value to write.

void rmff_put_uint32_le (  void *  buf, uint32_t  value )

Write a 32bit uint at an address. The value is converted from the machine's byte order to little endian byte order. Parameters: buf  The address to write to. value  The value to write.

int rmff_read_headers (  rmff_file_t *  file  )

Reads the file and track headers. This function should be called after directly after opening it for reading. It will try to read the file and track headers and position the file pointer right before the first data packet. Parameters: file  The file to read the headers from. Returns: RMFF_ERR_OK on success and one of the other RMFF_ERR_* constants on error.

rmff_frame_t* rmff_read_next_frame (  rmff_file_t *  file, void *  buffer )

Reads the next frame from the file. The frame must be released by rmff_release_frame(rmff_frame_t*). Parameters: file  The file to read from. buffer  A buffer to read the frame into. This parameter may be NULL in which case the buffer will be allocated by the library. If the application provides the buffer it must be large enough. The function rmff_get_next_frame_size can be used in this case. Returns: a pointer to a rmff_frame_t structure containing the frame and its metadata on success or NULL if the call failed. This frame must be freed with rmff_release_frame.

void rmff_release_frame (  rmff_frame_t *  frame  )

Frees all resources associated with a frame. If the frame buffer was allocated by the library it will be freed as well. Parameters: frame  The frame to free.

void rmff_set_cont_header (  rmff_file_t *  file, const char *  title, const char *  author, const char *  copyright, const char *  comment )

Sets the contents of the CONT file header . Frees the old contents if any and allocates copies of the given strings. If the CONT header should be written to the file in ""rmff_write_headers then the cont_header_present member must be set to 1. Parameters: file  The file whose CONT header should be set. title  The file's title, e.g. "Muriel's Wedding" author  The file's author, e.g. "P.J. Hogan" copyright  The copyright assigned to the file. comment  A free-style comment.

void rmff_set_std_audio_v4_values (  real_audio_v4_props_t *  props  )

Set some default values for RealAudio streams. Some of the fields in the props structure will be set to pre-defined values, especially the uknown fields. Should be used after rmff_add_track. Note: This function has not been implemented yet. Parameters: props  A pointer to the structure whose values should be set. See also: rmff_set_std_audio_v5_values(real_audio_v5_props_t*), rmff_set_std_video_values(real_video_props_t*)

void rmff_set_std_audio_v5_values (  real_audio_v5_props_t *  props  )

Set some default values for RealAudio streams. Some of the fields in the props structure will be set to pre-defined values, especially the uknown fields. Should be used after rmff_add_track. Note: This function has not been implemented yet. Parameters: props  A pointer to the structure whose values should be set. See also: rmff_set_std_audio_v4_values(real_audio_v5_props_t*), rmff_set_std_video_values(real_video_props_t*)

void rmff_set_std_video_values (  real_video_props_t *  props  )

Set some default values for RealVideo streams. Some of the fields in the props structure will be set to pre-defined values, especially the uknown fields. Should be used after rmff_add_track. Note: This function has not been implemented yet. Parameters: props  A pointer to the structure whose values should be set. See also: rmff_set_std_audio_v4_values(real_audio_v4_props_t*), rmff_set_std_audio_v5_values(real_audio_v5_props_t*)

void rmff_set_track_data (  rmff_track_t *  track, const char *  name, const char *  mime_type )

Sets the strings in the MDPR track header structure. Frees the old contents and allocates copies of the given strings. Parameters: track  The track whose MDPR header should be set. name  The track's name. mime_type  The MIME type. A video track should have the MIME type video/x-pn-realvideo, and an audio track should have the MIMT type audio/x-pn-realaudio.

void rmff_set_type_specific_data (  rmff_track_t *  track, const unsigned char *  data, uint32_t  size )

Sets the track_specific_data member of the MDPR header structure. The track_specific_data usually contains a ::real_video_props_t structure or a ::real_audio_props_t structure. The existing data, if any, will be freed, and a copy of the memory data points to will be made. Parameters: track  The track whose MDPR header should be set. data  A pointer to the track specific data. size  The track specific data's size in bytes.

int rmff_write_frame (  rmff_track_t *  track, rmff_frame_t *  frame )

Writes the frame contents to the file. Should be called after rmff_write_headers. The track ID stored in the track parameter will overwrite the track ID in the frame structure. Parameters: track  The track this frame belongs to. frame  The frame data to write. Returns: RMFF_ERR_OK on success or one of the other RMFF_ERR_* constants on error.

int rmff_write_headers (  rmff_file_t *  file  )

Writes the file and track headers. This function should be called after adding all tracks and before the first call to rmff_write_frame. Before closing the file the application should call rmff_fix_headers in order to write the corrected header values. Parameters: file  The file whose headers should be written. Returns: RMFF_ERR_OK on success or one of the other RMFF_ERR_* constants on error.

int rmff_write_index (  rmff_file_t *  file  )

Creates an index at the end of the file. The application can request that an index is created For each track with the rmff_add_track call. For each of these tracks an index is created in which each key frame is listed. Consecutive key frames with the same timecode only get one index entry. This function should be called after all calls to rmff_write_frame but before rmff_fix_headers. Parameters: file  The file for which the index should be written. Returns: RMFF_ERR_OK on success or one of the other RMFF_ERR_* constants on error.

int rmff_write_packed_video_frame (  rmff_track_t *  track, rmff_frame_t *  frame )

Unpacks a packed video frame into sub packets and writes each. Please see the section about packed video Packed video frames frames for a description of this function. This function takes such a complete frame, splits it up into their sub packets and writes each sub packet out into the file this track belongs to. Parameters: track  The track this frame belongs to. frame  The assembled/packed video frame that is to be split up. Returns: RMFF_ERR_OK on success or one of the other RMFF_ERR_* constants on error.

---

Variable Documentation

int rmff_last_error

The error code of the last function call. Contains the last error code for a function that failed. If a function succeeded it usually does not reset rmff_last_error to RMFF_ERR_OK. This variable can contain one of the RMFF_ERR_* constants.

const char* rmff_last_error_msg

The error message of the last function call. Contains the last error message for a function that failed. If a function succeeded it usually does not reset rmff_last_error_msg to NULL.

---