/*
* This file is part of the KDE libraries
* Copyright (C) 2000-2001 Dawit Alemayehu <adawit@kde.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library 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
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#ifndef __KIO_AUTHINFO_H
#define __KIO_AUTHINFO_H
#include <qdatastream.h>
#include <qstring.h>
#include <kurl.h>
namespace KIO
{
/*
* This class is intended to make it easier to prompt for, cache
* and retrieve authorization information.
*
* When using this class to cache, retrieve or prompt authentication
* information, you only need to set the necessary attributes. For
* example, to check whether a password is already cached, the only
* required information is the URL of the resource and optionally
* whether or not a path match should be performed. Similarly, to
* prompt for password you only need to optionally set the prompt,
* username (if already supplied), comment and commentLabel fields.
*
* <u>SPECIAL NOTE:</u> If you extend this class to add additional
* paramters do not forget to overload the stream insertion and
* extraction operators ("<<" and ">>") so that the added data can
* be correctly serialzed.
*
* @short A two way messaging class for passing authentication information.
* @author Dawit Alemayehu <adawit@kde.org>
*/
class AuthInfo
{
friend QDataStream& operator<< (QDataStream& s, const AuthInfo& a);
friend QDataStream& operator>> (QDataStream& s, AuthInfo& a);
public:
/**
* Default constructor.
*/
AuthInfo();
/**
* Copy constructor.
*/
AuthInfo( const AuthInfo& info );
/**
* Overloaded equal to operator.
*/
AuthInfo& operator=( const AuthInfo& info );
/**
* Use this method to check if the object was modified.
*/
bool isModified() const { return modified; }
/**
* Use this method to indicate that this object has been modified.
*/
void setModified( bool flag ) { modified = flag; }
/**
* The URL for which authentication is to be stored.
*
* This field is required when attempting to cache authorization
* and retrieve it. However, it is not needed when prompting
* the user for authorization info.
*
* This setting is @p required except when prompting the
* user for password.
*/
KURL url;
/**
* This setting is @p required for caching.
*/
QString username;
/**
* This setting is @p required for caching.
*/
QString password;
/**
* Information to be displayed when prompting
* the user for authentication information.
*
* <u>NOTE:</u>If this field is not set, the authentication
* dialog simply displays the preset default prompt.
*
* This setting is @p optional and empty by default.
*/
QString prompt;
/**
* The text to displayed in the title bar of
* the password prompting dialog.
*
* <u>NOTE:</u>If this field is not set, the authentication
* dialog simply displays the preset default caption.
*
* This setting is @p optional and empty by default.
*/
QString caption;
/**
* Additional comment to be displayed when prompting
* the user for authentication information.
*
* This field allows you to display a short (no more than
* 80 characters) extra description in the password prompt
* dialog. For example, this field along with the
* @ref commentLabel can be used to describe the server that
* requested the authentication:
*
* <pre>
* Server: Squid Proxy @ foo.com
* </pre>
*
* where "Server:" is the commetLabel and the rest is the
* actual comment. Note that it is always better to use
* the @p commentLabel field as it will be placed properly
* in the dialog rather than to include it within the actual
* comment.
*
* This setting is @p optional and empty by default.
*/
QString comment;
/**
* Descriptive label to be displayed infront of the
* comment when prompting the user for password.
*
* This setting is @p optional and only applicable when
* the @ref comment field is also set.
*/
QString commentLabel;
/**
* A unique identifier that allows caching of multiple
* passwords for different resources in the same server.
*
* Mostly this setting is applicable to the HTTP protocol
* whose authentication scheme explicitly defines the use
* of such a unique key. However, any protocol that can
* generate or supply a unique id can effectively use it
* to distinguish passwords.
*
* If you are instead interested in caching the authentication
* info for multiple users to the same server, refer to @ref
* multipleUserCaching below.
*
* This setting is @p optional and not set by default.
*/
QString realmValue;
/**
* Field to store any extra authentication information for
* protocols that need it (ex: http).
*
* This setting is @p optional and mostly applicable for HTTP
* protocol. However, any protocol can make use of it to
* store extra info.
*/
QString digestInfo;
/**
* Flag that, if set, indicates whether a path match should be
* performed when requesting for cached authorization.
*
* A path is deemed to be a match if it is equal to or is a subset
* of the cached path. For example, if stored path is "/foo/bar"
* and the request's path set to "/foo/bar/acme", then it is a match
* whereas it would not if the request's path was set to "/foo".
*
* This setting is @p optional and false by default.
*/
bool verifyPath;
/**
* Flag which if set forces the username field to be read-only.
*
* This setting is @p optional and false by default.
*/
bool readOnly;
/**
* Flag to indicate the persistence of the given password.
*
* This is a two-way flag when set before calling openPassDlg
* makes the "keep Password" check box will visible to the user.
* In return the flag will indicate the state of the check box.
* By default if the flag is checked the password will be cached
* for the entire life of the current KDE session otherwise the
* cached password is deleted right after the application using
* it has been closed.
*/
bool keepPassword;
protected:
bool modified;
};
};
#endif
| Generated by: ssk@tauon.ph.unimelb.EDU.AU on Wed May 23 05:06:16 2001, using kdoc 2.0a35. |
