Basic Capabilities

# 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 enabling the connection and disconnection of VPN, the collection of statistics, the monitoring of VPN state and the display of user messages.

## 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 the connection will succeed. If the connection succeeds, a state of VPNState::CONNECTED will be received via the ClientIfc::StateCB method.

## Disconnect

The ClientIfc::disconnect method can be used to initiate a disconnect of the active VPN connection.

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

## Statistics

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

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

The following methods allow for some control over the flow of VPN statistics. As a default, statistics will be sent once a VPN is connected.

See also
  ClientIfc::resetStats(), ClientIfc::stopStats() and ClientIfc::startStats()

## 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.

## 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 its own error code scheme.

# Activating the API

## Attach Method

Once the client application has created an instance of its 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 its 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.

## 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 usable again.

## 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.

# 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.

# 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.

# 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.