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