AnyConnect Secure Mobility Client 4.10.06090

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_