| AnyConnect Secure Mobility Client 5.0.01242

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

# include/ClientIfc.h

    00001 /**************************************************************************
    00002 *   Copyright (c) 2006, 2022 Cisco Systems, Inc.
    00003 *   All Rights Reserved. Cisco Highly Confidential.
    00004 ***************************************************************************
    00005 *
    00006 *   File: ClientIfc.h
    00007 *   Date: 11/2006
    00008 *
    00009 ***************************************************************************
    00010 *   Client Interface class implementation for the Client API.
    00011 ***************************************************************************/
    00012
    00013 #ifndef _CLIENTIFC_
    00014 #define _CLIENTIFC_
    00015
    00016
    00017 /**
    00018 * This is the main interface class for applications that implement the
    00019 * Cisco AnyConnect Secure Mobility VPN API.  A program wishing to use the API must create a
    00020 * class that extends the ClientIfc class.  This new class is required to
    00021 * provide implementations for the pure virtual methods found in the protected
    00022 * section (for example, StatsCB).
    00023 *
    00024 * Finally, the public section contains methods that are available for
    00025 * managing the API.  These include methods like attach and connect.
    00026 *
    00027 * A client must implement the CB (abstract) methods found in the protected
    00028 * section of this interface.
    00029 *
    00030 */
    00031
    00032 #include "api.h"
    00033 #include "ClientIfcBase.h"
    00034 #include "VPNStats.h"
    00035 #include "ConnectPromptInfo.h"
    00036 #include "Preference.h"
    00037 #include "PreferenceInfo.h"
    00038
    00039 class ClientIfcData;
    00040
    00041 class VPN_VPNAPI ClientIfc :
    00042     protected ClientIfcBase
    00043 {
    00044     friend class ClientIfcData;
    00045
    00046     protected:
    00047
    00048         ClientIfc();
    00049
    00050         virtual ~ClientIfc();
    00051
    00052         /**
    00053         * Callback Declarations inherited from ClientIfcBase.
    00054         *
    00055         * Virtual Abstract Callback Method Declarations:
    00056         *   StatsCB
    00057         *   StateCB
    00058         *   BannerCB
    00059         *   NoticeCB
    00060         *   CertBannerCB
    00061         *   ServiceReadyCB
    00062         *   UserPromptCB
    00063         *   CertBlockedCB
    00064         *   CertWarningCB (2 signatures)
    00065         *   ClientCertificateCB
    00066         *
    00067         * Virtual Callback Method Declarations:
    00068         *   PreConnectReminderCB
    00069         *   ExitNoticeCB
    00070         *   WMHintCB
    00071         *   deliverWebLaunchHostCB
    00072         *   EventAvailable
    00073         *   ImportPKCS12ResultCB
    00074         *   AgentDetachedCB
    00075         */
    00076
    00077     public:
    00078
    00079         /**
    00080          * After the ClientIfc class has been created, the client implementation
    00081          * must invoke this method prior to attempting connections,
    00082          * retrieving statistics, etc.  If successful, this method returns
    00083          * true.  If not successful, it returns false and returns a notice error
    00084          * message to the user.
    00085          *
    00086          * A single call to this method is all that is necessary.  If the
    00087          * attach fails, a message indicating the VPN service is not available
    00088          * is returned.  If the call succeeds, the ServiceReadyCB is
    00089          * called and true is returned.
    00090          *
    00091          * \param ClientType clientType (default ClientType_GUI)
    00092          * Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT.
    00093          * ClientType_GUI: indicates that the started program is a GUI
    00094          * application.  With this attribute set to true, the application will
    00095          * now receive WMHints.
    00096          * ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation
    00097          * where a GUI can be launched prior to the normal windows logon sequence.
    00098          * This allows a VPN tunnel to be activated and used as part of the windows
    00099          * logon sequence. This value is applicable only when a corresponding
    00100          * argument has been passed to the program by the VPN agent.
    00101          * ClientType_CLI: indicates that the started program is a CLI application.
    00102          * ClientType_MGMT: indicates that the started program is used to initiate
    00103          *                  an AnyConnect management VPN tunnel. This value is
    00104          *                  applicable only to a client launched by AnyConnect VPN agent.
    00105          *
    00106          * \param requestFullCapabilities indicates that the client program is
    00107          * requesting full API capabilities.  Full capabilities allows the
    00108          * client program to connect, disconnect, receive statistics, etc.
    00109          * When full capabilities are not requested or not available, the
    00110          * client program will not be able to establish new VPN connections.
    00111          * Only a client program with full capabilites can do this.  In
    00112          * addition, only the first program requesting full capabilities will
    00113          * be granted this level of access.  The attach method can succeed
    00114          * even if full capabilities is requested but not granted.  To test
    00115          * for this state, use the method ::hasFullCapabilities.
    00116          *
    00117          * \param suppressAutoConnect indicates that the client wishes to
    00118          * override automatically initiating a connection to the last connected
    00119          * secure gateway at startup.  Normally, this is determined by the
    00120          * value of the AutoConnectOnStart preference.  If this flag is true
    00121          * then an automatic connection will never be initiated, even if
    00122          * AutoConnectOnStart is enabled.
    00123          */
    00124         bool attach(ClientType clientType = ClientType_GUI,
    00125                     bool requestFullCapabilities = true,
    00126                     bool suppressAutoConnect = true);
    00127
    00128
    00129         /**
    00130          * After the client program is done, call the detach method to do a
    00131          * graceful cleanup.  This method stops the flow
    00132          * of events and does general cleanup.
    00133          */
    00134         void detach();
    00135
    00136
    00137         /**
    00138          * When the method ClientIfc::EventAvailable has been overridden in the
    00139          * client application, this method must be called to receive events.
    00140          *
    00141          * It is expected that GUI programs will use EventAvailable as a
    00142          * signal, allowing them to set an event using their native event
    00143          * handler.  When that event fires, the application can call
    00144          * ProcessEvents, which causes the API to deliver events in the
    00145          * client's main thread.
    00146          */
    00147         void ProcessEvents();
    00148
    00149
    00150         /**
    00151          * Use this method to determine whether this application has full
    00152          * capabilities.  Only one application (the first one started) can have
    00153          * full capabilities.  If this is the first application started, this
    00154          * method returns true.  When an application has full capabilities,
    00155          * it can initiate connections, as well as offer UI capabilities.
    00156          */
    00157         bool hasFullCapabilities();
    00158
    00159
    00160         /**
    00161          * This method returns true if the client has an active VPN
    00162          * connection with a secure gateway.
    00163          */
    00164         bool isConnected(bool bSilent = false);
    00165
    00166
    00167         /**
    00168          * This method returns true if the client VPN is available for use.
    00169          * If false is returned this means that VPN has been intentionally
    00170          * disabled.  This would indicate a situation where other AnyConnect
    00171          * services were in use but not VPN.
    00172          */
    00173         bool isAvailable();
    00174
    00175
    00176         /**
    00177          * This method returns true if the VPN service is available for
    00178          * establishing VPN connections.
    00179          */
    00180         bool isVPNServiceAvailable();
    00181
    00182
    00183         /**
    00184          * This method returns true if the mode in which the client is
    00185          * currently operating is enabled. For a list of all possible modes
    00186          * of operation see the ::OperatingMode enum in api.h.
    00187          */
    00188         bool isOperatingMode(OperatingMode opMode);
    00189
    00190         /**
    00191          * This method returns a list of secure gateway host names found in an
    00192          * AnyConnect profile.  If no profile is available, an empty
    00193          * list is returned.
    00194          */
    00195         std::list<tstring> getHostNames();
    00196
    00197
    00198         /**
    00199          * This method returns any default Host name from User Preferences.
    00200          *
    00201          * A host can be returned here even if there are no profiles on the
    00202          * system.  The host last connected to (via the connect method) is
    00203          * returned by this method.
    00204          *
    00205          * If there is no previously connected-to host, the first host found
    00206          * in an AnyConnect profile (if any) is returned.
    00207          */
    00208         tstring getDefaultHostName();
    00209
    00210
    00211         /**
    00212          * This method initiates a connection to the specified host.
    00213          * The connection results in the presentation of authentication
    00214          * credentials, as appropriate.  Any credentials returned by the secure
    00215          * gateway are delivered via the #UserPromptCB method.
    00216          *
    00217          * See ConnectPromptInfo for more details on possible authentication
    00218          * credentials.
    00219          *
    00220          * If the connection request is accepted, true is returned.  This does
    00221          * not mean the connection succeeded.  If the connection succeeds, a
    00222          * state of connect will be received via the #StateCB method.
    00223          */
    00224         bool connect(
    00225             tstring host);
    00226
    00227 #if defined(HOST_DATA_SUPPORTED)
    00228         bool connect(
    00229             const IHostData& host);
    00230 #endif
    00231
    00232         bool connect(
    00233 #if defined(HOST_DATA_SUPPORTED)
    00234             const IHostData& host,
    00235 #else
    00236             tstring host,
    00237 #endif
    00238             unsigned int origin);
    00239
    00240         /**
    00241          * Use this method to change selected group after initial connection
    00242          * request has been made and credentials were delivered.
    00243          *
    00244          * Depending on secure gateway configuratiion, call to this method may
    00245          * result in a new connection request and will update credentials
    00246          * required for the selected group. New credentials returned by the
    00247          * secure gateway are delivered via the #UserPromptCB method.
    00248          */
    00249         bool setNewTunnelGroup(const tstring & group);
    00250
    00251         /**
    00252          * Use this method to initiate a disconnect of the active VPN
    00253          * connection.
    00254          *
    00255          * An indication of VPN disconnect is received via the #StateCB
    00256          * method.
    00257          */
    00258         void disconnect();
    00259
    00260         /**
    00261         * Use this method to cancel the user authentication. VPN tunnel is not connected
    00262         * at the moment. This function is used to cancel SSO authentication.
    00263         *
    00264         * An indication of VPN disconnect is received via the #StateCB
    00265         * method.
    00266         */
    00267         void cancel();
    00268
    00269         /**
    00270          * This method triggers the retrieval of the current VPN state.
    00271          * After the client is conected to the VPN service via the #attach
    00272          * method, both the current state and any changes in state are
    00273          * automatically delivered to the client.  In general, this method
    00274          * should not be needed.
    00275          *
    00276          * ::VPNState is delivered via #StateCB method.
    00277          */
    00278         void getState();
    00279
    00280
    00281         /**
    00282          * This method triggers the retrieval of the current VPN statistics.
    00283          * This allows an UI to notify the API that it is ready to receive
    00284          * statistics.
    00285          *
    00286          * ::VPNState is delivered via #StatsCB method.
    00287          */
    00288         void getStats();
    00289
    00290         /**
    00291          * This method resets current VPN statistics counters.
    00292          */
    00293         void resetStats();
    00294
    00295
    00296         /**
    00297          * This method activates the retrieval of VPN statistics and other
    00298          * related data.  By default, VPNStats are automatically delivered
    00299          * via the method #StatsCB.
    00300          *
    00301          * If the #stopStats method is called to stop the delivery of
    00302          * statistics, this method can be called to resume delivery.
    00303          */
    00304         void startStats();
    00305
    00306
    00307         /**
    00308          * This method stops the delivery of VPN statistics and
    00309          * other related data.  By default, VPNStats are automatically
    00310          * delivered.  This method disables delivery.
    00311          *
    00312          * The method #startStats can be called to resume the delivery of
    00313          * statistics.
    00314          */
    00315         void stopStats();
    00316
    00317
    00318         /**
    00319          * This method directs where and how to export the statistics
    00320          */
    00321         void exportStats(const tstring &tstrFilePath);
    00322
    00323
    00324         /**
    00325          * Call this method after a #BannerCB has been received to indicate
    00326          * that the user response to the banner can now be read.
    00327          *
    00328          * \param bAccepted
    00329          * indicates if the user accepted or declined the banner.
    00330          */
    00331         void setBannerResponse(bool bAccepted);
    00332
    00333         /**
    00334          * Call this method after a #PreConnectReminderCB has been received
    00335          * to indicate that user has acknowledged pre-connect reminder message.
    00336          *
    00337          * NOTE : Ignoring the response from user (for example, closing the modal
    00338          *        dialog instead of clicking OK button). Old AnyConnect client (v3.1)
    00339          *        ignored the response too.
    00340          */
    00341         void setPreConnectReminderResponse();
    00342
    00343         /*
    00344          * Call this method after a #CertBlockedCB has been received to
    00345          * indicate the user's response to the blocked untrusted VPN server
    00346          * error message.
    00347          *
    00348          * \param bUnblock indicates if the user wants to disable the
    00349          * preference to block untrusted servers
    00350         */
    00351         void setCertBlockedResponse(bool bUnblock);
    00352
    00353         /*
    00354          * Call this method after a #CertWarningCB has been received to
    00355          * indicate the user's response to the server certificate error
    00356          * warning
    00357          *
    00358          * \param bConnect indicates user wants to connect anyways
    00359          * \param bImport inidicates user wants to permanently trust
    00360          * the VPN server. This would result in no future certificate
    00361          * error warning prompts. bImport is only valid if
    00362          * bConnect is true and bAllowImport is true when a CertWarningCB
    00363          * was given.
    00364         */
    00365         void setCertWarningResponse(bool bConnect, bool bImportCert);
    00366
    00367
    00368         /**
    00369          * Call this method to indicate that authentication credential
    00370          * requests values solicited by the #UserPromptCB method can now
    00371          * be read from the ConnectPromptInfo instance.
    00372          */
    00373         void UserSubmit();
    00374
    00375
    00376         /**
    00377          * Method for retrieving the currently available user preferences.
    00378          * This method returns an instance of the class PreferenceInfo. The
    00379          * instance contains a variable number of Preference object pointers.
    00380          * Each preference contains data identifying the specific preference,
    00381          * its current value, etc. For a list of all possible preferences see
    00382          * the ::PreferenceId enum in api.h. Note that some of these
    00383          * preferences are not available to the user.
    00384          *
    00385          * @see PreferenceInfo
    00386          */
    00387         PreferenceInfo &getPreferences();
    00388
    00389
    00390         /**
    00391          * This method stores the current set values of the preferences to the
    00392          * preferences file(s).  This method is a counterpart to the
    00393          * getPreferences() method.
    00394          */
    00395         bool savePreferences();
    00396
    00397         /**
    00398          * This is called from the credential dialog in the GUI to get the correct
    00399          * friendly name for the dialog title.
    00400          */
    00401         tstring getConnectHost();
    00402
    00403         /**
    00404          * This method sets the last VPN error seen during this connection
    00405          * attempt for reporting purposes. This VPN error should be cleared for
    00406          * each connection attempt.
    00407          */
    00408         void setLastVpnError(VPNError vpnError);
    00409
    00410
    00411         /**
    00412          * This method gets the last VPN error seen during this connection
    00413          * attempt for reporting purposes. This VPN error should be cleared for
    00414          * each connection attempt.
    00415          */
    00416         VPNError getLastVpnError();
    00417
    00418         /**
    00419         * This method indicates if a request to connect has been initiated and the SG is being
    00420         * contacted. Note: the connect request is not active while waiting for the user to enter
    00421         * credentials.
    00422         */
    00423         bool isConnectRequestActive();
    00424
    00425     private:
    00426
    00427         //
    00428         //
    00429         // Private Member Methods
    00430         //
    00431         //
    00432
    00433         ClientIfc(const ClientIfc& other);
    00434         ClientIfc& operator=(const ClientIfc& other);
    00435
    00436         virtual void EventNotificationInternalCB(
    00437             const std::shared_ptr<CEventNotificationTlv>& spEventNtfctnTlv);
    00438
    00439         using ClientIfcBase::ClientIfcTransmigration;
    00440
    00441         //
    00442         //
    00443         // Private Member Data
    00444         //
    00445         //
    00446
    00447         ClientIfcData* const m_pClientIfcData;
    00448 };
    00449
    00450 #endif //_CLIENTIFC_