include/ClientIfc.h

/**************************************************************************
*       Copyright (c) 2006, Cisco Systems, All Rights Reserved
***************************************************************************
*
*  File:    ClientIfc.h
*  Date:    11/2006
*
***************************************************************************
*
*   Client Interface class implementation for the Client API.
*
***************************************************************************/

#ifndef _CLIENTIFC_
#define _CLIENTIFC_


/**
* This is the main interface class for applications that implement the
* Cisco AnyConnect Secure Mobility VPN API.  A program wishing to use the API must create a
* class that extends the ClientIfc class.  This new class is required to
* provide implementations for the pure virtual methods found in the protected
* section (for example, StatsCB).
*
* Finally, the public section contains methods that are available for
* managing the API.  These include methods like attach and connect.
*
* A client must implement the CB (abstract) methods found in the protected
* section of this interface.
*
*/



#include "api.h"
#include "ClientIfcBase.h"
#include "VPNStats.h"
#include "ConnectPromptInfo.h"
#include "Preference.h"
#include "PreferenceInfo.h"

class VPN_VPNAPI ClientIfc : protected ClientIfcBase
{
    protected:

        /**
         * Callback used to deliver new statistics related to the VPN
         * connection.
         *
         * When a connection is active, a new set of statistics is
         * delivered each second.
         *
         * @see resetStats(), stopStats() and startStats()
         *
         */
        virtual void StatsCB(VPNStats &stats) = 0;


        /**
         * Callback used to deliver VPN state and state change string.
         * The stateString delivered by this method is localized.
         *
         * See the ::VPNState enum found in api.h for set of valid states.
         */
        virtual void StateCB(const VPNState state,
                             const tstring stateString) = 0;


        /**
         * If a banner needs to be acknowledged, this CB delivers the banner
         * to the client. 
         *
         * NOTE: Connection establishment will block until the method
         * setBannerResponse() is called.
         *
         * In a GUI, a banner would typically be displayed in a modal dialog
         * with an accept or decline button selection.
         *
         * @see setBannerResponse() to set the user response to the banner.
         */
        virtual void BannerCB(const tstring &banner) = 0;


        /**
         * Messages are delivered via the NoticeCB and can come from multiple
         * sources.  There are four message types (error, warning, info and
         * status).  See the ::MessageType enum in api.h for the list.
         *
         * Clients using the API as an embedded application (not
         * user visible) might want to further characterize
         * messages.  One option here is to use the AnyConnect message
         * catalog and assign message codes as the translations for
         * various messages.  An application could then track messages based
         * on its own error code scheme.
         */
        virtual void NoticeCB(const tstring notice,
                              const MessageType type) = 0;


        /**
         * This CB would likely occur only during a connection when it was
         * detected that the software needed to be upgraded, or when Start
         * Before Logon (SBL) is being used.
         *
         * Unlike the other callback methods, this method provides a default
         * implementation (calling the system's exit() function).
         * If clients of the API wish to override this behavior, they are
         * responsible for ensuring that the current running process exits with
         * the return code specified by returnCode.
         *
         * <b>Caution</b>: IF YOU OVERRIDE THIS METHOD AND DO NOT EXIT WITH
         * THE PROPER CODE SOFTWARE UPDATE FUNCTIONALITY IN YOUR CLIENT WILL
         * BREAK
         */
        virtual void ExitNoticeCB(const tstring &tstrNotice,
                                  const int returnCode);


        /**
         * Under normal operating conditions, this CB is called as soon
         * as the attach method completes.  In case the service (vpn agent)
         * is not ready, this CB is not called until it is.
         *
         * Any API calls made prior to this CB being called will result in a
         * NoticeCB error message.
         */
        virtual void ServiceReadyCB() = 0;



        /**
         * This method supports prompting for single or multiple values.  All
         * prompts are considered mandatory.
         *
         * The ConnectPromptInfo object contains a list of PromptEntry
         * instances.  The labels and their default values (if any) can be
         * found in these instances.  After the data has been collected from the user
         * it can be set into these same instances.  When ready, the client
         * application should call the method UserSubmit() to have the
         * responses read by the API.
         */
        virtual void UserPromptCB(ConnectPromptInfo &ConnectPrompt) = 0;


        /**
         * Use this method to provide Window Manager hints to GUI
         * applications.  To receive these hints, the application must
         * identify itself as a GUI in the attach method.  In addition, this
         * method should be overriden to receive any generated events.
         *
         * Event that can be received include those indicating that a user is
         * starting a second instance of the GUI application.  This information
         * can be used to tell the already running application to un-minimize
         * itself and let the new program know that it should Quit (since a GUI
         * is already running).
         */
        virtual void WMHintCB(const WMHint hint,
                              const WMHintReason reason);


        /**
         * This method is useful when the connection to the secure gateway
         * has been established as part of a web-launch of the VPN tunnel.
         *
         * If the client application wishes to be notified of the secure
         * gateway to which the VPN has been established, this method should
         * be overriden.
         *
         * If the client application is started and a tunnel is already active,
         * this method also delivers the name of the secure gateway host.
         */
        virtual void deliverWebLaunchHostCB(const tstring &activeHost);

        /**
         * This method is called when the result of a vpnapi_request_importpkcs12(..) 
         * call is known. If bResult is false then pszError will be an error string.
         */
        virtual void ImportPKCS12ResultCB(bool bResult, const tstring &strError);

        /**
         * This method is called when the preference to block untrusted
         * servers is enabled and the current VPN server being connected
         * to is untrusted. Clients should present an error to the user
         * notifying them that the current connection to rtstrUntrustedServer
         * is being blocked. The client should also provide a way for the
         * user to change the preference to block untrusted servers.
         *
         * The user response must be indicated using setCertBlockedReponse
        */
        virtual void CertBlockedCB(const tstring &rtstrUntrustedServer) = 0;

        /**
         * This method is called when connections to untrusted VPN servers
         * is allowed by policies and the current VPN server being connected
         * to is untrusted. Clients should present a warning to the user
         * notifying them that the current connection to rtstrUntrustedServer
         * is unsafe. The reason the VPN server is untrusted is provided in
         * rltstrCertErrors. The client should provide a way for the user to
         * connect once, connect and always trust or cancel the connection.
         *
         * The user response must be indicated using setCertWarningReponse
        */
        virtual void CertWarningCB(const tstring &rtstrUntrustedServer,
                                   const std::list<tstring> &rltstrCertErrors) = 0;

        /**
         * This method can be overriden if the client application wishes to
         * exercise some control over the delivery of events from the other
         * protected methods in this class.
         *
         * This might be necessary in cases where a GUI is being written and
         * the data from this API needs to be delivered in the GUI or main
         * thread.  In this case, you should override this method and when it
         * is called by the API post an event to your event queue (message
         * pump, etc.).  After this event executes in your GUI or main thread,
         * call the method ClientIfc::ProcessEvents to have events delivered
         * to your client application.
         */
        virtual void EventAvailable();


        ClientIfc();


    public:

        /**
         * After the ClientIfc class has been created, the client implementation
         * must invoke this method prior to attempting connections,
         * retrieving statistics, etc.  If successful, this method returns
         * true.  If not successful, it returns false and returns a notice error
         * message to the user.
         *
         * A single call to this method is all that is necessary.  If the
         * attach fails, a message indicating the VPN service is not available
         * is returned.  If the call succeeds, the ServiceReadyCB is
         * called and true is returned.
         *
         * \param SBL Start Before Logon
         * is a mode of operation where a GUI
         * can be launched prior to the normal windows logon sequence.  This
         * allows a VPN tunnel to be activated and used as part of the windows
         * logon sequence.  The SBL attribute should be set to true only when
         * it has been passed as an argument to the program by the VPN agent.
         *
         * \param isGUI indicates that the started program is a UI
         * application.  With this attribute set to true, the application will
         * now receive WMHints.
         *
         * \param requestFullCapabilities indicates that the client program is
         * requesting full API capabilities.  Full capabilities allows the
         * client program to connect, disconnect, receive statistics, etc.
         * When full capabilities are not requested or not available, the
         * client program will not be able to establish new VPN connections.
         * Only a client program with full capabilites can do this.  In
         * addition, only the first program requesting full capabilities will
         * be granted this level of access.  The attach method can succeed
         * even if full capabilities is requested but not granted.  To test
         * for this state, use the method ::hasFullCapabilities.
         *
         * \param suppressAutoConnect indicates that the client wishes to
         * override automatically initiating a connection to the last connected
         * secure gateway at startup.  Normally, this is determined by the 
         * value of the AutoConnectOnStart preference.  If this flag is true
         * then an automatic connection will never be initiated, even if 
         * AutoConnectOnStart is enabled.
         */
        bool attach(bool SBL = false, 
                    bool isGUI = true,
                    bool requestFullCapabilities = true,
                    bool suppressAutoConnect = true);


        /**
         * After the client program is done, call the detach method to do a
         * graceful cleanup.  This method stops the flow
         * of events and does general cleanup.
         */
        void detach();


        /**
         * When the method ClientIfc::EventAvailable has been overriden in the
         * client application, this method must be called to receive events.
         *
         * It is expected that GUI programs will use EventAvailable as a
         * signal, allowing them to set an event using their native event
         * handler.  When that event fires, the application can call
         * ProcessEvents, which causes the API to deliver events in the
         * client's main thread.
         */
        virtual void ProcessEvents();


        /**
         * Use this method to determine whether this application has full
         * capabilities.  Only one application (the first one started) can have
         * full capabilities.  If this is the first application started, this
         * method returns true.  When an application does not have full
         * capabilities, it cannot initiate connections.
         */
        bool hasFullCapabilities();
 

        /**
         * This method returns true if the client has an active VPN
         * connection with a secure gateway.
         */
        bool isConnected();


        /**
         * This method returns true if the client VPN is available for use.
         * If false is returned this means that VPN has been intentionally
         * disabled.  This would indicate a situation where other AnyConnect
         * services were in use but not VPN.
         */
        bool isAvailable();


        /**
         * This method returns true if the VPN service is available for
         * establishing VPN connections.
         */
        bool isVPNServiceAvailable();


        /**
         * This method returns true if the mode in which the client is
         * currently operating is enabled. For a list of all possible modes
         * of operation see the ::OperatingMode enum in api.h.
         */
        bool isOperatingMode(OperatingMode opMode);

        /**
         * This method returns a list of secure gateway host names found in an
         * AnyConnect profile.  If no profile is available, an empty
         * list is returned.
         */
        std::list<tstring> getHostNames();


        /**
         * This method returns any default Host name from User Preferences.
         *
         * A host can be returned here even if there are no profiles on the
         * system.  The host last connected to (via the connect method) is
         * returned by this method.
         *
         * If there is no previously connected-to host, the first host found
         * in an AnyConnect profile (if any) is returned.
         */
        tstring getDefaultHostName();


        /**
         * This method initiates a connection to the specified host.
         * The connection results in the presentation of authentication
         * credentials, as appropriate.  Any credentials returned by the secure
         * gateway are delivered via the #UserPromptCB method.
         *
         * See ConnectPromptInfo for more details on possible authentication
         * credentials.
         *
         * If the connection request is accepted, true is returned.  This does
         * not mean the connection succeeded.  If the connection succeeds, a
         * state of connect will be received via the #StateCB method.
         */
        bool connect(tstring host);

        /**
         * Use this method to change selected group after initial connection
         * request has been made and credentials were delivered. 
         *
         * Depending on secure gateway configuratiion, call to this method may
         * result in a new connection request and will update credentials 
         * required for the selected group. New credentials returned by the 
         * secure gateway are delivered via the #UserPromptCB method.
         */
        virtual bool setNewTunnelGroup(const tstring & group);

        /**
         * Use this method to initiate a disconnect of the active VPN
         * connection.
         *
         * An indication of VPN disconnect is received via the #StateCB
         * method.
         */
        void disconnect();


        /**
         * This method triggers the retrieval of the current VPN state.
         * After the client is conected to the VPN service via the #attach
         * method, both the current state and any changes in state are
         * automatically delivered to the client.  In general, this method
         * should not be needed.
         *
         * ::VPNState is delivered via #StateCB method.
         */
        void getState();


        /**
         * This method triggers the retrieval of the current VPN statistics.
         * This allows an UI to notify the API that it is ready to receive 
         * statistics.
         *
         * ::VPNState is delivered via #StatsCB method.
         */
        void getStats();

        /**
         * This method resets current VPN statistics counters.
         */
        void resetStats();


        /**
         * This method activates the retrieval of VPN statistics and other
         * related data.  By default, VPNStats are automatically delivered
         * via the method #StatsCB.
         *
         * If the #stopStats method is called to stop the delivery of
         * statistics, this method can be called to resume delivery.  
         */
        void startStats();


        /**
         * This method stops the delivery of VPN statistics and
         * other related data.  By default, VPNStats are automatically
         * delivered.  This method disables delivery.
         *
         * The method #startStats can be called to resume the delivery of
         * statistics.
         */
        void stopStats();


      /**
       * This method directs where and how to export the statistics
       */
        void exportStats(const tstring &tstrFilePath);


        /**
         * Call this method after a #BannerCB has been received to indicate 
         * that the user response to the banner can now be read.
         *
         * \param bAccepted
         * indicates if the user accepted or declined the banner.
         */
        void setBannerResponse(bool bAccepted);

        /*
         * Call this method after a #CertBlockedCB has been received to
         * indicate the user's response to the blocked untrusted VPN server
         * error message.
         *
         * \param bUnblock indicates if the user wants to disable the
         * preference to block untrusted servers
        */
        void setCertBlockedResponse(bool bUnblock);

        /*
         * Call this method after a #CertWarningCB has been received to
         * indicate the user's response to the server certificate error
         * warning
         *
         * \param bConnect indicates user wants to connect anyways
         * \param bImport inidicates user wants to permanently trust
         * the VPN server. This would result in no future certificate
         * error warning prompts. bImport is only valid if
         * bConnect is true.
        */
        void setCertWarningResponse(bool bConnect, bool bImportCert);


        /**
         * Call this method to indicate that authentication credential
         * requests values solicited by the #UserPromptCB method can now
         * be read from the ConnectPromptInfo instance.
         */
        void UserSubmit();


        /**
         * Method for retrieving the currently available user preferences.
         * This method returns an instance of the class PreferenceInfo. The 
         * instance contains a variable number of Preference object pointers.  
         * Each preference contains data identifying the specific preference, 
         * its current value, etc. For a list of all possible preferences see
         * the ::PreferenceId enum in api.h. Note that some of these
         * preferences are not available to the user.
         *
         * @see PreferenceInfo
         */
        PreferenceInfo &getPreferences();


        /**
         * This method stores the current set values of the preferences to the 
         * preferences file(s).  This method is a counterpart to the 
         * getPreferences() method. 
         */
        bool savePreferences();

        /**
         * This method is used to import a PKCS12 file from a byte array.
         * May incite UserPromptCB() to prompt for the p12 password.  Will
         * invoke ImportPKCS12ResultCB() to indicate the result.
         * Returns true if the request was acknowledged, false otherwise.
         */
        bool requestImportPKCS12(const std::vector<unsigned char> &der);

        /**
         * This method is used to import a gettext localization file from a
         * byte array, for the specified locale. Returns true if the locale
         * file was successfully imported, false otherwise. 
         * Note: successful import does not guarantee that the specified
         * locale will be used.
         */
        bool requestImportLocalization(const tstring tstrLocale,
                                       const std::vector<unsigned char> &MoFileData);

        virtual ~ClientIfc();

    private:

        ClientIfc(const ClientIfc& other);
        ClientIfc& operator=(const ClientIfc& other);

};

#endif //_CLIENTIFC_