ConnectPromptInfo.h

/**************************************************************************
*       Copyright (c) 2006, Cisco Systems, All Rights Reserved
***************************************************************************
*
*  File:    ConnectPromptInfo.h
*  Date:    08/2006
*
***************************************************************************
*
*   Connect Prompt Info class implementation for the Client API.
*
***************************************************************************/
#ifndef _CONNECTPROMPTINFO_
#define _CONNECTPROMPTINFO_
 
#include "ConnectPromptInfoBase.h"
 
class PromptEntry;
 
/**
 * This class transports credential data between the client interface
 * and the API.  The API creates PromptEntry instances for each required
 * option or credential.  These PromptEntry instances can range from an
 * instance with group options to one containing a password prompt.
 *
 * The API automatically references the instance of this class and any
 * values that have been set.  When the selections or values are set,
 * simply call the API method ClientIfc::UserSubmit to alert
 * the API that it can process the responses and proceed with VPN
 * establishment.
 *
 * The storage and management of this class are the responsibility of the API.
 * No management is required on the part of a client program.
 */
 
 
class VPN_VPNAPI ConnectPromptInfo : public ConnectPromptInfoBase
{
 
    public:
 
 
        /**
         * Specifies what type of data is being requested/presented to the user:
         * Certificate - can be a single or list of certificates.
         * Proxy - indicates being prompted for proxy credentials.
         * Credentials - indicates being prompted for user credentials
         * (for example, username, password).
         */
        ConnectPromptType getConnectPromptType() const;
 
        /**
         * This method returns whether or not this connect prompt has been
         * marked as canceled by the user.
         */
        bool isCanceled() const;
 
        /**
         * Marks the canceled state of this connect prompt.
         */
        void setCanceled(bool bIsCanceled);
 
        /**
         * This method returns whether or not this connect prompt has error occurred
         */
        UserResponseError getResponseError() const;
    
        /**
         * Marks the error state of this connect prompt.
         */
        void setResponseError(UserResponseError err);
    
        /**
         * This method returns the count of any available PromptEntry objects.
         * Each PromptEntry object, typically, represents a credential whose
         * value the client must set before calling the UserSubmit method.
         */
        unsigned int countPromptEntry() const;
 
 
        /**
         * Return the string if any, related to the credentials for which
         * the user is being prompted.
         */
        const tstring &getMessage() const;
 
 
        /**
         * Retrieve a list of any available prompt names.
         */
        const std::list<tstring> &getListPromptNames(
                                   std::list<tstring> &listPromptNames) const;
 
 
        /**
         * Retrieve a PromptEntry instance by name.  The list of names can
         * be obtained using getListPromptNames method. 
         * 
         * See the ::PromptType enum found in api.h for valid PromptEntry
         * types (except for Prompt_Checkbox which is used by the Preference
         * class).
         */
        PromptEntry *getPromptEntry(const tstring &promptName) const;
 
 
        /**
         * Retrieve the entire list of PromptEntry objects.
         */
        const std::list<PromptEntry *> &getListPromptEntry() const;
 
        /**
         * If an error during authentication is detected,
         * this method returns true.
         */
        bool hasAuthenticationError() const;
 
        /**
         * If an error during authentication is detected,
         * this method returns the auth error code.
         */
        int getAuthenticationError() const;
 
        /**
         * Get the name to be used for the button used to submit user responses
         * (For example, Connect, Submit)
         */
        const tstring &getSubmitButtonName() const;
 
 
        /**
         * Indicates that an enrollment Certificate Authority (CA) is
         * available.
         */
        bool hasEnrollmentCA() const;
 
 
        /**
         * Set to true to indicate that we want to retrieve a
         * certificate from the CA.
         */
        void setUseEnrollmentCA(bool bUseEnrollmentCA);
 
        /**
         * Set the actively selected group.
         * This method will update the value and enabled properties of the
         * contained credential PromptEntry objects.
         */
        bool setTunnelGroup(const tstring &group);
 
        /**
         * Indicates if this object is "Empty".  This means:
         * -The object has no entries and no enrollmentCA (and a detail message)
         * -Has only disabled/invisible entries
         * -Has only entries of Type Prompt_Banner or Prompt_Hidden or Prompt_Header or Prompt_CheckBox
         * returns true if the object is "Empty" false otherwise
         */
        bool isEmpty() const;
 
        ConnectPromptInfo(tstring defaultSubmitButtonName);
        virtual ~ConnectPromptInfo();
 
};
 
 
#endif // _CONNECTPROMPTINFO_