/*! \mainpage AnyConnect VPN Client C++ API

\section pref_sec Preface

The starting point for developing a client using the AnyConnect API is 
the file ClientIfc.  This file contains a series of protected methods most of
which must be implemented by the client developer.

The public methods are available to the client developer based on data needed by their applicaiton or actions they want executed.
A typical implementation is to call the attach method.  Once this
completes successfully, the connect method can be called.  On subsequent
connections, the connect method happens automatically as the last host visited
is automatically contacted when the client is started.

After a gateway has been contacted, the method UserPromptCB is called.
This method delivers an instance of the object ConnectPromptInfo, which contains
user messages and any authentication prompt requests.
After setting the desired data, the client developer can call UserSubmit
to have the credentials delivered to the Gateway.  There is also a method of
authentication called certificate-only.  If this mechanism of authentication
is used, there are no calls to UserPromptCB.  Instead, the StateCB method
is called, letting the user know that the VPN is Connected.

In the documentation for the ClientIfc interface, some of the methods have a reference "Implemented in ClientImpl".  Follow these links to see code snippets that show details of how to interact with data used in the API.


\section intro_sec Introduction

The following documentation details the AnyConnect VPN Client C++
API.  The documentation consists of two demo programs which show
usage of the API functionality.  For additional information on
how to use the API, read the documentation provdied and browse the Class
hierarchy.

*/

//------ Building the client ---------------

/*! \page build_sec Building an AnyConnect client
The API bundle contains the libraries, project files, and build scripts required to build the included examples.

At this time, the supported platforms include those supported in the current release of AnyConnect.  These include Windows platforms, MAC (PPC and Intel) and Linux.  Look in the example directory for test programs.  Also, see the Examples section on the "Advanced Topics" page with this documentation.

\section win_sec Windows
There are several issues with the API and integrating it into your client application on a Windows platform when using the static libraries.  One issue to be aware of is the version of Visual Studio currently supported.  To interact with the installed VpnApi.dll directly, please see the COM API documentation.

\subsection vs_sec Visual Studio
On Windows, the static libs provided require the client implementor
to build using VS2005 in conjunction with Service pack 1.

For more information about this service pack, see http://support.microsoft.com/kb/926601

You may be able to initiate a download of this service pack from http://msdn2.microsoft.com/en-us/express/aa975050.aspx

\subsection dll_sec AnyConnect VpnApi dll
The dlls that come with AnyConnect installation are not suitable for use in programs built with the API.  As of 2.3, a COM API is available to interact with the installed VpnApi.dll directly.  Please see the COM API documentation for more information.

\subsection vs_debug Debugging
Another issue when building your test client with the AnyConnect provided
static libs has to do with the type of build.  As debug builds are not shipped
with the AnyConnect bundle, you will only be able to do <i>Release</i> builds.

This will not prevent you from debugging your code, it will just keep you from
inspecting the AnyConnect internals.  To debug your client implementation 
it is required that the pdb file reside in the same directory as the
executable you are trying to debug.

For example, if your executable is
vpnui.exe you will need to have the file vpnui.pdb in the directory with
vpnui.exe when you run vpnui.exe in the debugger.

\subsection wide_sec Wide Character Support 
The API is available on Windows in wide string format only.  This means
code using the API must also be built for Unicode support.   On non-Windows
platforms, the API is not built for wide-string support.  The API 
still handles multibyte languages in this format.

\section mac_sec MAC and Linux
The required libraries and header files needed for MAC (PowerPC and Intel)
and Linux integration with the API are available in this bundle.  The CLI
example (example/CLI) contains build command examples for Linux and MAC
PowerPC platforms.

The AnyConnect libraries are build with gcc version 4.0.0 on Linux and
version 4.0.1 for MAC platforms.

Note: The non-Windows build scripts assume that AnyConnect is already installed.

*/

//------ Basic Capabilities ---------------

/*! \page basic_cap_pag Basic Capabilities

\section bas_sec Managing the VPN
There are several methods that provide the application developer with a means to manage and integrate with the VPN.  The following methods detail functionality enableing the connection and disconnection of VPN, the collection of statisitics, the monitoring of VPN state and the display f user messages.


\subsection connect_sub Connect
The ClientIfc::connect(tstring host) method will initiate a connection to the specified host.
The connection will result in the presentation of authentication
credentials as appropriate.  Any credentials returned by the secure
gateway will be delivered via the ClientIfc::UserPromptCB method.

See ConnectPromptInfo for more details on possible authentication credentials.

If the connection request is accepted, true is returned.  This does
not mean connection will succeed.  If the conneciton succeeds, a
state of VPNState::CONNECTED will be recieved via the ClientIfc::StateCB method.


\subsection disconnect_sub Disconnect
The ClientIfc::disconnect method can be used to innitiate a disconnect of the active VPN connection.

Indication of VPN disconnect will be received via the ClientIfc::StateCB method.


\subsection stats_sub Statistics
Statistics for the currently active VPN are delivered via the callback ClientIfc::StatsCB.

When a connection is active, a new set of statisitcs will be delivered each second.

The following methods allow for some control over the flow of VPN statisitics.  As a default, statisitcs will be sent once a VPN is connected.
@see ClientIfc::resetStats(), ClientIfc::stopStats() and ClientIfc::startStats()


\subsection state_sub State Changes
VPN state changes will be delivered via the Callback ClientIfc::StateCB(VPNState state, tstring stateString).
The stateString delivered by this method will be localized.

See the ::VPNState enum found in api.h for set of valid states.


\subsection notices_sub Notices
User Messages are delivered via the NoticeCB and can come from multiple
sources.  There are 4 message types (error, warning, info and
status).  See the ::MessageType enum in api.h for the list.

For clients using the API as an embedded application (not
user visible) there may be a desire to further characterize
messages.  One option here is to use the AnyConnect message
catalog and assign message codes as the translations for
various messages.  An application could then track messages based
on it's own error code scheme.


\section act_sec Activating the API
\subsection attach_sub Attach Method
Once the client application has creted an instance of it's extension of the ClientIfc
class the attach method should be invoked.
This must be done prior to attempting connections,
retrieving statistics, etc.  If successful, this method will return
true.  If not successful false will be returned and a notice error
message returned to the user (via ClientIfc::NoticeCB).

See the method ClientIfc::attach for additional information regarding the arguments available with the attach method.

Some of the embedded functionality in the API manages the existence of multiple GUIs.
For example, if a GUI is running on the client machine, and the user tries to start
another one, instead of the second instance starting, a message is sent to the
first GUI to Open (WMHint::OPEN), and the second instance will have it's ClientIfc::ExitNoticeCB
method called.
If a second instance of a client program is started, and it is not identified as a GUI, then no attempt is made to close it.

Note: If a second application utilizing the API is started when another is already running, only the first application is allowed to start VPN connections.

\subsection detach_sub Detach Method
Once the client program is done and wishes to do a graceful cleanup,
the detach method should be called.  This method will stop the flow
of events and do general cleanup.  Once this method is called the ClientIfc instance is no longer useful.  The attach method will not make the instance useable again.

\subsection svc_rdy_sub ServiceReadyCB Method
Under normal operating conditions, this CB will be called as soon
as the attach method completes.  In case the service (vpn agent)
is not ready, this CB will not be called until it is.

Any API calls made prior to this CB being called will result in a
NoticeCB error message.

\section cert_sel_sec Certificate Selection
The API will automatically perform certificate selection.  There are some aspects of
this selection that can be controlled with attributes found in an AnyConnect profile.  
Those include certificate match options found in the CertificateMatch section of the
profile as well as certificate store selection options that can be configured with the
CertificateStore attribute.

\section cert_imp_sec Certificate Import
The API can be used to automatically import certificates that have been made available
by an administrator.  If the gateway being contacted has a Certificate Authority
enabled, the API will inform the application of this by returning true when the method
ConnectPromptInfo::hasEnrollmentCA is called.  This method can be called when a
ConnectPromptInfo instance is delivered via the ClientIfc::UserPromptCB method.

If the application wishes to have a certificate imported, the method
ConnectPromptInfo::setUseEnrollmentCA should be called with an argument of true prior
to calling ClientIfc::UserSubmit.

This will cause an updated ConnectPromptInfo instance to be delivered to the client
application.  This instance will contain authentication prompts required for
retrieving and importing the cleint certificate.

For additional details on Certificate match and Certificate store capabilities, see the AnyConnect Release notes.

\section csd_sec CSD Integration
The Cisco Secure Desktop application is integrated into the AnyConnect API.  This
means that if the CSD application and any DAP rules are enabled by an Administrator,
they will control the ability of a user to initiate a VPN tunnel.

*/

//------ API Interface ---------------

/*! \page api_files_sec The API Interface
- \subpage evt_sub Event Models
- \subpage req_sub Required Implementation
- \subpage bas_sub General API Methods

*/

/*! \page evt_sub Event Models
The use of two methods ClientIfc::EventAvailable and ClientIfc:ProcessEvents by the client program dictates how data is to be delivered.  For purposes of description, we will refer to the two delivery methods as the CLI versus the GUI method.  The example programs provided include a CLI and a GUI program, each using the event model described here but in a slightly different manner.  No matter which method is used, data delivery is through the same methods described in the API (for example, NoticeCB, UserPromptCB, etc.).  The difference is essentially one where the client program asks for the latest events, versus an implementation where the events are delivered as they occur.

Different types of programs require different event models.  For example, GUI programs will likely require the client program to request events when they are available.  Other programs like command line or service implementations could use the model where events are delivered as they occur.

The AnyConnect API detects the model in use based on the client programs implementation of the method ClientIfc::EventAvailable().  If the client program has implemented this virtual method, then it is called when new data is available for the client program.  Then, it is up to the client program to schedule an event, the firing of which calls the method ClientIfc::ProcessEvents().

A sample GUI program containing the implementation of this method can be found in the files GUIClientImpl.cpp and MainDialog.cpp.  The flow can be traced from the method GUIClientImpl::EventAvailable().

The reason for offering this type of event processing is that GUI programs typically require that GUI objects be managed (created or manipulated) from the program's main thread.  The assumption here is that the various callback methods (for example, UserPromptCB) are used to manipulate the GUI program.  For example, with the AnyConnect GUI, widgets are created dynamically.  This includes the Group selection combo box, as well as the Username and Password input fields.  Because of this, the AnyConnect GUI directly uses the event model.  This is in contrast to the implementation found in the CLI example CLIClientImpl.cpp.  This example makes no use of the EventAvailable method and therefore is a passive user of the event model.  In the CLI case, events are delivered to the program as they occur.

*/

/*! \page req_sub Required Implementation
You must implement the following methods for integration with the AnyConnect API.

\section stats_sec StatsCB
The StatsCB method provides a mechanism for the periodic delivery of VPN statistics, protocol and route data as well as the current state of the VPN.  You can control or ignore the flow of this data as desired.  For additional information about the method, see ClientIfc::StatsCB.  To see an example of accessing the data delivered by this method, see CLIClientImpl::StatsCB and CLIClientImpl::getStats.

For a list of available statistics, see the <b>Static Public Attributes</b> section in the VPNStats class.

\subsection protocol_info_sec Protocol Data
The VPNStats class also provides access to Protocol and compression data.  This data can be accessed using the method VPNStats::getProtocolInfo.  As with the VPNStats class, see the <b>Static Public Attributes</b> section for data available from an instance of the ProtocolInfo class.

\subsection route_info_sec Route Data
Finally, the VPNStats class provides access to Route data.  There can be one or more instances of Secure and Non-Secure routes.  To retrieve this data, you can use the methods VPNStats::getSecureRoutes and VPNStats::getNonsecureRoutes.  See the class RouteInfo for methods that can be used to access the data in a Secure or Non-Secure RouteInfo instance.

\section state_sec StateCB
The StateCB method delivers the current state (see ::VPNState) and a localized string identifying that state textually.  This method is called when your application calls ClientIfc::attach and then each time the state changes.

\section banner_sec BannerCB
This method delivers important notices.  This method should return a true or false indicating <b>acceptance</b> or <b>rejection</b> of the notice.  If used, the BannerCB method is called during authentication.  If the response to a banner is false <b>rejection</b> the VPN connection attempt is terminated.  If the reponse is true, the VPN connection attempt continues.  Some examples of using banner include:
<list type="bullet">
<item>
When a server certificates from remote gateway is not recognized 
</item>
<item>
When an administrator has provisioned a banner on the gateway.  Once authentication is complete the banner is delivered.
</item>
</list>

\section notice_sec NoticeCB
Messages are delivered via the NoticeCB and can come from multiple sources.  There are four message types: error, warning, info and status.  See the ::MessageType enum in api.h for the list.

For clients using the API as an embedded application (not user visible) there may be a desire to further characterize messages.  One option here is to use the AnyConnect message catalog and assign message codes as the translations for various messages.  An application could then track messages based on it's own error code scheme and resulting desired remedial action.

\section svc_ready_sec ServiceReadyCB
Under normal operating conditions, this CB will be called as soon
as the ClientIfc::attach method completes.  In case the service (vpn agent)
is not ready, this CB is not called until either the service is ready, or the attempt fails.

Any API calls made prior to this CB being called result in a NoticeCB error message.

\section user_prompt_sec UserPromptCB
This method supports prompting for single or multiple values.  It is the mechanism for displaying and setting values that are required by the secure gateway for authentication.

The ConnectPromptInfo object contains a list of PromptEntry instances.  The labels and their default values (if any) can be found in this list.  After the data has been collected from the user, it can be set into these same instances.  When ready, the client application should call the method ClientIfc::UserSubmit to have the responses read by the API.

Two methods in the CLI example code demonstrate the delivery of ConnectPromptInfo, the parsing of PromptEntry and subsequent return of user entered values using the UserSubmit method.  See the methods CLIClientImpl::UserPromptCB and CLIClientImpl::setUserData.

*/

/*! \page bas_sub General API Methods
The following are categories of methods available to the API programmer.  The methods cover aspects of the API from connecting or disconnecting a VPN to managing statistics.

All of the methods can be found in the main API interface file, ClientIfc


- \subpage client_state_sub  These methods provide some basic capability for
determining the state of the client program.

- \subpage vpn_state_sub Provides a simple mechanism to check current state of VPN.

- \subpage external_exit_sub These requests are likely to occur only during connection attempts when special processing conditions exist. 

- \subpage sg_hosts_sub These are methods for accessing Secure Gateway Names.

- \subpage manage_vpns_sub These methods provide simple mechanisms to control VPN connection.

- \subpage stats_manage_sub These methods allow for some control over statistics being delivered to a client program.

*/

/*! \page client_state_sub Client State Checking

\section full_cap_sec hasFullCapabilities
This method can be used to determine whether this application has <b>full capabilities</b>.  Only one application (the first one started) can have full capabilities.  If this is the first application started, this method returns true.  When an application does not have full capabilities, it cannot initiate connections.  Other functionality, such as disconnecting VPN, is available.


\section is_svc_avail_sec isVPNServiceAvailable
This method returns true if the VPN service is available for establishing VPN connections.

*/


/*! \page vpn_state_sub VPN Status Checking

\section is_conn_sec isConnected
This method returns true if this client has an active VPN connection with a Secure Gateway.

\section get_state_sec getState
This method triggers the retrieval of the current VPN state.
After the client is conected to the VPN service via the ClientIfc::attach
method, both the current state and any changes in state are
automatically delivered to the client.  In general, this method
should not be needed.

::VPNState is delivered via ClientIfc::StateCB method.

*/


/*! \page external_exit_sub Externally Initiated Exit Requests

\section exit_notice_sec ExitNoticeCB
This method is likely to occur only during connection attempts when it has
been determined that one of several factors has occured.  These may include:
<list type="bullet">
<item>
A software upgrade is required.
</item>
<item>
Start Before Logon (SBL) is in use.
</item>
<item>
The Secure Vault feature of Cisco Secure Desktop is in use.
</item>
</list>
There might be additional cases, but these are three common ones.

Unlike the other callback methods, a default implementation (calling 
the system's exit() function) is provided.  If clients of the API
want to override this behavior, they must ensure
that the current running process exits with the return code
specified by returnCode.

WARNING: If you override this method and do not exit with the proper
code, software update (or other) functionality in your client will not
work as expected.

*/


/*! \page sg_hosts_sub Using Secure Gateway Hosts

\section get_host_sec Hosts from Profile
The method ClientIfc::getHostNames returns a list of Secure Gateway
host names found in the current system's AnyConnect profile.  If no profile is
available, an empty list is returned.


\section def_host_sec Default Connection Host
The method ClientIfc::getDefaultHostName
returns the default Host name from user preferences.  Even if no profile
exists on the system, a host can still be returned here.  This method returns the
host last connected to (via ClientIfc::connect method).

If there is no preference containing the host last connected to, this method returns the first host found in an AnyConnect profile (if any).

\section web_host_sec Host from a Web launch
The method ClientIfc::deliverWebLaunchHostCB is useful when the connection
to the secure gateway has been established as part of a web-launch of the
VPN tunnel.

If the client application wants to be notified of the secure
gateway to which the VPN has been established, this method should
be overriden.

If the client application is started and a tunnel is already active,
this method also delivers the name of the secure gateway host.

*/


/*! \page manage_vpns_sub Managing VPN Connections

\section connect_sec connect
This method initiates a connection to the specified host,
resulting in the presentation of authentication
credentials, as appropriate.  The ClientIfc::UserPromptCB method delivers any
credential requests sent by the secure
gateway.
The ClientIfc::UserSubmit
method must be called to signal to the API that these requested prompts
have been completed and are ready for delivery back to the Secure Gateway. 

See ConnectPromptInfo for more details on possible authentication
credentials.

If the connection request is accepted, true is returned.  This does
not mean the VPN connection will succeed.  If the connection succeeds, the state
VPNState::CONNECTED will be received by the ClientIfc::StateCB method.


\section disc_sec disconnect
This method can be used to initiate a disconnect of the currently active VPN
connection.

When the VPN disconnect completes, the state VPNState::DISCONNECTED will be received by the
ClientIfc::StateCB method.

*/


/*! \page stats_manage_sub Managing Flow of Statistics


\section reset_stats_sec resetStats
This method resets current VPN statistics counters.


\section start_stats_sec startStats
This method activates the retrieval of VPN statistics and other
related data.  By default, VPNStats is automatically delivered
via the ClientIfc::StatsCB method, when a VPN is active.

If the ClientIfc::stopStats method is called to stop the delivery of
statistics, this method can be called to resume delivery.


\section stop_stats_sec stopStats
This method stops the delivery of VPN statistics and
other related data.  By default, VPNStats is automatically
delivered when a VPN is active.  This method disables delivery.

The method ClientIfc::startStats can be called to resume the delivery of
statistics.

*/

*/


//------ Advanced Topics ---------------

/*! \page adv_page Advanced Topics
The API is fully integrated into the AnyConnect environment.
This includes the use of SBL, CSD and web launch

\section gui_sub GUI implementations
There are several points of interest with the API that GUI programmers should
be aware of.  The main area of concern will be using the appropriate Event Model.  For additional information see the Event Models section.

Other topics of interest related to GUI and the features that are available include:
- Web Launch
- Window Management hints
- Start Before Logon
- Cisco Secure Desktop
- Localization

\subsection wm_sub Window Management Hints
A GUI program can further integrate with the AnyConnect API by taking
advantage of available <i>Window Managaement Hints</i>.  These hints will,
for various reasons, instruct the GUI to OPEN, QUIT or MINIMIZE.  For a
complete list see #WMHint.  For integration into a GUI program, see the
ClientIfc::WMHintCB method.

\section sign_sub Program Signing
Only signed binaries work as expected when integrated into the
AnyConnect environment.  A number of the AnyConnect feature implementations
work only when the GUI program is signed.

\subsection res_int_sub GUI Restart Following AnyConnect Upgrade
If the AnyConnect software determines that an upgrade of its software is
required, any currently running GUI will be terminated as part of the upgrade
 process.  The upgrade process will be preceeded by a running GUI being sent
a WMHint to QUIT.  If this hint is ignored, the GUI will be forcibly killed.

Once the updated software has been installed, the GUI will be automatically
restarted.  This restart requires that the GUI follow both
<i>Program Naming</i> and <i>Program Signing</i> conventions.

\subsection csd_int_sub Cisco Secure Desktop Integration
See the section <b>Cisco Secure Desktop</b> under <b>Program Arguments</b> for details on Cisco Secure Desktop integration.

\subsection sbl_int_sub Start Before Logon
This capability is available to Windows based GUI programs.  This
functionality will allow a GUI program to start and activate a VPN prior to
the Windows logon.

Using Start Before Logon requires that the <i>Program Naming</i> conventions
as well as <i>Program Signing</i> be followed.

\section name_sub Program Naming
With the API, the name of the
application binary must be the same as the currently supplied AnyConnect
GUI.  Further, the binary must be installed into the application
directory used by the AnyConnect software.  This overwrites
the AnyConnect GUI supplied by Cisco.  If the binary is imported into
ASDM, it is automatically installed into the mentioned location.

A GUI that does not use the current vpnui.exe does work and can be installed.
It cannot however take advantage of the integration previously
described.  In addition, the existing AnyConnect GUI is still used
during the integration events mentioned if it is not removed from the
system.

\section args_sub Program Arguments

\subsection sbl_sub Start Before Logon
The API supports a special mode of processing called Start Before Logon (SBL).
In this model the GUI (vpnui.exe) is launched by a special windows program
(GINA on Windows XP and PLAP on VISTA).  This program allows the GUI program to
run prior to the windows login, enabling a VPN tunnel to be established.
Once the tunnel is established, the normal Windows login will continue.

For this mode to work with a client GUI program, the GUI Program should
recognize the program argument <b>-sbl</b>.  This argument is passed
by Windows when the AnyConnect GINA or PLAP component is installed.  In
addition, the argument occurs only when the user is logging in
using <b><ctrl><alt><del></b> keyboard sequence.

The GUI client program recognizing this command line argument should use it
to configure the API ClientIfc::attach method.  Specifically, the SBL
argument for the attach method should be set to true.  Setting this
argument enables the API to work correctly when it is invoked as part of
a pre-login sequence.

As noted previously, the GUI used in this mode of operation must be signed
for it to be started.

\subsection csd_sub Cisco Secure Desktop
The Cisco Secure Desktop (CSD) environment has various options and
capabilities.  The API manages all of these for the client program.
One mode of operation with CSD is referred to as the <i>vault</i> which
s an option within Secure Desktop.

When this option is used, the GUI detects it (handled by the API) and
exits automatically.  Once the vault environment has started, the GUI 
is re-launched.  When it is re-launched, a command line argument is
passed to the GUI program.

To complete the GUI restart once the Secure Desktop vault has been started,
CSD launches the GUI with additional parameters.  These parameters must
be used as part of the subsequent connect method call.  The two parameters
are <b>-connect</b> and <b>-connectparam</b>.

These two parameters must be combined and passed to the connect method.
For example, the value for -connect may be hosta.xyz.com and for
connectparam \#csd123.  The value passed to the connect method would then
e <b>hosta.xyz.com\#csd123</b>.  


\subsection web_sub Web Launch
There are cases where the GUI can be launched automatically.  Once such case
is as part of a WEB-based launch.  In this mode, the VPN is started using
a web page.  After the VPN is active, the GUI is started.  As part of this
mode, the program argument <b>-autolaunched</b> is passed to the program.
This argument can be used to indicate to the GUI that it should start minimized
as opposed to opening on the desktop.

This launch capability requires the GUI to follow both <i>Program Naming</i>
and <i>Program Signing</i> requirements.


\section l10n_sub Localization
A third party GUI can take advantage of localization capabilities provided
via the AnyConnect API.  Localized string are available via labels associated
with PromptEntry objects (see PromptEntry::getPromptLabel).  In addition,
all notices (see ClientIfc::NoticeCB) and banner (see ClientIfc::BannerCB)
can be localized.  Finally, statistics labels
(see VPNStats::getTranslatedLabel) can also be localized.

See the AnyConnect Release notes for additional details on localization and
how to manage for AnyConnect.


\section prox_sub Proxy Support
Global proxy settings are supported on Windows only.  These can
be used for service-based implementations of the AnyConnect client.
The preferences file defining the proxy settings goes in the
C:\\Documents and Settings\\All Users\\Application Data\\Cisco\\Cisco AnyConnect VPN Client\\
directory on Windows machines.

\section example_sec Examples
Two examples are available with the API bundle.  One is a CLI and the other a GUI.  The code for these can be found in example/CLI and example/GUI.

The example code is tied to the documentation for quick referencing.  An
example of this linkage can be seen by viewing the ClientIfc class.  For some
of the methods, the text <i>Implemented in CLIClientImpl</i> will provide a
link to example code implementing the described method.

*/

*/
