![]() |
AnyConnect Secure Mobility Client 5.0.00556
|
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 ¬ice, 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_