| AnyConnect Secure Mobility Client 5.0.00556

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

# include/ClientIfc.h

    00001 /**************************************************************************
    00002 *       Copyright (c) 2006, Cisco Systems, All Rights Reserved
    00003 ***************************************************************************
    00004 *
    00005 *  File:    ClientIfc.h
    00006 *  Date:    11/2006
    00007 *
    00008 ***************************************************************************
    00009 *
    00010 *   Client Interface class implementation for the Client API.
    00011 *
    00012 ***************************************************************************/
    00013
    00014 #ifndef _CLIENTIFC_
    00015 #define _CLIENTIFC_
    00016
    00017
    00018 /**
    00019 * This is the main interface class for applications that implement the
    00020 * Cisco AnyConnect Secure Mobility VPN API.  A program wishing to use the API must create a
    00021 * class that extends the ClientIfc class.  This new class is required to
    00022 * provide implementations for the pure virtual methods found in the protected
    00023 * section (for example, StatsCB).
    00024 *
    00025 * Finally, the public section contains methods that are available for
    00026 * managing the API.  These include methods like attach and connect.
    00027 *
    00028 * A client must implement the CB (abstract) methods found in the protected
    00029 * section of this interface.
    00030 *
    00031 */
    00032
    00033
    00034
    00035 #include "api.h"
    00036 #include "ClientIfcBase.h"
    00037 #include "VPNStats.h"
    00038 #include "ConnectPromptInfo.h"
    00039 #include "Preference.h"
    00040 #include "PreferenceInfo.h"
    00041
    00042 class VPN_VPNAPI ClientIfc : protected ClientIfcBase
    00043 {
    00044     protected:
    00045
    00046         /**
    00047          * Callback used to deliver new statistics related to the VPN
    00048          * connection.
    00049          *
    00050          * When a connection is active, a new set of statistics is
    00051          * delivered each second.
    00052          *
    00053          * @see resetStats(), stopStats() and startStats()
    00054          *
    00055          */
    00056         virtual void StatsCB(VPNStats &stats) = 0;
    00057
    00058
    00059         /**
    00060          * Callback used to deliver VPN state and state change string.
    00061          * The stateString delivered by this method is localized.
    00062          *
    00063          * See the ::VPNState enum found in api.h for set of valid states.
    00064          */
    00065         virtual void StateCB(const VPNState state,
    00066                              const VPNSubState subState,
    00067                              const tstring stateString) = 0;
    00068
    00069
    00070         /**
    00071          * If a banner needs to be acknowledged, this CB delivers the banner
    00072          * to the client.
    00073          *
    00074          * NOTE: Connection establishment will block until the method
    00075          * setBannerResponse() is called.
    00076          *
    00077          * In a GUI, a banner would typically be displayed in a modal dialog
    00078          * with an accept or decline button selection.
    00079          *
    00080          * @see setBannerResponse() to set the user response to the banner.
    00081          */
    00082         virtual void BannerCB(const tstring &banner) = 0;
    00083
    00084         /**
    00085          * If a pre-connect reminder needs to be acknowledged, this CB delivers
    00086          * the pre-connect reminder to the client.
    00087          *
    00088          * NOTE: Connection establishment will block until the method
    00089          * setPreConnectReminderResponse() is called.
    00090          *
    00091          * In a GUI, a pre-connect reminder would typically be displayed in a modal
    00092          * dialog with an OK button selection.
    00093          *
    00094          * @see setPreConnectReminderResponse() to set the user acknowledgement to
    00095          * the pre-connect reminder message.
    00096          */
    00097         virtual void PreConnectReminderCB(const tstring &rtstrPreConnectReminder);
    00098
    00099         /**
    00100          * Messages are delivered via the NoticeCB and can come from multiple
    00101          * sources.  There are four message types (error, warning, info and
    00102          * status).  See the ::MessageType enum in api.h for the list.
    00103          *
    00104          * Clients using the API as an embedded application (not
    00105          * user visible) might want to further characterize
    00106          * messages.  One option here is to use the AnyConnect message
    00107          * catalog and assign message codes as the translations for
    00108          * various messages.  An application could then track messages based
    00109          * on its own error code scheme.
    00110          */
    00111         virtual void NoticeCB(const tstring &notice,
    00112                               const MessageType type,
    00113                               const bool bSensitive = false) = 0;
    00114
    00115
    00116         /**
    00117          * This CB would likely occur only during a connection when it was
    00118          * detected that the software needed to be upgraded, or when Start
    00119          * Before Logon (SBL) is being used.
    00120          *
    00121          * Unlike the other callback methods, this method provides a default
    00122          * implementation (calling the system's exit() function).
    00123          * If clients of the API wish to override this behavior, they are
    00124          * responsible for ensuring that the current running process exits with
    00125          * the return code specified by returnCode.
    00126          *
    00127          * <b>Caution</b>: IF YOU OVERRIDE THIS METHOD AND DO NOT EXIT WITH
    00128          * THE PROPER CODE SOFTWARE UPDATE FUNCTIONALITY IN YOUR CLIENT WILL
    00129          * BREAK
    00130          */
    00131         virtual void ExitNoticeCB(const tstring &tstrNotice,
    00132                                   const int returnCode);
    00133
    00134
    00135         /**
    00136          * Under normal operating conditions, this CB is called as soon
    00137          * as the attach method completes.  In case the service (vpn agent)
    00138          * is not ready, this CB is not called until it is.
    00139          *
    00140          * Any API calls made prior to this CB being called will result in a
    00141          * NoticeCB error message.
    00142          */
    00143         virtual void ServiceReadyCB() = 0;
    00144
    00145
    00146
    00147         /**
    00148          * This method supports prompting for single or multiple values.  All
    00149          * prompts are considered mandatory.
    00150          *
    00151          * The ConnectPromptInfo object contains a list of PromptEntry
    00152          * instances.  The labels and their default values (if any) can be
    00153          * found in these instances.  After the data has been collected from the user
    00154          * it can be set into these same instances.  When ready, the client
    00155          * application should call the method UserSubmit() to have the
    00156          * responses read by the API.
    00157          */
    00158         virtual void UserPromptCB(ConnectPromptInfo &ConnectPrompt) = 0;
    00159
    00160
    00161         /**
    00162          * Use this method to provide Window Manager hints to GUI
    00163          * applications.  To receive these hints, the application must
    00164          * identify itself as a GUI in the attach method.  In addition, this
    00165          * method should be overriden to receive any generated events.
    00166          *
    00167          * Event that can be received include those indicating that a user is
    00168          * starting a second instance of the GUI application.  This information
    00169          * can be used to tell the already running application to un-minimize
    00170          * itself and let the new program know that it should Quit (since a GUI
    00171          * is already running).
    00172          */
    00173         virtual void WMHintCB(const WMHint hint,
    00174                               const WMHintReason reason);
    00175
    00176
    00177         /**
    00178          * This method is useful when the connection to the secure gateway
    00179          * has been established as part of a web-launch of the VPN tunnel.
    00180          *
    00181          * If the client application wishes to be notified of the secure
    00182          * gateway to which the VPN has been established, this method should
    00183          * be overriden.
    00184          *
    00185          * If the client application is started and a tunnel is already active,
    00186          * this method also delivers the name of the secure gateway host.
    00187          */
    00188         virtual void deliverWebLaunchHostCB(const tstring &activeHost);
    00189
    00190         /**
    00191          * This method is called when the preference to block untrusted
    00192          * servers is enabled and the current VPN server being connected
    00193          * to is untrusted. Clients should present an error to the user
    00194          * notifying them that the current connection to rtstrUntrustedServer
    00195          * is being blocked. The client should also provide a way for the
    00196          * user to change the preference to block untrusted servers.
    00197          *
    00198          * The user response must be indicated using setCertBlockedResponse
    00199         */
    00200         virtual void CertBlockedCB(const tstring &rtstrUntrustedServer) = 0;
    00201
    00202         /**
    00203          * This method is called when connections to untrusted VPN servers
    00204          * is allowed by policies and the current VPN server being connected
    00205          * to is untrusted. Clients should present a warning to the user
    00206          * notifying them that the current connection to rtstrUntrustedServer
    00207          * is unsafe. The reason the VPN server is untrusted is provided in
    00208          * rltstrCertErrors. The client should provide a way for the user to
    00209          * connect once, connect and always trust or cancel the connection.
    00210          * If bAllowImport is set to false then the always trust option should
    00211          * not be presented to users.
    00212          *
    00213          * The user response must be indicated using setCertWarningResponse
    00214         */
    00215         virtual void CertWarningCB(const tstring &rtstrUntrustedServer,
    00216                                    const std::list<tstring> &rltstrCertErrors,
    00217                                    bool bAllowImport) = 0;
    00218
    00219         /**
    00220          * This method can be overriden if the client application wishes to
    00221          * exercise some control over the delivery of events from the other
    00222          * protected methods in this class.
    00223          *
    00224          * This might be necessary in cases where a GUI is being written and
    00225          * the data from this API needs to be delivered in the GUI or main
    00226          * thread.  In this case, you should override this method and when it
    00227          * is called by the API post an event to your event queue (message
    00228          * pump, etc.).  After this event executes in your GUI or main thread,
    00229          * call the method ClientIfc::ProcessEvents to have events delivered
    00230          * to your client application.
    00231          */
    00232         virtual void EventAvailable();
    00233
    00234
    00235         ClientIfc();
    00236
    00237
    00238     public:
    00239
    00240         /**
    00241          * After the ClientIfc class has been created, the client implementation
    00242          * must invoke this method prior to attempting connections,
    00243          * retrieving statistics, etc.  If successful, this method returns
    00244          * true.  If not successful, it returns false and returns a notice error
    00245          * message to the user.
    00246          *
    00247          * A single call to this method is all that is necessary.  If the
    00248          * attach fails, a message indicating the VPN service is not available
    00249          * is returned.  If the call succeeds, the ServiceReadyCB is
    00250          * called and true is returned.
    00251          *
    00252          * \param ClientType clientType (default ClientType_GUI)
    00253          * Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT.
    00254          * ClientType_GUI: indicates that the started program is a GUI
    00255          * application.  With this attribute set to true, the application will
    00256          * now receive WMHints.
    00257          * ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation
    00258          * where a GUI can be launched prior to the normal windows logon sequence.
    00259          * This allows a VPN tunnel to be activated and used as part of the windows
    00260          * logon sequence. This value is applicable only when a corresponding
    00261          * argument has been passed to the program by the VPN agent.
    00262          * ClientType_CLI: indicates that the started program is a CLI application.
    00263          * ClientType_MGMT: indicates that the started program is used to initiate
    00264          *                  an AnyConnect management VPN tunnel. This value is
    00265          *                  applicable only to a client launched by AnyConnect VPN agent.
    00266          *
    00267          * \param requestFullCapabilities indicates that the client program is
    00268          * requesting full API capabilities.  Full capabilities allows the
    00269          * client program to connect, disconnect, receive statistics, etc.
    00270          * When full capabilities are not requested or not available, the
    00271          * client program will not be able to establish new VPN connections.
    00272          * Only a client program with full capabilites can do this.  In
    00273          * addition, only the first program requesting full capabilities will
    00274          * be granted this level of access.  The attach method can succeed
    00275          * even if full capabilities is requested but not granted.  To test
    00276          * for this state, use the method ::hasFullCapabilities.
    00277          *
    00278          * \param suppressAutoConnect indicates that the client wishes to
    00279          * override automatically initiating a connection to the last connected
    00280          * secure gateway at startup.  Normally, this is determined by the
    00281          * value of the AutoConnectOnStart preference.  If this flag is true
    00282          * then an automatic connection will never be initiated, even if
    00283          * AutoConnectOnStart is enabled.
    00284          */
    00285         bool attach(ClientType clientType = ClientType_GUI,
    00286                     bool requestFullCapabilities = true,
    00287                     bool suppressAutoConnect = true);
    00288
    00289
    00290         /**
    00291          * After the client program is done, call the detach method to do a
    00292          * graceful cleanup.  This method stops the flow
    00293          * of events and does general cleanup.
    00294          */
    00295         void detach();
    00296
    00297
    00298         /**
    00299          * When the method ClientIfc::EventAvailable has been overriden in the
    00300          * client application, this method must be called to receive events.
    00301          *
    00302          * It is expected that GUI programs will use EventAvailable as a
    00303          * signal, allowing them to set an event using their native event
    00304          * handler.  When that event fires, the application can call
    00305          * ProcessEvents, which causes the API to deliver events in the
    00306          * client's main thread.
    00307          */
    00308         virtual void ProcessEvents();
    00309
    00310
    00311         /**
    00312          * Use this method to determine whether this application has full
    00313          * capabilities.  Only one application (the first one started) can have
    00314          * full capabilities.  If this is the first application started, this
    00315          * method returns true.  When an application has full capabilities,
    00316          * it can initiate connections, as well as offer UI capabilities.
    00317          */
    00318         bool hasFullCapabilities();
    00319
    00320
    00321         /**
    00322          * This method returns true if the client has an active VPN
    00323          * connection with a secure gateway.
    00324          */
    00325         bool isConnected();
    00326
    00327
    00328         /**
    00329          * This method returns true if the client VPN is available for use.
    00330          * If false is returned this means that VPN has been intentionally
    00331          * disabled.  This would indicate a situation where other AnyConnect
    00332          * services were in use but not VPN.
    00333          */
    00334         bool isAvailable();
    00335
    00336
    00337         /**
    00338          * This method returns true if the VPN service is available for
    00339          * establishing VPN connections.
    00340          */
    00341         bool isVPNServiceAvailable();
    00342
    00343
    00344         /**
    00345          * This method returns true if the mode in which the client is
    00346          * currently operating is enabled. For a list of all possible modes
    00347          * of operation see the ::OperatingMode enum in api.h.
    00348          */
    00349         bool isOperatingMode(OperatingMode opMode);
    00350
    00351         /**
    00352          * This method returns a list of secure gateway host names found in an
    00353          * AnyConnect profile.  If no profile is available, an empty
    00354          * list is returned.
    00355          */
    00356         std::list<tstring> getHostNames();
    00357
    00358
    00359         /**
    00360          * This method returns any default Host name from User Preferences.
    00361          *
    00362          * A host can be returned here even if there are no profiles on the
    00363          * system.  The host last connected to (via the connect method) is
    00364          * returned by this method.
    00365          *
    00366          * If there is no previously connected-to host, the first host found
    00367          * in an AnyConnect profile (if any) is returned.
    00368          */
    00369         tstring getDefaultHostName();
    00370
    00371
    00372         using ClientIfcBase::connect;
    00373         /**
    00374          * This method initiates a connection to the specified host.
    00375          * The connection results in the presentation of authentication
    00376          * credentials, as appropriate.  Any credentials returned by the secure
    00377          * gateway are delivered via the #UserPromptCB method.
    00378          *
    00379          * See ConnectPromptInfo for more details on possible authentication
    00380          * credentials.
    00381          *
    00382          * If the connection request is accepted, true is returned.  This does
    00383          * not mean the connection succeeded.  If the connection succeeds, a
    00384          * state of connect will be received via the #StateCB method.
    00385          */
    00386         bool connect(tstring host);
    00387
    00388         /**
    00389          * Use this method to change selected group after initial connection
    00390          * request has been made and credentials were delivered.
    00391          *
    00392          * Depending on secure gateway configuratiion, call to this method may
    00393          * result in a new connection request and will update credentials
    00394          * required for the selected group. New credentials returned by the
    00395          * secure gateway are delivered via the #UserPromptCB method.
    00396          */
    00397         virtual bool setNewTunnelGroup(const tstring & group);
    00398
    00399         /**
    00400          * Use this method to initiate a disconnect of the active VPN
    00401          * connection.
    00402          *
    00403          * An indication of VPN disconnect is received via the #StateCB
    00404          * method.
    00405          */
    00406         void disconnect();
    00407
    00408         /**
    00409         * Use this method to cancel the user authentication. VPN tunnel is not connected
    00410         * at the moment. This function is used to cancel SSO authentication.
    00411         *
    00412         * An indication of VPN disconnect is received via the #StateCB
    00413         * method.
    00414         */
    00415         void cancel();
    00416
    00417         /**
    00418          * This method triggers the retrieval of the current VPN state.
    00419          * After the client is conected to the VPN service via the #attach
    00420          * method, both the current state and any changes in state are
    00421          * automatically delivered to the client.  In general, this method
    00422          * should not be needed.
    00423          *
    00424          * ::VPNState is delivered via #StateCB method.
    00425          */
    00426         void getState();
    00427
    00428
    00429         /**
    00430          * This method triggers the retrieval of the current VPN statistics.
    00431          * This allows an UI to notify the API that it is ready to receive
    00432          * statistics.
    00433          *
    00434          * ::VPNState is delivered via #StatsCB method.
    00435          */
    00436         void getStats();
    00437
    00438         /**
    00439          * This method resets current VPN statistics counters.
    00440          */
    00441         void resetStats();
    00442
    00443
    00444         /**
    00445          * This method activates the retrieval of VPN statistics and other
    00446          * related data.  By default, VPNStats are automatically delivered
    00447          * via the method #StatsCB.
    00448          *
    00449          * If the #stopStats method is called to stop the delivery of
    00450          * statistics, this method can be called to resume delivery.
    00451          */
    00452         void startStats();
    00453
    00454
    00455         /**
    00456          * This method stops the delivery of VPN statistics and
    00457          * other related data.  By default, VPNStats are automatically
    00458          * delivered.  This method disables delivery.
    00459          *
    00460          * The method #startStats can be called to resume the delivery of
    00461          * statistics.
    00462          */
    00463         void stopStats();
    00464
    00465
    00466       /**
    00467        * This method directs where and how to export the statistics
    00468        */
    00469         void exportStats(const tstring &tstrFilePath);
    00470
    00471
    00472         /**
    00473          * Call this method after a #BannerCB has been received to indicate
    00474          * that the user response to the banner can now be read.
    00475          *
    00476          * \param bAccepted
    00477          * indicates if the user accepted or declined the banner.
    00478          */
    00479         void setBannerResponse(bool bAccepted);
    00480
    00481         /**
    00482          * Call this method after a #PreConnectReminderCB has been received
    00483          * to indicate that user has acknowledged pre-connect reminder message.
    00484          *
    00485          * NOTE : Ignoring the response from user (for example, closing the modal
    00486          *        dialog instead of clicking OK button). Old AnyConnect client (v3.1)
    00487          *        ignored the response too.
    00488          */
    00489         void setPreConnectReminderResponse();
    00490
    00491         /*
    00492          * Call this method after a #CertBlockedCB has been received to
    00493          * indicate the user's response to the blocked untrusted VPN server
    00494          * error message.
    00495          *
    00496          * \param bUnblock indicates if the user wants to disable the
    00497          * preference to block untrusted servers
    00498         */
    00499         void setCertBlockedResponse(bool bUnblock);
    00500
    00501         /*
    00502          * Call this method after a #CertWarningCB has been received to
    00503          * indicate the user's response to the server certificate error
    00504          * warning
    00505          *
    00506          * \param bConnect indicates user wants to connect anyways
    00507          * \param bImport inidicates user wants to permanently trust
    00508          * the VPN server. This would result in no future certificate
    00509          * error warning prompts. bImport is only valid if
    00510          * bConnect is true and bAllowImport is true when a CertWarningCB
    00511          * was given.
    00512         */
    00513         void setCertWarningResponse(bool bConnect, bool bImportCert);
    00514
    00515
    00516         /**
    00517          * Call this method to indicate that authentication credential
    00518          * requests values solicited by the #UserPromptCB method can now
    00519          * be read from the ConnectPromptInfo instance.
    00520          */
    00521         void UserSubmit();
    00522
    00523
    00524         /**
    00525          * Method for retrieving the currently available user preferences.
    00526          * This method returns an instance of the class PreferenceInfo. The
    00527          * instance contains a variable number of Preference object pointers.
    00528          * Each preference contains data identifying the specific preference,
    00529          * its current value, etc. For a list of all possible preferences see
    00530          * the ::PreferenceId enum in api.h. Note that some of these
    00531          * preferences are not available to the user.
    00532          *
    00533          * @see PreferenceInfo
    00534          */
    00535         PreferenceInfo &getPreferences();
    00536
    00537
    00538         /**
    00539          * This method stores the current set values of the preferences to the
    00540          * preferences file(s).  This method is a counterpart to the
    00541          * getPreferences() method.
    00542          */
    00543         bool savePreferences();
    00544
    00545         /**
    00546          * This is called from the credential dialog in the GUI to get the correct
    00547          * friendly name for the dialog title.
    00548          */
    00549         tstring getConnectHost();
    00550
    00551         /**
    00552          * This method sets the last VPN error seen during this connection
    00553          * attempt for reporting purposes. This VPN error should be cleared for
    00554          * each connection attempt.
    00555          */
    00556         void setLastVpnError(VPNError vpnError);
    00557
    00558
    00559         /**
    00560          * This method gets the last VPN error seen during this connection
    00561          * attempt for reporting purposes. This VPN error should be cleared for
    00562          * each connection attempt.
    00563          */
    00564         VPNError getLastVpnError();
    00565
    00566         virtual ~ClientIfc();
    00567
    00568     private:
    00569
    00570         ClientIfc(const ClientIfc& other);
    00571         ClientIfc& operator=(const ClientIfc& other);
    00572
    00573 };
    00574
    00575 #endif //_CLIENTIFC_