This sample is supplied as is with no implied warranty.
It is designed to assist you in using the Cisco AnyConnect VPN API.
It is assumed that you will build a production application and refer to this sample
as a reference only.
Send questions to anyconnect-api-support@cisco.com
1) Install the AnyConnect VPN Client (2.3 or later)
on your PC.
2) This project looks in the $(ProgramFiles)\Cisco\Cisco AnyConnect VPN Client\
directory,
for the vpnapi.dll file.
3) It extracts the Typelib and generates the vpnapi.tlh and vpnapi.tli files
automatically.
4) After installing AnyConnect, simply build the application, and you can then start to use
it.
If you have the Cisco IPsec client installed, move the \Windows\System32\vpnapi.dll
to the Cisco IPsec install directory. For additional options, see the stdafx.h
file comments on this subject.
Note:
The application configures COM in STA mode. If you are not familiar with STA
and MTA, please consult MSDN for more information.
Additionally, by default, the COM server runs in high isolation mode (out-of-proc).
You can change this to run as a DLL, loaded in this application (in-proc) by setting
a single preprocessor value.
MTA is beyond the scope of this example, and it is assumed that if you use an MTA
you have sufficient COM expertise to handle multithreading techniques required
to serialize events sent back to the application from the COM server.
In the CppComSampleDlg you will find the following discussion on the STA / High isolation
mode of operation:
//|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
//
//Uncomment the next line to run the VPN API COM Server INPROC
//#define
COM_INPROC_EXAMPLE
//
//|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
//NOTE: In this example, the COM object is hosted out of process by design.
// Additionally, the threading for COM is set for STA in this sample.
// As a result of both of these items, COM notifications will be
// serialized to your UI thread.
//
// This removes the need for you to worry about threading and also
// provides a layer of fault isolation between your application and
// the VPN API. For example, you might be writing a module whose
// primary role is not VPN related, and want to ensure the component
// is isolated from VPN components (and vice-versa).
//
// If you choose to explicitly host the API COM server INPROC, using
// an STA threading model, then uncomment the #define COM_INPROC_EXAMPLE
// at the top of this file. This will allow you to use the COM API
// in a manner that processes events on your UI thread. This is accomplished
// by setting the VpnApi::EnableConsumerDrivenEventModel = VARIANT_TRUE
//
// THIS EXAMPLE DEMONSTRATES STA / OUT-OF-PROC COM BY DEFAULT
//
What does the TypeLibrary import create?
When the TypeLibrary is imported (automatically by just doing a build), two files
are auto-generated for you.
vpnapi.tlh and
vpnapi.tli
The auto-generated files provide a lot of flexibility in how the
COM methods and properties are called.
For example, obtaining the Default Host Name property from the IVpnApi interface
can be done 3 different ways.
[2 ways for methods, 3 ways for properties]
- 'Raw' methods (raw_Xxxx ) and 'raw' properties ( put_Xxxx get_Xxxx).
These do not raise exceptions and just return HRESULT status to indicate success
or failure.
_bstr_t bstrName;
HRESULT hr = pVpnApi->get_DefaultHostName(&bstrName);
if (FAILED(hr)) ....
- Wrapped interface calls. These methods and properties wrap the 'raw'
implementation and raise exceptions.
try
{
_bstr_t bstrName = pVpnApi->GetDefaultHostName();
}
catch(_com_error err) ....
- Properties also have a variable declared that is assigned by the wrapped methods
from item #2.
These are subject to the exceptions of the wrapped methods.
try
{
_bstr_t bstrName = pVpnApi->DefaultHostName;
}
catch(_com_error err) ....
This sample application uses the 'wrapped' methods and properties
as described in #2 and #3.
EventCallBack.h contains the CEventCallBack COM ATL implementation as described
below.
You must implement this interface and provide it to the COM VPN API Server.
This example
implements this interface and provides the instance to the COM Server.
// --
EventCallBack.h --
//This file
contains the COM object implementation of the IVpnApiEvents interface using ATL.
//An instance of this class is given to the COM Server to use for firing notifications.
//The defined class, CEventCallBack is then added to the object inheritance of the
dialog class
//via the CComObjectStackEx template class (which requires a concrete
class object argument).
//The use of CComObjectStackEx requires that you create
the dialog on the stack.
//The virtual methods of this concrete class are then overriden
in the dialog class
by you,
//as is shown in this example.
//