| AnyConnect Secure Mobility Client 5.1.10.233

ClientIfc.h
1/**************************************************************************
2* Copyright (c) 2006, 2022-2023 Cisco Systems, Inc.
3* All Rights Reserved. Cisco Highly Confidential.
4***************************************************************************
5*
6* File: ClientIfc.h
7* Date: 11/2006
8*
9***************************************************************************
10* Client Interface class implementation for the Client API.
11***************************************************************************/
12
13#ifndef _CLIENTIFC_
14#define _CLIENTIFC_
15
16
17/**
18* This is the main interface class for applications that implement the
19* Cisco AnyConnect Secure Mobility VPN API. A program wishing to use the API must create a
20* class that extends the ClientIfc class. This new class is required to
21* provide implementations for the pure virtual methods found in the protected
22* section (for example, StatsCB).
23*
24* Finally, the public section contains methods that are available for
25* managing the API. These include methods like attach and connect.
26*
27* A client must implement the CB (abstract) methods found in the protected
28* section of this interface.
29*
30*/
31
32#include "ClientIfcCommon.h"
33#include "api.h"
34#include "ClientIfcBase.h"
35#include "VPNStats.h"
36#include "ConnectPromptInfo.h"
37#include "Preference.h"
38#include "PreferenceInfo.h"
39
40 class ClientIfcData;
41
42 class VPN_VPNAPI ClientIfc :
43 protected ClientIfcBase
44{
45 friend class ClientIfcData;
46
47 protected:
48
49 ClientIfc();
50
51 virtual ~ClientIfc();
52
53 /**
54 * Callback Declarations inherited from ClientIfcBase.
55 *
56 * Virtual Abstract Callback Method Declarations:
57 * StatsCB
58 * StateCB
59 * BannerCB
60 * NoticeCB
61 * CertBannerCB
62 * ServiceReadyCB
63 * UserPromptCB
64 * CertBlockedCB
65 * CertWarningCB (2 signatures)
66 * ClientCertificateCB
67 *
68 * Virtual Callback Method Declarations:
69 * PreConnectReminderCB
70 * ExitNoticeCB
71 * WMHintCB
72 * deliverWebLaunchHostCB
73 * EventAvailable
74 * ImportPKCS12ResultCB
75 * AgentDetachedCB
76 */
77
78 public:
79
80 /**
81 * After the ClientIfc class has been created, the client implementation
82 * must invoke this method prior to attempting connections,
83 * retrieving statistics, etc. If successful, this method returns
84 * true. If not successful, it returns false and returns a notice error
85 * message to the user.
86 *
87 * A single call to this method is all that is necessary. If the
88 * attach fails, a message indicating the VPN service is not available
89 * is returned. If the call succeeds, the ServiceReadyCB is
90 * called and true is returned.
91 *
92 * \param ClientType clientType (default ClientType_GUI)
93 * Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT.
94 * ClientType_GUI: indicates that the started program is a GUI
95 * application. With this attribute set to true, the application will
96 * now receive WMHints.
97 * ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation
98 * where a GUI can be launched prior to the normal windows logon sequence.
99 * This allows a VPN tunnel to be activated and used as part of the windows
100 * logon sequence. This value is applicable only when a corresponding
101 * argument has been passed to the program by the VPN agent.
102 * ClientType_CLI: indicates that the started program is a CLI application.
103 * ClientType_MGMT: indicates that the started program is used to initiate
104 * an AnyConnect management VPN tunnel. This value is
105 * applicable only to a client launched by AnyConnect VPN agent.
106 *
107 * \param requestFullCapabilities indicates that the client program is
108 * requesting full API capabilities. Full capabilities allows the
109 * client program to connect, disconnect, receive statistics, etc.
110 * When full capabilities are not requested or not available, the
111 * client program will not be able to establish new VPN connections.
112 * Only a client program with full capabilites can do this. In
113 * addition, only the first program requesting full capabilities will
114 * be granted this level of access. The attach method can succeed
115 * even if full capabilities is requested but not granted. To test
116 * for this state, use the method ::hasFullCapabilities.
117 *
118 * \param suppressAutoConnect indicates that the client wishes to
119 * override automatically initiating a connection to the last connected
120 * secure gateway at startup. Normally, this is determined by the
121 * value of the AutoConnectOnStart preference. If this flag is true
122 * then an automatic connection will never be initiated, even if
123 * AutoConnectOnStart is enabled.
124 */
125 bool attach(ClientType clientType = ClientType_GUI,
126 bool requestFullCapabilities = true,
127 bool suppressAutoConnect = true);
128
129
130 /**
131 * After the client program is done, call the detach method to do a
132 * graceful cleanup. This method stops the flow
133 * of events and does general cleanup.
134 */
135 void detach();
136
137
138 /**
139 * When the method ClientIfc::EventAvailable has been overridden in the
140 * client application, this method must be called to receive events.
141 *
142 * It is expected that GUI programs will use EventAvailable as a
143 * signal, allowing them to set an event using their native event
144 * handler. When that event fires, the application can call
145 * ProcessEvents, which causes the API to deliver events in the
146 * client's main thread.
147 */
148 void ProcessEvents();
149
150
151 /**
152 * Use this method to determine whether this application has full
153 * capabilities. Only one application (the first one started) can have
154 * full capabilities. If this is the first application started, this
155 * method returns true. When an application has full capabilities,
156 * it can initiate connections, as well as offer UI capabilities.
157 */
158 bool hasFullCapabilities();
159
160
161 /**
162 * This method returns true if the client has an active VPN
163 * connection with a secure gateway.
164 */
165 bool isConnected(bool bSilent = false);
166
167
168 /**
169 * This method returns true if the client VPN is available for use.
170 * If false is returned this means that VPN has been intentionally
171 * disabled. This would indicate a situation where other AnyConnect
172 * services were in use but not VPN.
173 */
174 bool isAvailable();
175
176
177 /**
178 * This method returns true if the VPN service is available for
179 * establishing VPN connections.
180 */
181 bool isVPNServiceAvailable();
182
183
184 /**
185 * This method returns true if the mode in which the client is
186 * currently operating is enabled. For a list of all possible modes
187 * of operation see the ::OperatingMode enum in api.h.
188 */
189 bool isOperatingMode(OperatingMode opMode);
190
191 /**
192 * This method returns a list of secure gateway host names found in an
193 * AnyConnect profile. If no profile is available, an empty
194 * list is returned.
195 */
196 std::list<tstring> getHostNames();
197
198
199 /**
200 * This method returns any default Host name from User Preferences.
201 *
202 * A host can be returned here even if there are no profiles on the
203 * system. The host last connected to (via the connect method) is
204 * returned by this method.
205 *
206 * If there is no previously connected-to host, the first host found
207 * in an AnyConnect profile (if any) is returned.
208 */
209 tstring getDefaultHostName();
210
211
212 /**
213 * This method initiates a connection to the specified host.
214 * The connection results in the presentation of authentication
215 * credentials, as appropriate. Any credentials returned by the secure
216 * gateway are delivered via the #UserPromptCB method.
217 *
218 * See ConnectPromptInfo for more details on possible authentication
219 * credentials.
220 *
221 * If the connection request is accepted, true is returned. This does
222 * not mean the connection succeeded. If the connection succeeds, a
223 * state of connect will be received via the #StateCB method.
224 */
225 bool connect(
226 tstring host);
227
228#if defined(HOST_DATA_SUPPORTED)
229 bool connect(
230 const IHostData& host);
231#endif
232
233 bool connect(
234#if defined(HOST_DATA_SUPPORTED)
235 const IHostData& host,
236#else
237 tstring host,
238#endif
239 unsigned int origin);
240
241 /**
242 * Use this method to change selected group after initial connection
243 * request has been made and credentials were delivered.
244 *
245 * Depending on secure gateway configuratiion, call to this method may
246 * result in a new connection request and will update credentials
247 * required for the selected group. New credentials returned by the
248 * secure gateway are delivered via the #UserPromptCB method.
249 */
250 bool setNewTunnelGroup(const tstring & group);
251
252 /**
253 * Use this method to initiate a disconnect of the active VPN
254 * connection.
255 *
256 * An indication of VPN disconnect is received via the #StateCB
257 * method.
258 */
259 void disconnect();
260
261 /**
262 * Use this method to cancel the user authentication. VPN tunnel is not connected
263 * at the moment. This function is used to cancel SSO authentication.
264 *
265 * An indication of VPN disconnect is received via the #StateCB
266 * method.
267 */
268 void cancel();
269
270 /**
271 * This method triggers the retrieval of the current VPN state.
272 * After the client is conected to the VPN service via the #attach
273 * method, both the current state and any changes in state are
274 * automatically delivered to the client. In general, this method
275 * should not be needed.
276 *
277 * ::VPNState is delivered via #StateCB method.
278 */
279 void getState();
280
281
282 /**
283 * This method triggers the retrieval of the current VPN statistics.
284 * This allows an UI to notify the API that it is ready to receive
285 * statistics.
286 *
287 * ::VPNState is delivered via #StatsCB method.
288 */
289 void getStats();
290
291 /**
292 * This method resets current VPN statistics counters.
293 */
294 void resetStats();
295
296
297 /**
298 * This method activates the retrieval of VPN statistics and other
299 * related data. By default, VPNStats are automatically delivered
300 * via the method #StatsCB.
301 *
302 * If the #stopStats method is called to stop the delivery of
303 * statistics, this method can be called to resume delivery.
304 */
305 void startStats();
306
307
308 /**
309 * This method stops the delivery of VPN statistics and
310 * other related data. By default, VPNStats are automatically
311 * delivered. This method disables delivery.
312 *
313 * The method #startStats can be called to resume the delivery of
314 * statistics.
315 */
316 void stopStats();
317
318
319 /**
320 * This method directs where and how to export the statistics
321 */
322 void exportStats(const tstring &tstrFilePath);
323
324
325 /**
326 * Call this method after a #BannerCB has been received to indicate
327 * that the user response to the banner can now be read.
328 *
329 * \param bAccepted
330 * indicates if the user accepted or declined the banner.
331 */
332 void setBannerResponse(bool bAccepted);
333
334 /**
335 * Call this method after a #PreConnectReminderCB has been received
336 * to indicate that user has acknowledged pre-connect reminder message.
337 *
338 * NOTE : Ignoring the response from user (for example, closing the modal
339 * dialog instead of clicking OK button). Old AnyConnect client (v3.1)
340 * ignored the response too.
341 */
342 void setPreConnectReminderResponse();
343
344 /*
345 * Call this method after a #CertBlockedCB has been received to
346 * indicate the user's response to the blocked untrusted VPN server
347 * error message.
348 *
349 * \param bUnblock indicates if the user wants to disable the
350 * preference to block untrusted servers
351 */
352 void setCertBlockedResponse(bool bUnblock);
353
354 /*
355 * Call this method after a #CertWarningCB has been received to
356 * indicate the user's response to the server certificate error
357 * warning
358 *
359 * \param bConnect indicates user wants to connect anyways
360 * \param bImport inidicates user wants to permanently trust
361 * the VPN server. This would result in no future certificate
362 * error warning prompts. bImport is only valid if
363 * bConnect is true and bAllowImport is true when a CertWarningCB
364 * was given.
365 */
366 void setCertWarningResponse(bool bConnect, bool bImportCert);
367
368
369 /**
370 * Call this method to indicate that authentication credential
371 * requests values solicited by the #UserPromptCB method can now
372 * be read from the ConnectPromptInfo instance.
373 */
374 void UserSubmit();
375
376
377 /**
378 * Method for retrieving the currently available user preferences.
379 * This method returns a instance of the class PreferenceInfo. The class
380 * instance is a deep copy and therefore independent of any VPN API
381 * object instances. It contains a variable number of Preference class
382 * instance pointers. Each preference contains data identifying the
383 * specific preference, its current value, etc. For a list of all
384 * possible preferences see the PreferenceId enum in api.h. Note that
385 * some of these preferences are not available to the user.
386 *
387 * @see PreferenceInfo
388 */
389 std::shared_ptr<PreferenceInfo> getPreferences();
390
391 /**
392 * Method for retrieving the current number of available user preferences.
393 * This method provides an optimized means of determining if there are any available user
394 * preferences. An application may have no need to retrieve the user preferences if there are
395 * no user preferences available, and invoking getPreferences() incurs the cost of a deep
396 * copy of the internal PreferenceInfo class instance, possibly causing many memory
397 * allocations, even when there are no avaiable user preferences, which could result in poor
398 * user interface responsiveness.
399 *
400 * @see PreferenceInfo
401 */
402 unsigned int getPreferencesCount();
403
404 /**
405 * This method stores the current set values of the preferences to the
406 * preferences file(s). This method is a counterpart to the
407 * getPreferences() method.
408 */
409 bool savePreferences(const std::shared_ptr<PreferenceInfo>& spPreferenceInfo);
410
411 /**
412 * This is called from the credential dialog in the GUI to get the correct
413 * friendly name for the dialog title.
414 */
415 tstring getConnectHost();
416
417 /**
418 * This method sets the last VPN error seen during this connection
419 * attempt for reporting purposes. This VPN error should be cleared for
420 * each connection attempt.
421 */
422 void setLastVpnError(VPNError vpnError);
423
424
425 /**
426 * This method gets the last VPN error seen during this connection
427 * attempt for reporting purposes. This VPN error should be cleared for
428 * each connection attempt.
429 */
430 VPNError getLastVpnError();
431
432 /**
433 * This method indicates if a request to connect has been initiated and the SG is being
434 * contacted. Note: the connect request is not active while waiting for the user to enter
435 * credentials.
436 */
437 bool isConnectRequestActive();
438
439 private:
440
441 //
442 //
443 // Private Member Methods
444 //
445 //
446
447 // Prevent copying by declaring but not defining copy constructor and operator= methods.
448 //
449 ClientIfc(const ClientIfc& other);
450 ClientIfc& operator=(const ClientIfc& other);
451
452#if defined(VPNAPI_EVENT_NOTIFICATION_SUPPORTED)
453 virtual void EventNotificationInternalCB(
454 const std::shared_ptr<CEventNotificationTlv>& spEventNtfctnTlv);
455#endif
456
457 using ClientIfcBase::ClientIfcTransmigration;
458
459 //
460 //
461 // Private Member Data
462 //
463 //
464
465 ClientIfcData* const m_pClientIfcData;
466};
467
468#endif //_CLIENTIFC_
api.h
VPNError
VPNError
Definition api.h:589
OperatingMode
OperatingMode
Definition api.h:537
tstring
#define tstring
Definition api.h:35
ClientIfcBase::EventNotificationInternalCB
virtual void EventNotificationInternalCB(const std::shared_ptr< CEventNotificationTlv > &spEventNtfctnTlv)=0
ClientIfc::getPreferences
std::shared_ptr< PreferenceInfo > getPreferences()
ClientIfc::hasFullCapabilities
bool hasFullCapabilities()
ClientIfc::getDefaultHostName
tstring getDefaultHostName()
ClientIfc::getStats
void getStats()
ClientIfc::detach
void detach()
ClientIfc::setBannerResponse
void setBannerResponse(bool bAccepted)
ClientIfc::disconnect
void disconnect()
ClientIfc::isVPNServiceAvailable
bool isVPNServiceAvailable()
ClientIfc::savePreferences
bool savePreferences(const std::shared_ptr< PreferenceInfo > &spPreferenceInfo)
ClientIfc::getConnectHost
tstring getConnectHost()
ClientIfc::cancel
void cancel()
ClientIfc::isOperatingMode
bool isOperatingMode(OperatingMode opMode)
ClientIfc::ProcessEvents
void ProcessEvents()
ClientIfc::getHostNames
std::list< tstring > getHostNames()
ClientIfc::getPreferencesCount
unsigned int getPreferencesCount()
ClientIfc::setLastVpnError
void setLastVpnError(VPNError vpnError)
ClientIfc::resetStats
void resetStats()
ClientIfc::isAvailable
bool isAvailable()
ClientIfc::stopStats
void stopStats()
ClientIfc::getLastVpnError
VPNError getLastVpnError()
ClientIfc::exportStats
void exportStats(const tstring &tstrFilePath)
ClientIfc::getState
void getState()
ClientIfc::isConnected
bool isConnected(bool bSilent=false)
ClientIfc::attach
bool attach(ClientType clientType=ClientType_GUI, bool requestFullCapabilities=true, bool suppressAutoConnect=true)
ClientIfc::startStats
void startStats()
ClientIfc::connect
bool connect(tstring host)
ClientIfc::setNewTunnelGroup
bool setNewTunnelGroup(const tstring &group)
ClientIfc::setPreConnectReminderResponse
void setPreConnectReminderResponse()
ClientIfc::isConnectRequestActive
bool isConnectRequestActive()
ClientIfc::UserSubmit
void UserSubmit()