:orphan:

.. index:: pair: group; Test API to control a media player
.. _doxid-group__tapi__media__player:

Test API to control a media player
==================================

.. toctree::
	:hidden:

	enum_tapi_media_player_client.rst
	enum_tapi_media_player_error.rst
	struct_tapi_media_player.rst
	struct_tapi_media_player_methods.rst

Overview
~~~~~~~~

Generic high level test API to control a media player. :ref:`More...<details-group__tapi__media__player>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// typedefs

	typedef enum :ref:`tapi_media_player_client<doxid-group__tapi__media__player_1gac9da2735612e84ba6bff5ad3d8b1b3d3>` :ref:`tapi_media_player_client<doxid-group__tapi__media__player_1ga859da7ae8f60f77ca1970c981b5da405>`;
	typedef enum :ref:`tapi_media_player_error<doxid-group__tapi__media__player_1ga5ef6dcbcd56a034682c01571dd017ebe>` :ref:`tapi_media_player_error<doxid-group__tapi__media__player_1gab0217bfad1e5c6a007a88281e8c0bd14>`;
	typedef struct :ref:`tapi_media_player<doxid-structtapi__media__player>` :ref:`tapi_media_player<doxid-group__tapi__media__player_1gad91adf61c68ea26f9e227e6415aa0643>`;

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`tapi_media_player_method_play<doxid-group__tapi__media__player_1gacb1ad017c73a3ec53dfb7cf9f8906b6e>`)(
		tapi_media_player *player,
		const char *source,
		const char *options
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`tapi_media_player_method_stop<doxid-group__tapi__media__player_1ga05b27db9abc708d30a30232647410319>`)(tapi_media_player *player);
	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`tapi_media_player_method_get_errors<doxid-group__tapi__media__player_1gabe7a4c70538e84b8fe90b82827402038>`)(tapi_media_player *player);
	typedef struct :ref:`tapi_media_player_methods<doxid-structtapi__media__player__methods>` :ref:`tapi_media_player_methods<doxid-group__tapi__media__player_1gac7456d35b1a47b69d84476378a9ef246>`;

	// enums

	enum :ref:`tapi_media_player_client<doxid-group__tapi__media__player_1gac9da2735612e84ba6bff5ad3d8b1b3d3>`;
	enum :ref:`tapi_media_player_error<doxid-group__tapi__media__player_1ga5ef6dcbcd56a034682c01571dd017ebe>`;

	// structs

	struct :ref:`tapi_media_player<doxid-structtapi__media__player>`;
	struct :ref:`tapi_media_player_methods<doxid-structtapi__media__player__methods>`;

	// global functions

	:ref:`tapi_media_player<doxid-structtapi__media__player>`* :ref:`tapi_media_player_create<doxid-group__tapi__media__player_1ga193aed4bfc3399dedc8150711ff64104>`(const char* ta, :ref:`tapi_media_player_client<doxid-group__tapi__media__player_1gac9da2735612e84ba6bff5ad3d8b1b3d3>` client, const char* player);
	void :ref:`tapi_media_player_destroy<doxid-group__tapi__media__player_1ga41fd762cac9d87130125262f7e6ff3d1>`(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_media_player_play<doxid-group__tapi__media__player_1gae636c07a0d916523c5a3bee9e8ca1f04>`(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player, const char* source, const char* options);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_media_player_stop<doxid-group__tapi__media__player_1ga90833d2341c4d5483c3f982a75847a7d>`(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`tapi_media_player_get_errors<doxid-group__tapi__media__player_1ga650820e40d6e4e2112b67ceda671e454>`(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player);
	bool :ref:`tapi_media_player_check_errors<doxid-group__tapi__media__player_1ga42b149cc33f3cf3ba5481e644f7efff9>`(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player);
	void :ref:`tapi_media_player_log_errors<doxid-group__tapi__media__player_1ga1af97419d43c2c129170bd2bb45d1f0d>`(const :ref:`tapi_media_player<doxid-structtapi__media__player>`* player);

.. _details-group__tapi__media__player:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Generic high level test API to control a media player.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs
--------

.. index:: pair: typedef; tapi_media_player_client
.. _doxid-group__tapi__media__player_1ga859da7ae8f60f77ca1970c981b5da405:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef enum :ref:`tapi_media_player_client<doxid-group__tapi__media__player_1gac9da2735612e84ba6bff5ad3d8b1b3d3>` tapi_media_player_client

Supported media players list.

.. index:: pair: typedef; tapi_media_player_error
.. _doxid-group__tapi__media__player_1gab0217bfad1e5c6a007a88281e8c0bd14:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef enum :ref:`tapi_media_player_error<doxid-group__tapi__media__player_1ga5ef6dcbcd56a034682c01571dd017ebe>` tapi_media_player_error

List of possible playback errors.

.. index:: pair: typedef; tapi_media_player
.. _doxid-group__tapi__media__player_1gad91adf61c68ea26f9e227e6415aa0643:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_media_player<doxid-structtapi__media__player>` tapi_media_player

Media player access point.

.. index:: pair: typedef; tapi_media_player_method_play
.. _doxid-group__tapi__media__player_1gacb1ad017c73a3ec53dfb7cf9f8906b6e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*tapi_media_player_method_play)(
		tapi_media_player *player,
		const char *source,
		const char *options
		)

Play a media file.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player handle.

	*
		- source

		- Audio or video file to play (link or local pathname).

	*
		- options

		- Custom options to pass to player run command line or ``NULL`` to use default ones.



.. rubric:: Returns:

Status code.

.. index:: pair: typedef; tapi_media_player_method_stop
.. _doxid-group__tapi__media__player_1ga05b27db9abc708d30a30232647410319:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*tapi_media_player_method_stop)(tapi_media_player *player)

Stop playback.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player handle.



.. rubric:: Returns:

Status code.

.. index:: pair: typedef; tapi_media_player_method_get_errors
.. _doxid-group__tapi__media__player_1gabe7a4c70538e84b8fe90b82827402038:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*tapi_media_player_method_get_errors)(tapi_media_player *player)

Parse player **stderr** stream and count playback errors, the counters are located in ``player.errors``.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player handle.



.. rubric:: Returns:

Status code.

.. index:: pair: typedef; tapi_media_player_methods
.. _doxid-group__tapi__media__player_1gac7456d35b1a47b69d84476378a9ef246:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_media_player_methods<doxid-structtapi__media__player__methods>` tapi_media_player_methods

Methods to operate the server.

Global Functions
----------------

.. index:: pair: function; tapi_media_player_create
.. _doxid-group__tapi__media__player_1ga193aed4bfc3399dedc8150711ff64104:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`tapi_media_player<doxid-structtapi__media__player>`* tapi_media_player_create(const char* ta, :ref:`tapi_media_player_client<doxid-group__tapi__media__player_1gac9da2735612e84ba6bff5ad3d8b1b3d3>` client, const char* player)

Create media player access point. Start aux RPC server and initialize hooks. Note, **tapi_media_player_destroy** must be called to release resources.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- ta

		- Test agent name.

	*
		- client

		- Program to play media.

	*
		- player

		- Pathname to the player, or ``NULL`` to use default for specified client.



.. rubric:: Returns:

Acccess point.



.. rubric:: See also:

:ref:`tapi_media_player_destroy <doxid-group__tapi__media__player_1ga41fd762cac9d87130125262f7e6ff3d1>`

.. index:: pair: function; tapi_media_player_destroy
.. _doxid-group__tapi__media__player_1ga41fd762cac9d87130125262f7e6ff3d1:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void tapi_media_player_destroy(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player)

Destroy media player access point: stop playback, stop RPC server, and release resources.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- The player access point (can be ``NULL`` to call in cleanup)



.. rubric:: See also:

:ref:`tapi_media_player_create <doxid-group__tapi__media__player_1ga193aed4bfc3399dedc8150711ff64104>`

.. index:: pair: function; tapi_media_player_play
.. _doxid-group__tapi__media__player_1gae636c07a0d916523c5a3bee9e8ca1f04:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_media_player_play(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player, const char* source, const char* options)

Play a media file.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player handle.

	*
		- source

		- Audio or video file to play (link or local pathname).

	*
		- options

		- Custom options to pass to player run command line or ``NULL`` to use default ones.



.. rubric:: Returns:

Status code.

.. index:: pair: function; tapi_media_player_stop
.. _doxid-group__tapi__media__player_1ga90833d2341c4d5483c3f982a75847a7d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_media_player_stop(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player)

Stop playback.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player handle.



.. rubric:: Returns:

Status code.

.. index:: pair: function; tapi_media_player_get_errors
.. _doxid-group__tapi__media__player_1ga650820e40d6e4e2112b67ceda671e454:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` tapi_media_player_get_errors(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player)

Parse player **stderr** stream and count playback errors, the counters are located in ``player.errors``.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player handle.



.. rubric:: Returns:

Status code.

.. index:: pair: function; tapi_media_player_check_errors
.. _doxid-group__tapi__media__player_1ga42b149cc33f3cf3ba5481e644f7efff9:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool tapi_media_player_check_errors(:ref:`tapi_media_player<doxid-structtapi__media__player>`* player)

Check if there were errors during media playback. (Actually just check if counters are zero).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player access point.



.. rubric:: Returns:

``true`` if there are errors in counters.

.. index:: pair: function; tapi_media_player_log_errors
.. _doxid-group__tapi__media__player_1ga1af97419d43c2c129170bd2bb45d1f0d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void tapi_media_player_log_errors(const :ref:`tapi_media_player<doxid-structtapi__media__player>`* player)

Print a number of errors sorted by type which were occurred during media playback using RING function.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- player

		- Player access point.