| AnyConnect Secure Mobility Client 5.1.0.136

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

# include/ClientIfc.h

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