# Source: kpassdlg.h |
Annotated List
Files
Globals
Hierarchy
Index

    // vi: ts=8 sts=4 sw=4
    /* This file is part of the KDE libraries
       Copyright (C) 1998 Pietro Iglio <iglio@fub.it>
       Copyright (C) 1999,2000 Geert Jansen <jansen@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 version 2 as published by the Free Software Foundation.

       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 __KPassDlg_h_included__
    #define __KPassDlg_h_included__

    #include <qstring.h>
    #include <qlineedit.h>
    #include <qevent.h>

    #include <kdialogbase.h>

    class QLabel;
    class QGridLayout;
    class QWidget;

    /**
     * @short A safe password input widget.
     * @author Geert Jansen <geertj@kde.org>
     *
     * The widget uses the user's global "echo mode" setting.
     */

    class KPasswordEdit
        : public QLineEdit
    {
        Q_OBJECT

    public:
        /**
         * Create a widget using the user's global "echo mode" setting.
         */
        KPasswordEdit(QWidget *parent=0, const char *name=0);

        /**
         * Create a widget using echoMode as "echo mode".
         */
        KPasswordEdit(QWidget *parent, const char *name, int echoMode);

        ~KPasswordEdit();

        /**
         * Returns the password. The memory is freed in the destructor
         * so you should make a copy.
         */
        const char *password() { return m_Password; }

        /** Erase the current password. */
        void erase();

        static const int PassLen = 100;
        enum EchoModes { OneStar, ThreeStars, NoEcho };

    protected:
        virtual void keyPressEvent(QKeyEvent *);

    private:
        void showPass();

        char *m_Password;
        int m_EchoMode, m_Length;
    };

    /**
     * This dialog asks the user to enter a password. The functions you're
     * probably interested in are the static methods, @ref #getPassword() and
     * @ref #getNewPassword().
     *
     * @sect Usage example
     *
     * <pre>
     * QCString password;
     * int result = KPasswordDialog::getPassword(password, i18n("Password"));
     * if (result == KPasswordDialog::Accepted)
     *     use(password);
     * </pre>
     *
     * @sect Security notes
     *
     * Keeping passwords in memory can be a potential security hole. You should
     * handle this situation with care.
     *
     * @li You may want to use @ref #disableCoreDump() to disable core dumps.
     * Core dumps are dangerous because they are an image of the process memory,
     * and thus include any passwords that were in memory.
     *
     * @li You should delete passwords as soon as they are not needed anymore.
     * The functions @ref #getPassword() and @ref #getNewPassword() return the
     * password as a QCString. I believe this is safer than a QString. A QString
     * stores its characters internally as 16-bit wide values, so conversions are
     * needed, both for creating the QString and by using it. The temporary
     * memory used for these conversion is probably not erased. This could lead
     * to stray  passwords in memory, even if you think you erased all of them.
     *
     * @short A password input dialog.
     * @author Geert Jansen <jansen@kde.org>
     */

    class KPasswordDialog
        : public KDialogBase
    {
        Q_OBJECT

    public:
        KPasswordDialog(int type, QString prompt, bool enableKeep=false,
    	    int extraBttn=0);
        virtual ~KPasswordDialog();

        /** Set the password prompt. */
        void setPrompt(QString prompt);

        /** Add a line of information to the dialog. */
        void addLine(QString key, QString value);

        /**
         * Returns the password entered. The memory is freed in the destructor,
         * so you should make a copy.
         */
        const char *password() const { return m_pEdit->password(); }

        /** Returns true if the user wants to keep the password. */
        bool keep() const { return m_Keep; }

        /**
         * Pops up the dialog, asks the user for a password, and returns it.
         *
         * @param password The password is returned in this reference parameter.
         * @param prompt A prompt for the password. This can be a few lines of
         * information. The text is word broken to fit nicely in the dialog.
         * @param keep Enable/disable a checkbox controlling password keeping.
         * If you pass a null pointer, or a pointer to the value 0, the checkbox
         * is not shown. If you pass a pointer to a nonzero value, the checkbox
         * is shown and the result is stored in *keep.
         * @return Result code: Accepted or Rejected.
         */
        static int getPassword(QCString &password, QString prompt, int *keep=0L);

        /**
         * Pops up the dialog, asks the user for a password and returns it. The
         * user has to enter the password twice to make sure it was entered
         * correctly.
         *
         * @param password The password is returned in this reference parameter.
         * @param prompt A prompt for the password. This can be a few lines of
         * information. The text is word broken to fit nicely in the dialog.
         * @return Result code: Accepted or Rejected.
         */
        static int getNewPassword(QCString &password, QString prompt);

        /** Static helper funtion that disables core dumps. */
        static void disableCoreDumps();

        enum Types { Password, NewPassword };

    protected slots:
        void slotOk();
        void slotCancel();
        void slotKeep(bool);

    protected:

        /** Virtual function that can be overridden to provide password
         * checking in derived classes. It should return @p true if the
         * password is valid, @p false otherwise. */
        virtual bool checkPassword(const char *) { return true; }

    private:
        void erase();

        int m_Keep, m_Type, m_Row;
        QLabel *m_pHelpLbl;
        QGridLayout *m_pGrid;
        QWidget *m_pMain;
        KPasswordEdit *m_pEdit, *m_pEdit2;

        class KPasswordDialogPrivate;
        KPasswordDialogPrivate *d;
    };

    #endif // __KPassDlg_h_included__

Generated by: root@sparc.ports.openbsd.org on Wed May 2 09:37:45 2001, using kdoc 2.0a53.