AnyConnect Secure Mobility Client  4.10.08029
ClientIfc.h
1 /**************************************************************************
2 * Copyright (c) 2006, Cisco Systems, All Rights Reserved
3 ***************************************************************************
4 *
5 * File: ClientIfc.h
6 * Date: 11/2006
7 *
8 ***************************************************************************
9 *
10 * Client Interface class implementation for the Client API.
11 *
12 ***************************************************************************/
13 
14 #ifndef _CLIENTIFC_
15 #define _CLIENTIFC_
16 
17 
18 /**
19 * This is the main interface class for applications that implement the
20 * Cisco AnyConnect Secure Mobility VPN API. A program wishing to use the API must create a
21 * class that extends the ClientIfc class. This new class is required to
22 * provide implementations for the pure virtual methods found in the protected
23 * section (for example, StatsCB).
24 *
25 * Finally, the public section contains methods that are available for
26 * managing the API. These include methods like attach and connect.
27 *
28 * A client must implement the CB (abstract) methods found in the protected
29 * section of this interface.
30 *
31 */
32 
33 
34 
35 #include "api.h"
36 #include "ClientIfcBase.h"
37 #include "VPNStats.h"
38 #include "ConnectPromptInfo.h"
39 #include "Preference.h"
40 #include "PreferenceInfo.h"
41 
42 class VPN_VPNAPI ClientIfc : protected ClientIfcBase
43 {
44  protected:
45 
46  /**
47  * Callback used to deliver new statistics related to the VPN
48  * connection.
49  *
50  * When a connection is active, a new set of statistics is
51  * delivered each second.
52  *
53  * @see resetStats(), stopStats() and startStats()
54  *
55  */
56  virtual void StatsCB(VPNStats &stats) = 0;
57 
58 
59  /**
60  * Callback used to deliver VPN state and state change string.
61  * The stateString delivered by this method is localized.
62  *
63  * See the ::VPNState enum found in api.h for set of valid states.
64  */
65  virtual void StateCB(const VPNState state,
66  const VPNSubState subState,
67  const tstring stateString) = 0;
68 
69 
70  /**
71  * If a banner needs to be acknowledged, this CB delivers the banner
72  * to the client.
73  *
74  * NOTE: Connection establishment will block until the method
75  * setBannerResponse() is called.
76  *
77  * In a GUI, a banner would typically be displayed in a modal dialog
78  * with an accept or decline button selection.
79  *
80  * @see setBannerResponse() to set the user response to the banner.
81  */
82  virtual void BannerCB(const tstring &banner) = 0;
83 
84  /**
85  * If a pre-connect reminder needs to be acknowledged, this CB delivers
86  * the pre-connect reminder to the client.
87  *
88  * NOTE: Connection establishment will block until the method
89  * setPreConnectReminderResponse() is called.
90  *
91  * In a GUI, a pre-connect reminder would typically be displayed in a modal
92  * dialog with an OK button selection.
93  *
94  * @see setPreConnectReminderResponse() to set the user acknowledgement to
95  * the pre-connect reminder message.
96  */
97  virtual void PreConnectReminderCB(const tstring &rtstrPreConnectReminder);
98 
99  /**
100  * Messages are delivered via the NoticeCB and can come from multiple
101  * sources. There are four message types (error, warning, info and
102  * status). See the ::MessageType enum in api.h for the list.
103  *
104  * Clients using the API as an embedded application (not
105  * user visible) might want to further characterize
106  * messages. One option here is to use the AnyConnect message
107  * catalog and assign message codes as the translations for
108  * various messages. An application could then track messages based
109  * on its own error code scheme.
110  */
111  virtual void NoticeCB(const tstring &notice,
112  const MessageType type,
113  const bool bSensitive = false) = 0;
114 
115 
116  /**
117  * This CB would likely occur only during a connection when it was
118  * detected that the software needed to be upgraded, or when Start
119  * Before Logon (SBL) is being used.
120  *
121  * Unlike the other callback methods, this method provides a default
122  * implementation (calling the system's exit() function).
123  * If clients of the API wish to override this behavior, they are
124  * responsible for ensuring that the current running process exits with
125  * the return code specified by returnCode.
126  *
127  * <b>Caution</b>: IF YOU OVERRIDE THIS METHOD AND DO NOT EXIT WITH
128  * THE PROPER CODE SOFTWARE UPDATE FUNCTIONALITY IN YOUR CLIENT WILL
129  * BREAK
130  */
131  virtual void ExitNoticeCB(const tstring &tstrNotice,
132  const int returnCode);
133 
134 
135  /**
136  * Under normal operating conditions, this CB is called as soon
137  * as the attach method completes. In case the service (vpn agent)
138  * is not ready, this CB is not called until it is.
139  *
140  * Any API calls made prior to this CB being called will result in a
141  * NoticeCB error message.
142  */
143  virtual void ServiceReadyCB() = 0;
144 
145 
146 
147  /**
148  * This method supports prompting for single or multiple values. All
149  * prompts are considered mandatory.
150  *
151  * The ConnectPromptInfo object contains a list of PromptEntry
152  * instances. The labels and their default values (if any) can be
153  * found in these instances. After the data has been collected from the user
154  * it can be set into these same instances. When ready, the client
155  * application should call the method UserSubmit() to have the
156  * responses read by the API.
157  */
158  virtual void UserPromptCB(ConnectPromptInfo &ConnectPrompt) = 0;
159 
160 
161  /**
162  * Use this method to provide Window Manager hints to GUI
163  * applications. To receive these hints, the application must
164  * identify itself as a GUI in the attach method. In addition, this
165  * method should be overriden to receive any generated events.
166  *
167  * Event that can be received include those indicating that a user is
168  * starting a second instance of the GUI application. This information
169  * can be used to tell the already running application to un-minimize
170  * itself and let the new program know that it should Quit (since a GUI
171  * is already running).
172  */
173  virtual void WMHintCB(const WMHint hint,
174  const WMHintReason reason);
175 
176 
177  /**
178  * This method is useful when the connection to the secure gateway
179  * has been established as part of a web-launch of the VPN tunnel.
180  *
181  * If the client application wishes to be notified of the secure
182  * gateway to which the VPN has been established, this method should
183  * be overriden.
184  *
185  * If the client application is started and a tunnel is already active,
186  * this method also delivers the name of the secure gateway host.
187  */
188  virtual void deliverWebLaunchHostCB(const tstring &activeHost);
189 
190  /**
191  * This method is called when the preference to block untrusted
192  * servers is enabled and the current VPN server being connected
193  * to is untrusted. Clients should present an error to the user
194  * notifying them that the current connection to rtstrUntrustedServer
195  * is being blocked. The client should also provide a way for the
196  * user to change the preference to block untrusted servers.
197  *
198  * The user response must be indicated using setCertBlockedResponse
199  */
200  virtual void CertBlockedCB(const tstring &rtstrUntrustedServer) = 0;
201 
202  /**
203  * This method is called when connections to untrusted VPN servers
204  * is allowed by policies and the current VPN server being connected
205  * to is untrusted. Clients should present a warning to the user
206  * notifying them that the current connection to rtstrUntrustedServer
207  * is unsafe. The reason the VPN server is untrusted is provided in
208  * rltstrCertErrors. The client should provide a way for the user to
209  * connect once, connect and always trust or cancel the connection.
210  * If bAllowImport is set to false then the always trust option should
211  * not be presented to users.
212  *
213  * The user response must be indicated using setCertWarningResponse
214  */
215  virtual void CertWarningCB(const tstring &rtstrUntrustedServer,
216  const std::list<tstring> &rltstrCertErrors,
217  bool bAllowImport) = 0;
218 
219  /**
220  * This method should be overriden by the client application to
221  * exercise some control over the delivery of events from the other
222  * protected methods in this class.
223  *
224  * This might be necessary in cases where a GUI/CLI is being written and
225  * the data from this API needs to be delivered in the GUI/CLI or main
226  * thread. In this case, you should override this method and when it
227  * is called by the API post an event to your event queue (message
228  * pump, etc.). After this event executes in your GUI/CLI or main thread,
229  * call the method ClientIfc::ProcessEvents to have events delivered
230  * to your client application.
231  */
232  virtual void EventAvailable();
233 
234 
235  ClientIfc();
236 
237 
238  public:
239 
240  /**
241  * After the ClientIfc class has been created, the client implementation
242  * must invoke this method prior to attempting connections,
243  * retrieving statistics, etc. If successful, this method returns
244  * true. If not successful, it returns false and returns a notice error
245  * message to the user.
246  *
247  * A single call to this method is all that is necessary. If the
248  * attach fails, a message indicating the VPN service is not available
249  * is returned. If the call succeeds, the ServiceReadyCB is
250  * called and true is returned.
251  *
252  * \param ClientType clientType (default ClientType_GUI)
253  * Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT.
254  * ClientType_GUI: indicates that the started program is a GUI
255  * application. With this attribute set to true, the application will
256  * now receive WMHints.
257  * ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation
258  * where a GUI can be launched prior to the normal windows logon sequence.
259  * This allows a VPN tunnel to be activated and used as part of the windows
260  * logon sequence. This value is applicable only when a corresponding
261  * argument has been passed to the program by the VPN agent.
262  * ClientType_CLI: indicates that the started program is a CLI application.
263  * ClientType_MGMT: indicates that the started program is used to initiate
264  * an AnyConnect management VPN tunnel. This value is
265  * applicable only to a client launched by AnyConnect VPN agent.
266  *
267  * \param requestFullCapabilities indicates that the client program is
268  * requesting full API capabilities. Full capabilities allows the
269  * client program to connect, disconnect, receive statistics, etc.
270  * When full capabilities are not requested or not available, the
271  * client program will not be able to establish new VPN connections.
272  * Only a client program with full capabilites can do this. In
273  * addition, only the first program requesting full capabilities will
274  * be granted this level of access. The attach method can succeed
275  * even if full capabilities is requested but not granted. To test
276  * for this state, use the method ::hasFullCapabilities.
277  *
278  * \param suppressAutoConnect indicates that the client wishes to
279  * override automatically initiating a connection to the last connected
280  * secure gateway at startup. Normally, this is determined by the
281  * value of the AutoConnectOnStart preference. If this flag is true
282  * then an automatic connection will never be initiated, even if
283  * AutoConnectOnStart is enabled.
284  */
285  bool attach(ClientType clientType = ClientType_GUI,
286  bool requestFullCapabilities = true,
287  bool suppressAutoConnect = true);
288 
289 
290  /**
291  * After the client program is done, call the detach method to do a
292  * graceful cleanup. This method stops the flow
293  * of events and does general cleanup.
294  */
295  void detach();
296 
297 
298  /**
299  * When the method ClientIfc::EventAvailable has been overriden in the
300  * client application, this method must be called to receive events.
301  *
302  * It is expected that GUI programs will use EventAvailable as a
303  * signal, allowing them to set an event using their native event
304  * handler. When that event fires, the application can call
305  * ProcessEvents, which causes the API to deliver events in the
306  * client's main thread.
307  */
308  virtual void ProcessEvents();
309 
310 
311  /**
312  * Use this method to determine whether this application has full
313  * capabilities. Only one application (the first one started) can have
314  * full capabilities. If this is the first application started, this
315  * method returns true. When an application has full capabilities,
316  * it can initiate connections, as well as offer UI capabilities.
317  */
318  bool hasFullCapabilities();
319 
320 
321  /**
322  * This method returns true if the client has an active VPN
323  * connection with a secure gateway.
324  */
325  bool isConnected();
326 
327 
328  /**
329  * This method returns true if the client VPN is available for use.
330  * If false is returned this means that VPN has been intentionally
331  * disabled. This would indicate a situation where other AnyConnect
332  * services were in use but not VPN.
333  */
334  bool isAvailable();
335 
336 
337  /**
338  * This method returns true if the VPN service is available for
339  * establishing VPN connections.
340  */
341  bool isVPNServiceAvailable();
342 
343 
344  /**
345  * This method returns true if the mode in which the client is
346  * currently operating is enabled. For a list of all possible modes
347  * of operation see the ::OperatingMode enum in api.h.
348  */
349  bool isOperatingMode(OperatingMode opMode);
350 
351  /**
352  * This method returns a list of secure gateway host names found in an
353  * AnyConnect profile. If no profile is available, an empty
354  * list is returned.
355  */
356  std::list<tstring> getHostNames();
357 
358 
359  /**
360  * This method returns any default Host name from User Preferences.
361  *
362  * A host can be returned here even if there are no profiles on the
363  * system. The host last connected to (via the connect method) is
364  * returned by this method.
365  *
366  * If there is no previously connected-to host, the first host found
367  * in an AnyConnect profile (if any) is returned.
368  */
369  tstring getDefaultHostName();
370 
371 
372  using ClientIfcBase::connect;
373  /**
374  * This method initiates a connection to the specified host.
375  * The connection results in the presentation of authentication
376  * credentials, as appropriate. Any credentials returned by the secure
377  * gateway are delivered via the #UserPromptCB method.
378  *
379  * See ConnectPromptInfo for more details on possible authentication
380  * credentials.
381  *
382  * If the connection request is accepted, true is returned. This does
383  * not mean the connection succeeded. If the connection succeeds, a
384  * state of connect will be received via the #StateCB method.
385  */
386  bool connect(tstring host);
387 
388  /**
389  * Use this method to change selected group after initial connection
390  * request has been made and credentials were delivered.
391  *
392  * Depending on secure gateway configuratiion, call to this method may
393  * result in a new connection request and will update credentials
394  * required for the selected group. New credentials returned by the
395  * secure gateway are delivered via the #UserPromptCB method.
396  */
397  virtual bool setNewTunnelGroup(const tstring & group);
398 
399  /**
400  * Use this method to initiate a disconnect of the active VPN
401  * connection.
402  *
403  * An indication of VPN disconnect is received via the #StateCB
404  * method.
405  */
406  void disconnect();
407 
408  /**
409  * Use this method to cancel the user authentication. VPN tunnel is not connected
410  * at the moment. This function is used to cancel SSO authentication.
411  *
412  * An indication of VPN disconnect is received via the #StateCB
413  * method.
414  */
415  void cancel();
416 
417  /**
418  * This method triggers the retrieval of the current VPN state.
419  * After the client is conected to the VPN service via the #attach
420  * method, both the current state and any changes in state are
421  * automatically delivered to the client. In general, this method
422  * should not be needed.
423  *
424  * ::VPNState is delivered via #StateCB method.
425  */
426  void getState();
427 
428 
429  /**
430  * This method triggers the retrieval of the current VPN statistics.
431  * This allows an UI to notify the API that it is ready to receive
432  * statistics.
433  *
434  * ::VPNState is delivered via #StatsCB method.
435  */
436  void getStats();
437 
438  /**
439  * This method resets current VPN statistics counters.
440  */
441  void resetStats();
442 
443 
444  /**
445  * This method activates the retrieval of VPN statistics and other
446  * related data. By default, VPNStats are automatically delivered
447  * via the method #StatsCB.
448  *
449  * If the #stopStats method is called to stop the delivery of
450  * statistics, this method can be called to resume delivery.
451  */
452  void startStats();
453 
454 
455  /**
456  * This method stops the delivery of VPN statistics and
457  * other related data. By default, VPNStats are automatically
458  * delivered. This method disables delivery.
459  *
460  * The method #startStats can be called to resume the delivery of
461  * statistics.
462  */
463  void stopStats();
464 
465 
466  /**
467  * This method directs where and how to export the statistics
468  */
469  void exportStats(const tstring &tstrFilePath);
470 
471 
472  /**
473  * Call this method after a #BannerCB has been received to indicate
474  * that the user response to the banner can now be read.
475  *
476  * \param bAccepted
477  * indicates if the user accepted or declined the banner.
478  */
479  void setBannerResponse(bool bAccepted);
480 
481  /**
482  * Call this method after a #PreConnectReminderCB has been received
483  * to indicate that user has acknowledged pre-connect reminder message.
484  *
485  * NOTE : Ignoring the response from user (for example, closing the modal
486  * dialog instead of clicking OK button). Old AnyConnect client (v3.1)
487  * ignored the response too.
488  */
489  void setPreConnectReminderResponse();
490 
491  /*
492  * Call this method after a #CertBlockedCB has been received to
493  * indicate the user's response to the blocked untrusted VPN server
494  * error message.
495  *
496  * \param bUnblock indicates if the user wants to disable the
497  * preference to block untrusted servers
498  */
499  void setCertBlockedResponse(bool bUnblock);
500 
501  /*
502  * Call this method after a #CertWarningCB has been received to
503  * indicate the user's response to the server certificate error
504  * warning
505  *
506  * \param bConnect indicates user wants to connect anyways
507  * \param bImport inidicates user wants to permanently trust
508  * the VPN server. This would result in no future certificate
509  * error warning prompts. bImport is only valid if
510  * bConnect is true and bAllowImport is true when a CertWarningCB
511  * was given.
512  */
513  void setCertWarningResponse(bool bConnect, bool bImportCert);
514 
515 
516  /**
517  * Call this method to indicate that authentication credential
518  * requests values solicited by the #UserPromptCB method can now
519  * be read from the ConnectPromptInfo instance.
520  */
521  void UserSubmit();
522 
523 
524  /**
525  * Method for retrieving the currently available user preferences.
526  * This method returns an instance of the class PreferenceInfo. The
527  * instance contains a variable number of Preference object pointers.
528  * Each preference contains data identifying the specific preference,
529  * its current value, etc. For a list of all possible preferences see
530  * the ::PreferenceId enum in api.h. Note that some of these
531  * preferences are not available to the user.
532  *
533  * @see PreferenceInfo
534  */
535  PreferenceInfo &getPreferences();
536 
537 
538  /**
539  * This method stores the current set values of the preferences to the
540  * preferences file(s). This method is a counterpart to the
541  * getPreferences() method.
542  */
543  bool savePreferences();
544 
545  /**
546  * This is called from the credential dialog in the GUI to get the correct
547  * friendly name for the dialog title.
548  */
549  tstring getConnectHost();
550 
551  /**
552  * This method sets the last VPN error seen during this connection
553  * attempt for reporting purposes. This VPN error should be cleared for
554  * each connection attempt.
555  */
556  void setLastVpnError(VPNError vpnError);
557 
558 
559  /**
560  * This method gets the last VPN error seen during this connection
561  * attempt for reporting purposes. This VPN error should be cleared for
562  * each connection attempt.
563  */
564  VPNError getLastVpnError();
565 
566  virtual ~ClientIfc();
567 
568  private:
569 
570  ClientIfc(const ClientIfc& other);
571  ClientIfc& operator=(const ClientIfc& other);
572 
573 };
574 
575 #endif //_CLIENTIFC_
Definition: PreferenceInfo.h:27
virtual void BannerCB(const tstring &banner)=0
virtual void StatsCB(VPNStats &stats)=0
virtual void NoticeCB(const tstring &notice, const MessageType type, const bool bSensitive=false)=0
WMHintReason
Definition: api.h:200
virtual void StateCB(const VPNState state, const VPNSubState subState, const tstring stateString)=0
VPNState
Definition: api.h:135
Definition: ClientIfcBase.h:163
#define tstring
Definition: api.h:35
WMHint
Definition: api.h:181
Definition: ConnectPromptInfo.h:37
MessageType
Definition: api.h:104
virtual void CertBlockedCB(const tstring &rtstrUntrustedServer)=0
virtual void ExitNoticeCB(const tstring &tstrNotice, const int returnCode)
virtual void deliverWebLaunchHostCB(const tstring &activeHost)
Definition: ClientIfc.h:42
OperatingMode
Definition: api.h:522
virtual void PreConnectReminderCB(const tstring &rtstrPreConnectReminder)
VPNSubState
Definition: api.h:159
virtual void CertWarningCB(const tstring &rtstrUntrustedServer, const std::list< tstring > &rltstrCertErrors, bool bAllowImport)=0
VPNError
Definition: api.h:574
Definition: VPNStats.h:35
virtual void WMHintCB(const WMHint hint, const WMHintReason reason)
virtual void ServiceReadyCB()=0
virtual void EventAvailable()
virtual void UserPromptCB(ConnectPromptInfo &ConnectPrompt)=0