/**********************************************************************
 * LeechCraft - modular cross-platform feature rich internet client.
 * Copyright (C) 2006-2014  Georg Rudoy
 *
 * Boost Software License - Version 1.0 - August 17th, 2003
 *
 * Permission is hereby granted, free of charge, to any person or organization
 * obtaining a copy of the software and accompanying documentation covered by
 * this license (the "Software") to use, reproduce, display, distribute,
 * execute, and transmit the Software, and to prepare derivative works of the
 * Software, and to permit third-parties to whom the Software is furnished to
 * do so, all subject to the following:
 *
 * The copyright notices in the Software and this entire statement, including
 * the above license grant, this restriction and the following disclaimer,
 * must be included in all copies of the Software, in whole or in part, and
 * all derivative works of the Software, unless such copies or derivative
 * works are solely in the form of machine-executable object code generated by
 * a source language processor.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
 * SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
 * FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 **********************************************************************/

#pragma once

#include "xpcconfig.h"
#include <interfaces/core/icoreproxy.h>

class QString;
class QObject;

namespace LeechCraft
{
namespace Util
{
	template<typename, typename>
	class EitherCont;

	/** @brief Returns password for the key, possibly asking the user.
	 *
	 * This function returns password for the given \em keyName and using
	 * the given \em emitter object. The password is typically stored in
	 * a storage plugin like SecMan.
	 *
	 * If the password isn't found in any password stores (or there are
	 * no password stores) or \em useStore is set to false, this function
	 * asks the user for the password instead using the \em dialogText
	 * for the dialog and returns the user input instead. If user has
	 * canceled the dialog it returns an null string. Otherwise, if the
	 * user has entered some text this function automatically stores the
	 * password under the \em keyName.
	 *
	 * The emitter object is used to send the corresponding internal
	 * Entity objects around, so it should have its gotEntity() and
	 * delegateEntity() signals both relayed to the corresponding plugin
	 * instance object.
	 *
	 * @note Despite the name this function can be used to retrieve
	 * arbitrary string data saved via SavePassword().
	 *
	 * @param[in] keyName The name of the key uniquely identifying the
	 * password.
	 * @param[in] dialogText The text of the dialog to present to the
	 * user if the password isn't found or \em useStore is false.
	 * @param[in] emitter The object used to emit the gotEntity() and
	 * delegateEntity() signals.
	 * @param[in] useStore Whether stored password should be used at
	 * all. Calling code may explicitly set this to <code>false</code> if
	 * the saved password is known to be invalid, for instance.
	 * @return The password or a null string.
	 *
	 * @sa SavePassword()
	 */
	UTIL_XPC_API QString GetPassword (const QString& keyName,
			const QString& dialogText,
			const ICoreProxy_ptr& proxy,
			bool useStore = true);

	UTIL_XPC_API void GetPassword (const QString& keyName,
			const QString& dialogText,
			const ICoreProxy_ptr& proxy,
			const EitherCont<void (), void (QString)>& cont,
			QObject *depender = nullptr,
			bool useStore = true);

	/** @brief Saves the password to be retrieved later via GetPassword().
	 *
	 * This function stores the \em password under the given \em keyName
	 * and using the given \em emitter object. The password is typically
	 * stored in a storage plugin like SecMan.
	 *
	 * If there are no storage plugins, this function does nothing.
	 *
	 * The emitter object is used to send the corresponding internal
	 * Entity objects around, so it should have its gotEntity() and
	 * delegateEntity() signals both relayed to the corresponding plugin
	 * instance object.
	 *
	 * @note Despite the name this function can be used to save arbitrary
	 * string data in secure storages like SecMan.
	 *
	 * @param[in] password The password string to save.
	 * @param[in] keyName The name of the key uniquely identifying the
	 * password.
	 * @param[in] emitter The object used to emit the gotEntity() and
	 * delegateEntity() signals.
	 *
	 * @sa GetPassword()
	 */
	UTIL_XPC_API void SavePassword (const QString& password,
			const QString& keyName,
			const ICoreProxy_ptr& proxy);
}
}
