![]() |
AnyConnect Secure Mobility Client
4.10.08029
|
#include <ClientIfc.h>
Public Member Functions | |
bool | attach (ClientType clientType=ClientType_GUI, bool requestFullCapabilities=true, bool suppressAutoConnect=true) |
void | detach () |
virtual void | ProcessEvents () |
bool | hasFullCapabilities () |
bool | isConnected () |
bool | isAvailable () |
bool | isVPNServiceAvailable () |
bool | isOperatingMode (OperatingMode opMode) |
std::list< tstring > | getHostNames () |
tstring | getDefaultHostName () |
bool | connect (tstring host) |
virtual bool | setNewTunnelGroup (const tstring &group) |
void | disconnect () |
void | cancel () |
void | getState () |
void | getStats () |
void | resetStats () |
void | startStats () |
void | stopStats () |
void | exportStats (const tstring &tstrFilePath) |
void | setBannerResponse (bool bAccepted) |
void | setPreConnectReminderResponse () |
void | setCertBlockedResponse (bool bUnblock) |
void | setCertWarningResponse (bool bConnect, bool bImportCert) |
void | UserSubmit () |
PreferenceInfo & | getPreferences () |
bool | savePreferences () |
tstring | getConnectHost () |
void | setLastVpnError (VPNError vpnError) |
VPNError | getLastVpnError () |
Protected Member Functions | |
virtual void | StatsCB (VPNStats &stats)=0 |
virtual void | StateCB (const VPNState state, const VPNSubState subState, const tstring stateString)=0 |
virtual void | BannerCB (const tstring &banner)=0 |
virtual void | PreConnectReminderCB (const tstring &rtstrPreConnectReminder) |
virtual void | NoticeCB (const tstring ¬ice, const MessageType type, const bool bSensitive=false)=0 |
virtual void | ExitNoticeCB (const tstring &tstrNotice, const int returnCode) |
virtual void | ServiceReadyCB ()=0 |
virtual void | UserPromptCB (ConnectPromptInfo &ConnectPrompt)=0 |
virtual void | WMHintCB (const WMHint hint, const WMHintReason reason) |
virtual void | deliverWebLaunchHostCB (const tstring &activeHost) |
virtual void | CertBlockedCB (const tstring &rtstrUntrustedServer)=0 |
virtual void | CertWarningCB (const tstring &rtstrUntrustedServer, const std::list< tstring > &rltstrCertErrors, bool bAllowImport)=0 |
virtual void | EventAvailable () |
![]() | |
AgentIfc & | getAgentIfc () |
virtual std::list< HostEntry > | getHostEntries () |
bool | connect (tstring host, unsigned int origin) |
VPNState | getCurrentState () |
VPNSubState | getCurrentSubState () |
VPNSubState | getPreviousSubState () |
tstring | getStateText () |
void | setNetworkStates (NETENV_STATE netEnvState, NETCTRL_STATE netCtrlState, NETWORK_TYPE netType, bool bACBrowserForCPRemediation, bool bUpdateUI) |
void | refreshOperatingModeForCurrentNetStates () |
NETENV_STATE | getCurrentNetEnvState () |
NETENV_STATE | getPreviousNetEnvState () |
NETCTRL_STATE | getCurrentNetCtrlState () |
NETWORK_TYPE | getCurrentNetType () |
bool | isACBrowserForCPRemediation () |
tstring | getNetworkStatusText (const VPNState state, const VPNSubState subState, const NETENV_STATE netEnvState, const NETCTRL_STATE netCtrlState) |
PreferenceInfo & | getPreferences () |
bool | savePreferences () |
void | setBanner (const tstring &banner) |
void | setBannerResponse (bool bResponse) |
void | setPreConnectReminder (const tstring &tstrPreConnectReminder) |
void | setPreConnectReminderResponse () |
bool | getUserResponse () |
bool | isUserResponseSet () |
void | setCertBlocked (const tstring &tstrUntrustedServer) |
void | setCertWarning (const tstring &rtstrUntrustedServer, const std::list< tstring > &rltstrCertErrors, bool bAllowImport) |
bool | getCertImportResponse () |
void | setUserPrompt (ConnectPromptInfo &ConnectPrompt) |
void | setCertBlockedResponse (bool bUnlock) |
void | setCertWarningResponse (bool bConnect, bool bImportCert) |
void | insertStateToConnectPrompt (ConnectPromptInfo &ConnectPrompt) |
void | ExitNotice (const tstring &tstrNotice, const int code=0) |
void | notice (const tstring &tstrNotice, const MessageType type=MsgType_Info, bool bClearLastMsg=false, bool bForce=false, bool bStateMsg=false, bool bSensitiveMsg=false) |
void | notice (MsgWithArg ¬ice, const MessageType type=MsgType_Info, bool bClearLastMsg=false, bool bForce=false, bool bStateMsg=false, bool bSensitiveMsg=false) |
void | getStats (void) |
void | setStats (VPNStats &stats) |
void | exportStats (const tstring &tstrFilePath) |
void | setState (VPNState state, VPNState previousState, VPNSubState subState=VPNSS_NORMAL, bool bUpdateStateMsg=true, bool bOnlyUpdateUI=false) |
void | setWMHint (WMHint hint, WMHintReason reason) |
bool | isLastConnectType (const ConnectPromptType connPromptType) |
bool | isOperatingMode (OperatingMode opMode) |
void | setOperatingMode (OperatingMode opMode) |
void | unsetOperatingMode (OperatingMode opMode) |
bool | CanRemediateCaptivePortal () |
bool | policyAllowsCaptivePortalRemediation () |
bool | isEventShutdown () |
bool | isUsingEventModel () |
time_t | getLastDisconnectTime () |
ConnectPromptInfo | getConnectPromptInfo () |
void | resetConnectPromptPasswordData () |
void | setStandaloneConnection (bool isStandalone) |
void | deliverActiveHost (const tstring &activeHost, ConnectProtocolType vpnProtocol=PROTOCOL_TYPE_UNKNOWN, bool bActiveHostFriendlyName=false) |
bool | isVPNServiceReady () |
void | resetLastDisconnectTime (time_t time=1) |
void | processMinimize () |
void | setEnrollClientCert (CertObj *pCert) |
void | linuxCertImportWarnUser () |
void | linuxCertImportWarnUserResponse (bool bAccept) |
void | setDefaultHost (tstring &host) |
void | setLastVpnError (VPNError vpnError) |
VPNError | getLastVpnError () |
bool | requestImportLocalization (const tstring tstrLocale, const std::vector< unsigned char > &MoFileData) |
void | startAHS (const unsigned int uiReason, const ProxyIfc &proxy) |
void | AHSSelectedHost (const unsigned int uiReason, const std::vector< tstring > &headendList, const long statusReturnCode, const tstring &extraInfo) |
std::vector< tstring > | getAHSHostList () |
unsigned int | getAHSState () |
bool | isAHSHasRun () |
bool | suppressConnectionErrorPopups () |
tstring | getCaptivePortalDetectedMsg () |
void | setProxyAuthPrompts (ProxyIfc *pProxy, const tstring &promptMsg) |
bool | handleIpcMessage (CIpcMessage *pIpcMessage) |
bool | IsCsdTokenVerified () const |
void | activateConnectMgrTunnelInitiationCompletionEvent () |
bool | isConnectRequestActive () |
bool | syncProfileChange (const tstring &profileName) |
tstring | getConnectHost () |
tstring | getMgmtTunnelHostname () |
VPN_TUNNEL_SCOPE | getVpnTunnelScope () |
bool | isStandaloneConnection () |
void | sendSSoLogoutPrompt (ConnectPromptInfo &cpi) |
void | setExternalSSOLogoutUrlFromAgent (const tstring &logoutUrl) |
bool | IsAHSCachingRestricted () |
Additional Inherited Members | |
![]() | |
static tstring | getNoticeTypeText (MessageType msgType) |
static tstring | getStateText (VPNState state, VPNSubState subState=VPNSS_NORMAL, NETENV_STATE netEnvState=NES_NETWORK_ACCESSIBLE, const tstring &tstrConnectedHost=tstring()) |
static tstring | getNetCtrlText (NETCTRL_STATE netCtrlState) |
static tstring | getNetEnvText (NETENV_STATE netEnvState, bool bSimple=false) |
static tstring | getNetTypeText (NETWORK_TYPE netType) |
static tstring | getQuarantinedStatusText () |
static tstring | getNetworkStatusSimpleText (const NETENV_STATE netEnvState, const NETCTRL_STATE netCtrlState) |
This is the main interface class for applications that implement the Cisco AnyConnect Secure Mobility VPN API. A program wishing to use the API must create a class that extends the ClientIfc class. This new class is required to provide implementations for the pure virtual methods found in the protected section (for example, StatsCB).
Finally, the public section contains methods that are available for managing the API. These include methods like attach and connect.
A client must implement the CB (abstract) methods found in the protected section of this interface.
|
virtual |
After the ClientIfc class has been created, the client implementation must invoke this method prior to attempting connections, retrieving statistics, etc. If successful, this method returns true. If not successful, it returns false and returns a notice error message to the user.
A single call to this method is all that is necessary. If the attach fails, a message indicating the VPN service is not available is returned. If the call succeeds, the ServiceReadyCB is called and true is returned.
ClientType | clientType (default ClientType_GUI) Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT. ClientType_GUI: indicates that the started program is a GUI application. With this attribute set to true, the application will now receive WMHints. ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation where a GUI can be launched prior to the normal windows logon sequence. This allows a VPN tunnel to be activated and used as part of the windows logon sequence. This value is applicable only when a corresponding argument has been passed to the program by the VPN agent. ClientType_CLI: indicates that the started program is a CLI application. ClientType_MGMT: indicates that the started program is used to initiate an AnyConnect management VPN tunnel. This value is applicable only to a client launched by AnyConnect VPN agent. |
requestFullCapabilities | indicates that the client program is requesting full API capabilities. Full capabilities allows the client program to connect, disconnect, receive statistics, etc. When full capabilities are not requested or not available, the client program will not be able to establish new VPN connections. Only a client program with full capabilites can do this. In addition, only the first program requesting full capabilities will be granted this level of access. The attach method can succeed even if full capabilities is requested but not granted. To test for this state, use the method ::hasFullCapabilities. |
suppressAutoConnect | indicates that the client wishes to override automatically initiating a connection to the last connected secure gateway at startup. Normally, this is determined by the value of the AutoConnectOnStart preference. If this flag is true then an automatic connection will never be initiated, even if AutoConnectOnStart is enabled. |
Reimplemented from ClientIfcBase.
|
protectedpure virtual |
If a banner needs to be acknowledged, this CB delivers the banner to the client.
NOTE: Connection establishment will block until the method setBannerResponse() is called.
In a GUI, a banner would typically be displayed in a modal dialog with an accept or decline button selection.
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
virtual |
Use this method to cancel the user authentication. VPN tunnel is not connected at the moment. This function is used to cancel SSO authentication.
An indication of VPN disconnect is received via the StateCB method.
Reimplemented from ClientIfcBase.
|
protectedpure virtual |
This method is called when the preference to block untrusted servers is enabled and the current VPN server being connected to is untrusted. Clients should present an error to the user notifying them that the current connection to rtstrUntrustedServer is being blocked. The client should also provide a way for the user to change the preference to block untrusted servers.
The user response must be indicated using setCertBlockedResponse
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
protectedpure virtual |
This method is called when connections to untrusted VPN servers is allowed by policies and the current VPN server being connected to is untrusted. Clients should present a warning to the user notifying them that the current connection to rtstrUntrustedServer is unsafe. The reason the VPN server is untrusted is provided in rltstrCertErrors. The client should provide a way for the user to connect once, connect and always trust or cancel the connection. If bAllowImport is set to false then the always trust option should not be presented to users.
The user response must be indicated using setCertWarningResponse
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
virtual |
This method initiates a connection to the specified host. The connection results in the presentation of authentication credentials, as appropriate. Any credentials returned by the secure gateway are delivered via the 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 succeeded. If the connection succeeds, a state of connect will be received via the StateCB method.
Reimplemented from ClientIfcBase.
|
protectedvirtual |
This method 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 wishes 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.
Reimplemented from ClientIfcBase.
|
virtual |
After the client program is done, call the detach method to do a graceful cleanup. This method stops the flow of events and does general cleanup.
Reimplemented from ClientIfcBase.
|
virtual |
Use this method to initiate a disconnect of the active VPN connection.
An indication of VPN disconnect is received via the StateCB method.
Reimplemented from ClientIfcBase.
Reimplemented in CLIClientImpl.
|
protectedvirtual |
This method should be overriden by the client application to exercise some control over the delivery of events from the other protected methods in this class.
This might be necessary in cases where a GUI/CLI is being written and the data from this API needs to be delivered in the GUI/CLI or main thread. In this case, you should override this method and when it is called by the API post an event to your event queue (message pump, etc.). After this event executes in your GUI/CLI or main thread, call the method ClientIfc::ProcessEvents to have events delivered to your client application.
Reimplemented from ClientIfcBase.
Reimplemented in CLIClientImpl.
|
protectedvirtual |
This CB would likely occur only during a connection when it was detected that the software needed to be upgraded, or when Start Before Logon (SBL) is being used.
Unlike the other callback methods, this method provides a default implementation (calling the system's exit() function). If clients of the API wish to override this behavior, they are responsible for ensuring that the current running process exits with the return code specified by returnCode.
Caution: IF YOU OVERRIDE THIS METHOD AND DO NOT EXIT WITH THE PROPER CODE SOFTWARE UPDATE FUNCTIONALITY IN YOUR CLIENT WILL BREAK
Reimplemented from ClientIfcBase.
Reimplemented in CLIClientImpl.
void ClientIfc::exportStats | ( | const tstring & | tstrFilePath | ) |
This method directs where and how to export the statistics
tstring ClientIfc::getConnectHost | ( | ) |
This is called from the credential dialog in the GUI to get the correct friendly name for the dialog title.
|
virtual |
This method returns any default Host name from User Preferences.
A host can be returned here even if there are no profiles on the system. The host last connected to (via the connect method) is returned by this method.
If there is no previously connected-to host, the first host found in an AnyConnect profile (if any) is returned.
Reimplemented from ClientIfcBase.
|
virtual |
This method returns a list of secure gateway host names found in an AnyConnect profile. If no profile is available, an empty list is returned.
Reimplemented from ClientIfcBase.
VPNError ClientIfc::getLastVpnError | ( | ) |
This method gets the last VPN error seen during this connection attempt for reporting purposes. This VPN error should be cleared for each connection attempt.
PreferenceInfo& ClientIfc::getPreferences | ( | ) |
Method for retrieving the currently available user preferences. This method returns an instance of the class PreferenceInfo. The instance contains a variable number of Preference object pointers. Each preference contains data identifying the specific preference, its current value, etc. For a list of all possible preferences see the PreferenceId enum in api.h. Note that some of these preferences are not available to the user.
|
virtual |
This method triggers the retrieval of the current VPN state. After the client is conected to the VPN service via the 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 StateCB method.
Reimplemented from ClientIfcBase.
void ClientIfc::getStats | ( | ) |
|
virtual |
Use this method to determine whether this application has full capabilities. 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 has full capabilities, it can initiate connections, as well as offer UI capabilities.
Reimplemented from ClientIfcBase.
|
virtual |
This method returns true if the client VPN is available for use. If false is returned this means that VPN has been intentionally disabled. This would indicate a situation where other AnyConnect services were in use but not VPN.
Reimplemented from ClientIfcBase.
|
virtual |
This method returns true if the client has an active VPN connection with a secure gateway.
Reimplemented from ClientIfcBase.
bool ClientIfc::isOperatingMode | ( | OperatingMode | opMode | ) |
This method returns true if the mode in which the client is currently operating is enabled. For a list of all possible modes of operation see the OperatingMode enum in api.h.
bool ClientIfc::isVPNServiceAvailable | ( | ) |
This method returns true if the VPN service is available for establishing VPN connections.
|
protectedpure virtual |
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.
Clients using the API as an embedded application (not user visible) might want 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.
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
protectedvirtual |
If a pre-connect reminder needs to be acknowledged, this CB delivers the pre-connect reminder to the client.
NOTE: Connection establishment will block until the method setPreConnectReminderResponse() is called.
In a GUI, a pre-connect reminder would typically be displayed in a modal dialog with an OK button selection.
Reimplemented from ClientIfcBase.
Reimplemented in CLIClientImpl.
|
virtual |
When the method ClientIfc::EventAvailable has been overriden in the client application, this method must be called to receive events.
It is expected that GUI programs will use EventAvailable as a signal, allowing them to set an event using their native event handler. When that event fires, the application can call ProcessEvents, which causes the API to deliver events in the client's main thread.
Reimplemented from ClientIfcBase.
Reimplemented in CLIClientImpl.
|
virtual |
This method resets current VPN statistics counters.
Reimplemented from ClientIfcBase.
bool ClientIfc::savePreferences | ( | ) |
This method stores the current set values of the preferences to the preferences file(s). This method is a counterpart to the getPreferences() method.
|
protectedpure virtual |
Under normal operating conditions, this CB is called as soon as the attach method completes. In case the service (vpn agent) is not ready, this CB is not called until it is.
Any API calls made prior to this CB being called will result in a NoticeCB error message.
Implements ClientIfcBase.
Implemented in CLIClientImpl.
void ClientIfc::setBannerResponse | ( | bool | bAccepted | ) |
Call this method after a BannerCB has been received to indicate that the user response to the banner can now be read.
bAccepted | indicates if the user accepted or declined the banner. |
void ClientIfc::setLastVpnError | ( | VPNError | vpnError | ) |
This method sets the last VPN error seen during this connection attempt for reporting purposes. This VPN error should be cleared for each connection attempt.
|
virtual |
Use this method to change selected group after initial connection request has been made and credentials were delivered.
Depending on secure gateway configuratiion, call to this method may result in a new connection request and will update credentials required for the selected group. New credentials returned by the secure gateway are delivered via the UserPromptCB method.
Reimplemented from ClientIfcBase.
void ClientIfc::setPreConnectReminderResponse | ( | ) |
Call this method after a PreConnectReminderCB has been received to indicate that user has acknowledged pre-connect reminder message.
NOTE : Ignoring the response from user (for example, closing the modal dialog instead of clicking OK button). Old AnyConnect client (v3.1) ignored the response too.
|
virtual |
This method activates the retrieval of VPN statistics and other related data. By default, VPNStats are automatically delivered via the method StatsCB.
If the stopStats method is called to stop the delivery of statistics, this method can be called to resume delivery.
Reimplemented from ClientIfcBase.
|
protectedpure virtual |
Callback used to deliver VPN state and state change string. The stateString delivered by this method is localized.
See the VPNState enum found in api.h for set of valid states.
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
protectedpure virtual |
Callback used to deliver new statistics related to the VPN connection.
When a connection is active, a new set of statistics is delivered each second.
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
virtual |
This method stops the delivery of VPN statistics and other related data. By default, VPNStats are automatically delivered. This method disables delivery.
The method startStats can be called to resume the delivery of statistics.
Reimplemented from ClientIfcBase.
|
protectedpure virtual |
This method supports prompting for single or multiple values. All prompts are considered mandatory.
The ConnectPromptInfo object contains a list of PromptEntry instances. The labels and their default values (if any) can be found in these instances. 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 UserSubmit() to have the responses read by the API.
Implements ClientIfcBase.
Implemented in CLIClientImpl.
|
virtual |
Call this method to indicate that authentication credential requests values solicited by the UserPromptCB method can now be read from the ConnectPromptInfo instance.
Reimplemented from ClientIfcBase.
|
protectedvirtual |
Use this method to provide Window Manager hints to GUI applications. To receive these hints, the application must identify itself as a GUI in the attach method. In addition, this method should be overriden to receive any generated events.
Event that can be received include those indicating that a user is starting a second instance of the GUI application. This information can be used to tell the already running application to un-minimize itself and let the new program know that it should Quit (since a GUI is already running).
Reimplemented from ClientIfcBase.