| AnyConnect Secure Mobility Client 5.1.16.194

ClientIfc.h
1 /**************************************************************************
2 * Copyright (c) 2006, 2022-2023, 2025 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 initiate a disconnect of the active VPN
263 * connection. This function consumes a VPNDisconnectReason to specify
264 * why the disconnect is occurring.
265 *
266 * An indication of VPN disconnect is received via the #StateCB
267 * method.
268 */
269 void disconnect(VPNDisconnectReason disconnectEvent);
270
271 /**
272 * Use this method to cancel the user authentication. VPN tunnel is not connected
273 * at the moment. This function is used to cancel SSO authentication.
274 *
275 * An indication of VPN disconnect is received via the #StateCB
276 * method.
277 */
278 void cancel();
279
280 /**
281 * This method triggers the retrieval of the current VPN state.
282 * After the client is conected to the VPN service via the #attach
283 * method, both the current state and any changes in state are
284 * automatically delivered to the client. In general, this method
285 * should not be needed.
286 *
287 * ::VPNState is delivered via #StateCB method.
288 */
289 void getState();
290
291
292 /**
293 * This method triggers the retrieval of the current VPN statistics.
294 * This allows an UI to notify the API that it is ready to receive
295 * statistics.
296 *
297 * ::VPNState is delivered via #StatsCB method.
298 */
299 void getStats();
300
301 /**
302 * This method resets current VPN statistics counters.
303 */
304 void resetStats();
305
306
307 /**
308 * This method activates the retrieval of VPN statistics and other
309 * related data. By default, VPNStats are automatically delivered
310 * via the method #StatsCB.
311 *
312 * If the #stopStats method is called to stop the delivery of
313 * statistics, this method can be called to resume delivery.
314 */
315 void startStats();
316
317
318 /**
319 * This method stops the delivery of VPN statistics and
320 * other related data. By default, VPNStats are automatically
321 * delivered. This method disables delivery.
322 *
323 * The method #startStats can be called to resume the delivery of
324 * statistics.
325 */
326 void stopStats();
327
328
329 /**
330 * This method directs where and how to export the statistics
331 */
332 void exportStats(const tstring &tstrFilePath);
333
334
335 /**
336 * Call this method after a #BannerCB has been received to indicate
337 * that the user response to the banner can now be read.
338 *
339 * \param bAccepted
340 * indicates if the user accepted or declined the banner.
341 */
342 void setBannerResponse(bool bAccepted);
343
344 /**
345 * Call this method after a #PreConnectReminderCB has been received
346 * to indicate that user has acknowledged pre-connect reminder message.
347 *
348 * NOTE : Ignoring the response from user (for example, closing the modal
349 * dialog instead of clicking OK button). Old AnyConnect client (v3.1)
350 * ignored the response too.
351 */
352 void setPreConnectReminderResponse();
353
354 /*
355 * Call this method after a #CertBlockedCB has been received to
356 * indicate the user's response to the blocked untrusted VPN server
357 * error message.
358 *
359 * \param bUnblock indicates if the user wants to disable the
360 * preference to block untrusted servers
361 */
362 void setCertBlockedResponse(bool bUnblock);
363
364 /*
365 * Call this method after a #CertWarningCB has been received to
366 * indicate the user's response to the server certificate error
367 * warning
368 *
369 * \param bConnect indicates user wants to connect anyways
370 * \param bImport inidicates user wants to permanently trust
371 * the VPN server. This would result in no future certificate
372 * error warning prompts. bImport is only valid if
373 * bConnect is true and bAllowImport is true when a CertWarningCB
374 * was given.
375 */
376 void setCertWarningResponse(bool bConnect, bool bImportCert);
377
378
379 /**
380 * Call this method to indicate that authentication credential
381 * requests values solicited by the #UserPromptCB method can now
382 * be read from the ConnectPromptInfo instance.
383 */
384 void UserSubmit();
385
386
387 /**
388 * Method for retrieving the currently available user preferences.
389 * This method returns a instance of the class PreferenceInfo. The class
390 * instance is a deep copy and therefore independent of any VPN API
391 * object instances. It contains a variable number of Preference class
392 * instance pointers. Each preference contains data identifying the
393 * specific preference, its current value, etc. For a list of all
394 * possible preferences see the PreferenceId enum in api.h. Note that
395 * some of these preferences are not available to the user.
396 *
397 * @see PreferenceInfo
398 */
399 std::shared_ptr<PreferenceInfo> getPreferences();
400
401 /**
402 * Method for retrieving the current number of available user preferences.
403 * This method provides an optimized means of determining if there are any available user
404 * preferences. An application may have no need to retrieve the user preferences if there are
405 * no user preferences available, and invoking getPreferences() incurs the cost of a deep
406 * copy of the internal PreferenceInfo class instance, possibly causing many memory
407 * allocations, even when there are no avaiable user preferences, which could result in poor
408 * user interface responsiveness.
409 *
410 * @see PreferenceInfo
411 */
412 unsigned int getPreferencesCount();
413
414 /**
415 * This method stores the current set values of the preferences to the
416 * preferences file(s). This method is a counterpart to the
417 * getPreferences() method.
418 */
419 bool savePreferences(const std::shared_ptr<PreferenceInfo>& spPreferenceInfo);
420
421 /**
422 * This is called from the credential dialog in the GUI to get the correct
423 * friendly name for the dialog title.
424 */
425 tstring getConnectHost();
426
427 /**
428 * This method sets the last VPN error seen during this connection
429 * attempt for reporting purposes. This VPN error should be cleared for
430 * each connection attempt.
431 */
432 void setLastVpnError(VPNError vpnError);
433
434
435 /**
436 * This method gets the last VPN error seen during this connection
437 * attempt for reporting purposes. This VPN error should be cleared for
438 * each connection attempt.
439 */
440 VPNError getLastVpnError();
441
442 /**
443 * This method indicates if a request to connect has been initiated and the SG is being
444 * contacted. Note: the connect request is not active while waiting for the user to enter
445 * credentials.
446 */
447 bool isConnectRequestActive();
448
449 private:
450
451 //
452 //
453 // Private Member Methods
454 //
455 //
456
457 // Prevent copying by declaring but not defining copy constructor and operator= methods.
458 //
459 ClientIfc(const ClientIfc& other);
460 ClientIfc& operator=(const ClientIfc& other);
461
462 #if defined(VPNAPI_EVENT_NOTIFICATION_SUPPORTED)
463 virtual void EventNotificationInternalCB(
464 const std::shared_ptr<CEventNotificationTlv>& spEventNtfctnTlv);
465 #endif
466
467 using ClientIfcBase::ClientIfcTransmigration;
468
469 //
470 //
471 // Private Member Data
472 //
473 //
474
475 ClientIfcData* const m_pClientIfcData;
476 };
477
478 #endif //_CLIENTIFC_
api.h
VPNDisconnectReason
VPNDisconnectReason
Definition: api.h:188
ClientIfcBase
Definition: ClientIfcBase.h:63
tstring
#define tstring
Definition: api.h:35
ClientIfc
Definition: ClientIfc.h:42
OperatingMode
OperatingMode
Definition: api.h:545
VPNError
VPNError
Definition: api.h:597