:orphan:

.. index:: pair: group; Test Agents: Command Handler
.. _doxid-group__rcf__ch:

Test Agents: Command Handler
============================

.. toctree::
	:hidden:

	group_rcf_ch_cfg.rst
	group_rcf_ch_file.rst
	group_rcf_ch_func.rst
	group_rcf_ch_proc.rst
	group_rcf_ch_reboot.rst
	group_rcf_ch_addr.rst
	group_rcf_ch_tad.rst
	group_rcf_ch_var.rst

Overview
~~~~~~~~

Common Handler (CH) is an interface to hide the details of Test Agent implementation for Portable Command Handler (PCH). :ref:`More...<details-group__rcf__ch>`

|	:ref:`Command Handler: Configuration support<doxid-group__rcf__ch__cfg>`
|		:ref:`Configuration node definition macros<doxid-group__rcf__ch__cfg__node__def>`
|	:ref:`Command Handler: File manipulation support<doxid-group__rcf__ch__file>`
|	:ref:`Command Handler: Function call support<doxid-group__rcf__ch__func>`
|	:ref:`Command Handler: Process/thread support<doxid-group__rcf__ch__proc>`
|	:ref:`Command Handler: Reboot and shutdown support<doxid-group__rcf__ch__reboot>`
|	:ref:`Command Handler: Symbol name and address resolver support<doxid-group__rcf__ch__addr>`
|	:ref:`Command Handler: Traffic Application Domain (TAD) support<doxid-group__rcf__ch__tad>`
|	:ref:`Command Handler: Variables support<doxid-group__rcf__ch__var>`



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

	
	// typedefs

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`rcf_rtn<doxid-group__rcf__ch_1ga969901275a112e6b1cfea69d53e3b98c>`)(
		void *arg,
		...
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`rcf_thr_rtn<doxid-group__rcf__ch_1ga1d245a451fc483ff44559bcd7366e378>`)(
		void *sem,
		void *arg,
		...
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`rcf_argv_rtn<doxid-group__rcf__ch_1gafb43a2355c76f48c6ab1d94c6b02f970>`)(
		int argv,
		char **argc
		);

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`rcf_argv_thr_rtn<doxid-group__rcf__ch_1ga5a5c715d8aa4d72a910124593d1dbd59>`)(
		void *sem,
		int argc,
		char **argv
		);

	// global functions

	int :ref:`rcf_ch_init<doxid-group__rcf__ch_1gab19d7b2f3a4265eb5bfd919d6db509d2>`(void);
	void :ref:`rcf_ch_lock<doxid-group__rcf__ch_1ga54e87ddcaa8b26520bb5782c10a26ecb>`(void);
	void :ref:`rcf_ch_unlock<doxid-group__rcf__ch_1gace92be5ae80ce7a5111c47636d4fe671>`(void);

	// macros

	#define :ref:`RCF_CH_LOCK<doxid-group__rcf__ch_1gada9c38da6bbb7d323a467378063f4d15>`
	#define :ref:`RCF_CH_UNLOCK<doxid-group__rcf__ch_1ga79d9f5e9d33598de9736ebce6af42853>`
	#define :ref:`RCF_PCH_CFG_SUBST_SET<doxid-group__rcf__ch_1gaad861f62ce20add7dae94edc91e7f91b>`(...)

.. _details-group__rcf__ch:

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

Common Handler (CH) is an interface to hide the details of Test Agent implementation for Portable Command Handler (PCH). When you support a new type of Test Agent you will need to implement only these set of functions to let other TE components access functionality exported by your Test Agent in generic way.

Definition of these functions could be found under ``${TE_BASE}/agents/[agent type]`` directory.

Typedefs
--------

.. index:: pair: typedef; rcf_rtn
.. _doxid-group__rcf__ch_1ga969901275a112e6b1cfea69d53e3b98c:

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

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*rcf_rtn)(
		void *arg,
		...
		)

Generic routine prototype

.. index:: pair: typedef; rcf_thr_rtn
.. _doxid-group__rcf__ch_1ga1d245a451fc483ff44559bcd7366e378:

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

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*rcf_thr_rtn)(
		void *sem,
		void *arg,
		...
		)

Generic threaded routine prototype

.. index:: pair: typedef; rcf_argv_rtn
.. _doxid-group__rcf__ch_1gafb43a2355c76f48c6ab1d94c6b02f970:

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

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*rcf_argv_rtn)(
		int argv,
		char **argc
		)

argv/argc routine prototype

.. index:: pair: typedef; rcf_argv_thr_rtn
.. _doxid-group__rcf__ch_1ga5a5c715d8aa4d72a910124593d1dbd59:

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

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*rcf_argv_thr_rtn)(
		void *sem,
		int argc,
		char **argv
		)

argv/argc threaded routine prototype

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

.. index:: pair: function; rcf_ch_init
.. _doxid-group__rcf__ch_1gab19d7b2f3a4265eb5bfd919d6db509d2:

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

	int rcf_ch_init(void)

Initialize structures.



.. rubric:: Returns:

Status code

.. index:: pair: function; rcf_ch_lock
.. _doxid-group__rcf__ch_1ga54e87ddcaa8b26520bb5782c10a26ecb:

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

	void rcf_ch_lock(void)

Mutual exclusion lock access to data connection.

.. index:: pair: function; rcf_ch_unlock
.. _doxid-group__rcf__ch_1gace92be5ae80ce7a5111c47636d4fe671:

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

	void rcf_ch_unlock(void)

Unlock access to data connection.

To be asynchronous cancellation safe, unlock should work fine in not locked state.

Macros
------

.. index:: pair: define; RCF_CH_LOCK
.. _doxid-group__rcf__ch_1gada9c38da6bbb7d323a467378063f4d15:

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

	#define RCF_CH_LOCK

POSIX thread cancellation-unsafe lock access to data connection.

.. index:: pair: define; RCF_CH_UNLOCK
.. _doxid-group__rcf__ch_1ga79d9f5e9d33598de9736ebce6af42853:

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

	#define RCF_CH_UNLOCK

POSIX thread cancellation-unsafe unlock access to data connection.

.. index:: pair: define; RCF_PCH_CFG_SUBST_SET
.. _doxid-group__rcf__ch_1gaad861f62ce20add7dae94edc91e7f91b:

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

	#define RCF_PCH_CFG_SUBST_SET(...)

A convenience constructor to define substitutions