/* $Id$ */
/* 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */
#ifndef __PJMEDIA_AVI_STREAM_H__
#define __PJMEDIA_AVI_STREAM_H__

/**
 * @file avi_stream.h
 * @brief AVI file player.
 */
#include <pjmedia/port.h>



PJ_BEGIN_DECL


/**
 * @defgroup PJMEDIA_FILE_PLAY AVI File Player
 * @ingroup PJMEDIA_PORT
 * @brief Video and audio playback from AVI file
 * @{
 */

/**
 * AVI file player options.
 */
enum pjmedia_avi_file_player_option
{
    /**
     * Tell the file player to return NULL frame when the whole
     * file has been played.
     */
    PJMEDIA_AVI_FILE_NO_LOOP = 1
};

/**
 * AVI stream data type.
 */
typedef pjmedia_port pjmedia_avi_stream;

/**
 * Opaque data type for AVI streams. AVI streams is a collection of
 * zero or more AVI stream.
 */
typedef struct pjmedia_avi_streams pjmedia_avi_streams;

/**
 * Create avi streams to play an AVI file. AVI player supports 
 * reading AVI file with uncompressed video format and 
 * 16 bit PCM or compressed G.711 A-law/U-law audio format.
 *
 * @param pool		Pool to create the streams.
 * @param filename	File name to open.
 * @param flags		Avi streams creation flags.
 * @param p_streams	Pointer to receive the avi streams instance.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t)
pjmedia_avi_player_create_streams(pj_pool_t *pool,
                                  const char *filename,
                                  unsigned flags,
                                  pjmedia_avi_streams **p_streams);

/**
 * Get the number of AVI stream.
 *
 * @param streams	The AVI streams.
 *
 * @return		The number of AVI stream.
 */
PJ_DECL(unsigned)
pjmedia_avi_streams_get_num_streams(pjmedia_avi_streams *streams);

/**
 * Return the idx-th stream of the AVI streams.
 *
 * @param streams	The AVI streams.
 * @param idx	        The stream index.
 *
 * @return		The AVI stream or NULL if it does not exist.
 */
PJ_DECL(pjmedia_avi_stream *)
pjmedia_avi_streams_get_stream(pjmedia_avi_streams *streams,
                               unsigned idx);

/**
 * Return an AVI stream with a certain media type from the AVI streams.
 *
 * @param streams	The AVI streams.
 * @param start_idx     The starting index.
 * @param media_type    The media type of the stream.
 *
 * @return		The AVI stream or NULL if it does not exist.
 */
PJ_DECL(pjmedia_avi_stream *)
pjmedia_avi_streams_get_stream_by_media(pjmedia_avi_streams *streams,
                                        unsigned start_idx,
                                        pjmedia_type media_type);

/**
 * Return the media port of an AVI stream.
 *
 * @param stream	The AVI stream.
 *
 * @return		The media port.
 */
PJ_INLINE(pjmedia_port *)
pjmedia_avi_stream_get_port(pjmedia_avi_stream *stream)
{
    return (pjmedia_port *)stream;
}

/**
 * Get the data length, in bytes.
 *
 * @param stream        The AVI stream.
 *
 * @return		The length of the data, in bytes. Upon error it will
 *			return negative value.
 */
PJ_DECL(pj_ssize_t) pjmedia_avi_stream_get_len(pjmedia_avi_stream *stream);


#if !DEPRECATED_FOR_TICKET_2251
/**
 * Register a callback to be called when the file reading has reached the
 * end of file. If the file is set to play repeatedly, then the callback
 * will be called multiple times. Note that only one callback can be 
 * registered for each AVI stream.
 *
 * @param stream	The AVI stream.
 * @param user_data	User data to be specified in the callback
 * @param cb		Callback to be called. If the callback returns non-
 *			PJ_SUCCESS, the playback will stop. Note that if
 *			application destroys the file port in the callback,
 *			it must return non-PJ_SUCCESS here.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_avi_stream_set_eof_cb(pjmedia_avi_stream *stream,
			      void *user_data,
			      pj_status_t (*cb)(pjmedia_avi_stream *stream,
					        void *usr_data));
#endif


/**
 * Register a callback to be called when the file reading has reached the
 * end of file. If the file is set to play repeatedly, then the callback
 * will be called multiple times. Note that only one callback can be 
 * registered for each AVI stream.
 *
 * @param stream	The AVI stream.
 * @param user_data	User data to be specified in the callback
 * @param cb		Callback to be called. Note that if
 *			application wishes to stop the playback, it
 *			can disconnect the port in the callback, and
 *			only after all connections have been removed
 *			could the application safely destroy the port.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_avi_stream_set_eof_cb2(pjmedia_avi_stream *stream,
			       void *user_data,
			       void (*cb)(pjmedia_avi_stream *stream,
					  void *usr_data));


/**
 * @}
 */


PJ_END_DECL


#endif	/* __PJMEDIA_AVI_STREAM_H__ */