![]() |
AnyConnect Secure Mobility Client 4.8.02045
|
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_