AnyConnect Secure Mobility Client 4.8.02045

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