Creating a Client in C++ Using ATL Server

This section explains how to create an ATL Server web service client for the AAA Server 6.7.2 SKI Connector service.

Important:
Differences between Microsoft Visual Studio 2005 and 2008:

The following are no longer included in Microsoft Visual Studio 2008:

  • ATL Server technology – you should either compile the sample code using Microsoft Visual Studio 2005, or include the ATL Server library headers in the project.

  • The sproxy.exe tool used to generate the web service files – use the version provided in Microsoft Visual Studio 2005.

Generate the Web Service Client Files

Use the following command line to run sproxy.exe and generate the header file containing all the classes and structures required to use the web service:

sproxy.exe /wsdl /out:<output_path>\SKIConnector.h <wsdl_path>\ActivCardSKIConnectorV2.wsdl

Where:

  • <output_path> points to the folder where the generated files are to be stored.

  • <wsdl_path> points to the folder of the .wsdl file.

Note: In the sample, the output filename is set to SKIConnector.h, If you change it, you must include the new filename correctly in the project.

The same also applies to the .wsdl file: It is not necessary to include it in the project, but take into account that some tools might generate classes according to the filename.

Configure the Web Service Client

  1. Use the following command to initialize the COM objects used by the ALT Server:

CoInitialize(NULL);

  1. Include the generated .h file in the project and use the namespace given by the generated file to access the client classes and functions.

    2. In the provided .wsdl file, the namespace should be ActivCardSKIConnectorV2.

  1. The generated header contains a class in charge of generating an instance of the client (in the sample, CActivCardSKIConnectorV2T<CSoapMSXMLInetClient>).

    2. To create a client, generate an instance of this class as follows:

    Copy 
    CActivCardSKIConnectorV2T<CSoapMSXMLInetClient> * pService;
    pService = new CActivCardSKIConnectorV2T<CSoapMSXMLInetClient>;

  1. As the sample does not use SSL, configure the client with the following elements:

    • pService->SetTimeout(timeout); – A timeout in milliseconds.
    • pService->SetUrl(url); – The service endpoint URI in a TCHAR table.

  1. For AAA Server 6.7.2, set the service endpoint URI as follows:

    2. http://<hostname>:<port>/Invoke?Handler=ActivCardSKIConnectorV2

  1. To test the client configuration and connection, it is recommended that you use a simple function such as getVersion().

    2. If getVersion() returns nothing or indicates an error, the endpoint URL might be wrong or using an invalid format.

Note: If the ActivID SKI Connector is using SSL, you also need to configure the sample (not described here). For further information, contact HID Global technical support.

Use the ActivID SKI Connector Functions

  1. To use the ActivID SKI Connector functions, call the corresponding methods of the client with the required variables.

    2. For further information about the method names and input/output variables, refer to ActivID SKI Connector Service API Functions.

  1. As most functions can only be used with a valid login handle, retrieve it using the Login() function before performing any other operation.

  2. As ATL server is using COM object, allocate each String passed as an argument with SysAllocString() and free them with SysFreeString().

  3. If the function has an output value, pass a reference or pointer to a relevant variable to retrieve it.

If the returned value is a structure, it should be one that is defined in the generated header file.

Closing the Service

  1. Before closing the service, it is recommended that you use the Logout() function to invalidate the login handle.

    2. If you do not, it is only invalidated after a defined time (10 minutes).

  1. To close the server, delete the instance of the class as follows:

Copy 
delete pService;
pService = NULL;
CoUninitialize();

Error Cases

With the ATL Server API, all client function calls return an HRESULT indicating if the web service call performed correctly.

In addition, most functions have a returned value (often a boolean) indicating if the operation was successful.

Implementation Example

Copy 
int nTimeout = 10 * 60 * 1000; /* setting a 10 minutes timeout */
HRESULT hRes = S_FALSE;
long long hLogin = -1;
BSTR sTMPadminUID = SysAllocString("<admin_uid>");
BSTR sTMPadminPWD = SysAllocString("<admin_pwd>");
 
hRes = pService->Login(    sTMPadminUID, 
                sTMPadminPWD, 
                nTimeout, 
                &hLogin);
 
SysFreeString(sTMPadminUID);
SysFreeString(sTMPadminPWD);
if (SUCCEEDED(hRes))
{
if (hLogin>0) cout << "Login succeeded."<< endl;
    else
    {
        cout << "ERROR: invalid credentials." << endl;
        // Handle error case
    }
}
else
{
    cout << "ERROR: Login webservice call failed" << endl;
    // Handle error case
}