<?php
/**
 * This file is part of the set of the DDR Simple API definition. It contains the
 * definition of the {@link Evidence} interface.
 * 
 * @author Sylvain Lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package AskPythia
 * @subpackage Interface
 * @version $Revision: 1.10 $
 * @license http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html W3C Software Notice and License
 * @copyright Copyright (c) 2009, W3C (MIT, ERCIM, Keio)
 */

/**
 * {@link http://www.w3.org/TR/DDR-Simple-API/#sec-Evidence Evidence} interface
 * as defined in the {@link http://www.w3.org/TR/DDR-Simple-API/ DDR Simple API}
 * standard.
 * 
 * When querying Property values, Evidence is the general term applied to providing 
 * informations to the Device Description Repository (DDR) to allow it to determine
 * the Delivery Context.
 * 
 * The DDR Simple API standard only mandates support for Evidence consisting of HTTP
 * Header name and value pairs. Other types of Evidence may be supported by
 * implementations.
 * 
 * @author Sylvain Lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package AskPythia
 * @subpackage Interface
 * @link http://www.w3.org/TR/DDR-Simple-API/ Device Description Repository Simple API
 * @version $Revision: 1.10 $
 * @license http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html W3C Software Notice and License
 * @copyright Copyright (c) 2009, W3C (MIT, ERCIM, Keio)
 */
interface Evidence {
	/**
	 * Adds a name/value pair to the Evidence.
	 * 
	 * In the DDR Simple API, an evidence consists of HTTP header name and value
	 * pairs. HTTP header name must be treated in a case insensitive manner
	 * (values may be treated in case sensitive manner, depending on the HTTP
	 * header).
	 * 
	 * @param string $key the key (name) to be added to the Evidence.
	 * @param string $value the value associated with the key.
	 */
	public function put($key, $value);
	
	/**
	 * Retrieves the value associated with the given key in the Evidence.
	 * 
	 * In the DDR Simple API, an evidence consists of HTTP header name and value
	 * pairs. HTTP header name must be treated in a case insensitive manner
	 * (values may be treated in case sensitive manner, depending on the HTTP
	 * header).
	 * 
	 * @param string $key the key (name) to retrieve. Search among HTTP headers
	 *               must be case-insensitive.
	 * @return string the value associated with the key.
	 */
	public function get($key);
	
	/**
	 * Tests if the given key is defined in the Evidence.
	 * 
	 * @param string $key the key (name) to check. Search among HTTP headers
	 *                    must be case-insensitive.
	 * @return bool true when the key exists, false otherwise.
	 */
	public function exists($key);
}

?>