/**
 * Copyright (c) 2014 Etherios, a Division of Digi International Inc.
 * All rights not expressly granted are reserved.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * Etherios 11001 Bren Road East, Minnetonka, MN 55343
 * =======================================================================
 */
package com.etherios.connector.emulator.rci;

/**
 * This interface lists all the required methods that should be implemented in 
 * order to extend the RCI functionality using Cloud Connector.
 * 
 * <p>In order to extend Cloud Connector RCI functionality, a class implementing 
 * this interface must be passed as parameter in the Cloud Connector constructor: 
 * {@link com.etherios.connector.emulator.CloudConnector#CloudConnector(IGeneralRCIExtension)}</p>
 * 
 * <p>The parameter {@value com.etherios.connector.emulator.rci.GeneralRCIManager#PARAM_EXTEND_RCI} value must be 
 * {@code True} in the {@code connector_config.txt} file.</p>
 * 
 * <p>The location of the custom descriptor in the application is determined by 
 * the settings {@value com.etherios.connector.emulator.rci.GeneralRCIManager#PARAM_DESCRIPTOR_TYPE} and 
 * {@value com.etherios.connector.emulator.rci.GeneralRCIManager#PARAM_DESCRIPTOR_LOC}:</p>
 * 
 * <ul>
 * <li>{@value com.etherios.connector.emulator.rci.GeneralRCIManager#DESCRIPTOR_TYPE_EMBEDDED} Cloud Connector will 
 * look for the descriptor file, defined in 
 * {@value com.etherios.connector.emulator.rci.GeneralRCIManager#PARAM_DESCRIPTOR_TYPE}, inside the jar.</li>
 * <li>{@value com.etherios.connector.emulator.rci.GeneralRCIManager#DESCRIPTOR_TYPE_EXTERNAL} Cloud Connector will 
 * look for the file defined {@value com.etherios.connector.emulator.rci.GeneralRCIManager#PARAM_DESCRIPTOR_TYPE}in 
 * the file system of the device.</li>
 * </ul>
 * 
 * @see GeneralRCIManager#PARAM_EXTEND_RCI
 * @see GeneralRCIManager#PARAM_DESCRIPTOR_TYPE
 * @see GeneralRCIManager#PARAM_DESCRIPTOR_LOC
 * @see com.etherios.connector.emulator.CloudConnector
 */
public interface IGeneralRCIExtension {

	/**
	 * Retrieves the value of the given setting name included in the
	 * given setting group.
	 * 
	 * @param group Name of the group where the setting is included.
	 * @param setting Name of the setting to retrieve its value.
	 * @param index In case of multiple instances of the settings group, the 
	 *              group index for arrays.
	 * @param name In case of multiple instances of the settings group, the 
	 *             group name for dictionaries.
	 * @return The setting value.
	 */
	public String getSettingValue(String group, String setting, int index, String name);
	
	/**
	 * Sets the value of the given setting name included in the
	 * given setting group.
	 * 
	 * @param group Name of the group where the setting is included.
	 * @param setting Name of the setting to set its value.
	 * @param value The new setting value.
	 * @param index In case of multiple instances of the settings group, the 
	 *              group index for arrays.
	 * @param name In case of multiple instances of the settings group, the 
	 *             group name for dictionaries.
	 * @return Set setting answer. Empty answer means no error.
	 */
	public String setSettingValue(String group, String setting, String value, int index, String name);
	
	/**
	 * Handles a ZigBee target request with the given data.
	 * 
	 * @param data ZigBee request data in XML format.
	 * @return The request answer after processing.
	 */
	public String handleZigbeeRequest(String data);
}
