:orphan:

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

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:`Configuration support<doxid-group__rcf__ch__cfg>`
|		:ref:`Configuration node definition macros<doxid-group__rcf__ch__cfg__node__def>`
|	:ref:`File manipulation<doxid-group__rcf__ch__file>`
|	:ref:`Function calls<doxid-group__rcf__ch__func>`
|	:ref:`Processes and threads<doxid-group__rcf__ch__proc>`
|	:ref:`Reboot and shutdown<doxid-group__rcf__ch__reboot>`
|	:ref:`Symbol and address resolution<doxid-group__rcf__ch__addr>`
|	:ref:`Traffic Application Domain support<doxid-group__rcf__ch__tad>`
|	:ref:`Variables<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.

.. attention::

	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