...G...... [ZBXNEXT-1550] added code comments and README file for the dummy module

2 files changed, 103 insertions, 1 deletions

diff --git a/src/modules/agent/dummy/README b/src/modules/agent/dummy/README
new file mode 100644
index 00000000000..d56d8d9eadf
--- /dev/null
+++ b/src/modules/agent/dummy/README
@@ -0,0 +1,3 @@
+This directory contains a sample module, which extends functionality of Zabbix Agent. The dummy.c module is well commented, have a look at the sourcesto learn how to create Zabbix modules.
+
+Run 'make' to build it. It should produce dummy.so.
diff --git a/src/modules/agent/dummy/dummy.c b/src/modules/agent/dummy/dummy.c
index ea5e149bb59..4c584c7568f 100644
--- a/src/modules/agent/dummy/dummy.c
+++ b/src/modules/agent/dummy/dummy.c
@@ -1,13 +1,57 @@
+/*
+** Zabbix
+** Copyright (C) 2000-2013 Zabbix SIA
+**
+** 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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+**/
+
 #include "modules.h"
 #include "sysinfo.h"
 
+/******************************************************************************
+ *                                                                            *
+ * Function: zbx_module_version                                               *
+ *                                                                            *
+ * Purpose: returns version number of the module                              *
+ *                                                                            *
+ * Parameters:                                                                *
+ *                                                                            *
+ * Return value: 1 - current version supported by the agent                   *
+ *                                                                            *
+ ******************************************************************************/
 int zbx_module_version()
 {
 	return 1;
 }
 
+/******************************************************************************
+ *                                                                            *
+ * Function: zbx_module_list                                                  *
+ *                                                                            *
+ * Purpose: returns list of item keys supported by the module                 *
+ *                                                                            *
+ * Parameters:                                                                *
+ *                                                                            *
+ * Return value: list of item keys                                            *
+ *                                                                            *
+ * Comment: item keys that accept optional parameters must have [*] included  *
+ *                                                                            *
+ ******************************************************************************/
 char **zbx_module_list()
 {
+	/* keys having [*] accept optional parameters */
 	static char *keys[]={"dummy.ping", "dummy.echo[*]", "dummy.random[*]"};
 	return keys;
 }
@@ -50,18 +94,45 @@ static int dummy_random(AGENT_REQUEST *request, AGENT_RESULT *result)
 }
 
 
+/******************************************************************************
+ *                                                                            *
+ * Function: zbx_module_process                                               *
+ *                                                                            *
+ * Purpose: a main entry point for processing of items                        *
+ *                                                                            *
+ * Parameters: request - structure that contains item key and parameters      *
+ *              request->key - item key without parameters                    *
+ *              request->nparam - number of parameters                        *
+ *              request->timeout - processing should not take longer than     *
+ *                                 this number of seconds                     *
+ *              request->params[N-1] - pointers to item key parameters        *
+ *                                                                            *
+ *             result - structure that will contain result                    *
+ *                                                                            *
+ * Return value: SYSINFO_RET_FAIL - function failed, item will be marked      *
+ *                                  as not supported by zabbix                *
+ *               SYSINFO_RET_OK - success                                     *
+ *                                                                            *
+ * Comment: get_param(request, N-1) can be used to get a pointer to the Nth   *
+ *          parameter starting from 0 (first parameter). Make sure it exists  *
+ *          by checking value of request->nparam.                             *
+ *                                                                            *
+ ******************************************************************************/
 int	zbx_module_process(AGENT_REQUEST *request, AGENT_RESULT *result)
 {
 	int ret = SYSINFO_RET_FAIL;
 
+	/* it always returns 1 */
 	if(0 == strcmp(request->key,"dummy.ping"))
 	{
 		ret = dummy_ping(request, result);
 	}
+	/* dummy.echo[param1] accepts one parameter and returns it as a result. For example: dummy.echo[abc] -> abc */
 	else if(0 == strcmp(request->key,"dummy.echo"))
 	{
 		ret = dummy_echo(request, result);
 	}
+	/* dummy.random[from,to] returns integer random number between 'from' and 'to' */
 	else if(0 == strcmp(request->key,"dummy.random"))
 	{
 		ret = dummy_random(request, result);
@@ -70,14 +141,42 @@ int	zbx_module_process(AGENT_REQUEST *request, AGENT_RESULT *result)
 	return ret;
 }
 
-/* It should return ZBX_MODULE_FAIL in case of initialization failure */
+/******************************************************************************
+ *                                                                            *
+ * Function: zbx_module_init                                                  *
+ *                                                                            *
+ * Purpose: the function is called on agent startup                           *
+ *          It should be used to call any initialization routines             *
+ *                                                                            *
+ * Parameters:                                                                *
+ *                                                                            *
+ * Return value: ZBX_MODULE_OK - success                                      *
+ *               ZBX_MODULE_FAIL - module initialization failed               *
+ *                                                                            *
+ * Comment: agent will not load the module in case of ZBX_MODULE_FAIL         *
+ *                                                                            *
+ ******************************************************************************/
 int zbx_module_init()
 {
+	/* Initialization for dummy.random */
 	srand(time(NULL));
 
 	return ZBX_MODULE_OK;
 }
 
+/******************************************************************************
+ *                                                                            *
+ * Function: zbx_module_uninit                                                *
+ *                                                                            *
+ * Purpose: the function is called on agent shutdown                          *
+ *          It should be used to cleanup used resources if there are any      *
+ *                                                                            *
+ * Parameters:                                                                *
+ *                                                                            *
+ * Return value: ZBX_MODULE_OK - success                                      *
+ *               ZBX_MODULE_FAIL - function failed                            *
+ *                                                                            *
+ ******************************************************************************/
 int zbx_module_uninit()
 {
 	return ZBX_MODULE_OK;