Developing an application that uses the Nexus Card SDK means, from a development point of view, working with XMLs and developing a web service client. This article describes some general basic introduction and approaches to use web services with popular programming languages. The examples used are calling the SDK's web service and its capture dialog.

.NET with C# and Microsoft Visual Studio

In this service integration the SDK's SOAP interface is called from a simple Windows Forms Application named WindowsFormsTestApp. In our example, we use the approach to integrate the web service as .NET Web Reference and not as Service Reference. According to our experience, this style is easier to handle. But you can also chose to integrate the web service as Service Reference.

In Visual Studio's Solution Explorer window, right click the project name and select Add Service Reference... in the menu.
The Add Service Reference dialog opens. Click Advanced...
The Service Reference Settings dialog opens. Click Add Web Reference...
The Add Web Reference dialog opens.
1. Enter the WSDL URL of the Web service (1) (http://localhost:54880/?wsdl)
2. Press Enter or click the white/green arrow button (2). The service and its methods are displayed.
3. Enter a meaningful name like CardSDK for the Web reference name (3).
4. Click Add Reference (4) to create the Web reference and to close the dialog.

The reference is now ready to use.

To call the capture dialog, enter some code like the following in any method of your application. We use a simple button-triggered event. You may call all other requests of the web service in corresponding way:

private void button1_Click(object sender, EventArgs e)
{
	int iResultId;
	String strResultText;
	String strResultData;
	String strRequestData = "<?xml version=\"1.0\"?>"
	+ "<image type=\"photo\" format=\"jpg\" ><result data=\"\"/></image>";

	CardSDK.IDProductionService ws = new CardSDK.IDProductionService();
	iResultId = ws.ImageCapture(strRequestData,
		out strResultText, out strResultData);
	if (iResultId == 0)
	{
		// ... strResultData contains the request's response XML which contains
		// the returned image. You may process it using any XML parser
		// (e.g. .NET's XmlDocument)
	}
}

The SDK provides the Visual C# example that uses the web service as described here. You can find the examples in the examples directory of the SDK installation.

Java

Using Java and the web service's SOAP interface, the Java API for XML Web Services (JAX-WS) in combination with the wsimport tool, is usually the first choice to access a web service. API and wsimport tool are part of the JDK package since Version 6.

Also Apache Axis can be used. But as Axis requires additional packages, we will only show the wsimport way here.

When developing an application using Java, the SOAP way with wsimport generated wrappers may be easier, as the created classes may support the development (provided that Java 6 or higher is used). But you can also use the equivalent RESTful way.

JavaScript

Using JavaScript is typically used to access a web service from an HTML page in a browser. For this purpose, JavaScript offers the XMLHttpRequest object. This object, which is available in all popular browsers, allows to send and receive data by using HTTP. You can very easily access a service's REST interface in this way.

Use this code to start the capture dialog from an HTML in a browser:

try {
	var req = new XMLHttpRequest();
	var strRequestData = "<?xml version=\"1.0\"?>"
		+ "<image type=\"photo\" format=\"jpg\" ><result data=\"\"/></image>";
	req.open("POST", "ImageCapture", false);
	req.setRequestHeader("Content-Type","text/xml");
	req.send(strRequestData);
	if (req.status == 200) {
		// req.responseText contains the returned XML as string
		// req.responseXML contains the returned XML accessable
		// as XML DOM object
	}
} catch (ex) {
	alert(ex);
}

Note: The SDK's requests, which show a user interface like the capture dialog, work synchronously. This may cause refresh issues of some browser's main windows (especially the Internet Explorer). Therefore, we recommend to do the request asynchronously as shown in following code:

try {
	var req = new XMLHttpRequest();
	req.onreadystatechange=function() {
		try {
			if (req.readyState==4) {
				if (req.status == 200) {
					// req.responseText contains the returned XML as string
					// req.responseXML contains the returned XML accessable
					// as XML DOM object
				}
			}
		} catch (ex) {
			alert(ex);
		}
	}
	var strRequestData = "<?xml version=\"1.0\"?>"
	+ "<image type=\"photo\" format=\"jpg\" ><result data=\"\"/></image>";
	req.open("POST", "ImageCapture", true);
	req.setRequestHeader("Content-Type","text/xml");
	req.send(strRequestData);
} catch (ex) {
	alert(ex);
}

A last issue when using JavaScript may be caused by caching issues - again typically in combination with the Internet Explorer. An easy but effective workaround is a changing parameter added to the request URL as this code snippet demonstrates:

var date = new Date();
var reloadTrigger = "?"+date.getTime()
req.open("GET", "ImageCapture" + reloadTrigger, false);

There are a lot of example code implemented in the HTMLs of the web service's service interface (http://localhost:54880/components.htm and http://localhost:54880/development.htm).

Notes for Internet Explorer

XMLHttpRequest (XHR) as used here, is the API to send HTTP requests from within a browser. It is available in the described way in all up-to-date browsers (Mozilla, Opera, Chrome and Internet Explorer). However, the way the IE supports XHR does strongly depend on its version:

IE 5, 5.5 and 6 support XHR, but require a different object instantiation.
IE 7 allows the usage as described in this article.
IE 8 and IE 9 support XHR basically but prevent cross-site requests. This is important in our use case: The HTML page is usually provided by an application server with a domain that is different from the production service's domain. Only in the special case of the IDProductionService, application server and production service domain are identical. Instead, Microsoft introduced the XDomainRequest (XDR) object to make cross-domain requests. XDR is a stripped-down XHD.
IE 10 allows cross-domain requests using XMLHttpRequest. It can be used in the same way as used with Mozilla, Opera and Chrome.

Using XMLHttpRequest and XDomainRequest directly as shown here is the basic way to communicate with a web service using Java script. However, it may be a more convenient way to use a library like jQuery package (http://jquery.com ) or one of its alternatives. For more information, refer to the libraries public documentation. The usage of such libraries may help to solve issues using different browsers and their versions.

C/C++

C or C++ as more low level languages indicate to use the lean implementable REST interface. This is done using the Windows WinINet API to communicate with a peer using HTTP.

This code shows the basics to call the capture dialog:

TCHAR headers[] = _T("Content-Type: application/x-www-form-urlencoded");
LPSTR accept[2]={"*/*", NULL};
TCHAR requestData[] =
_T("<?xml version=\"1.0\"?><image type=\"photo\" \
format=\"jpg\" ><result data=\"\"/></image>");
HINTERNET hSession = InternetOpen("MyAgent",
	INTERNET_OPEN_TYPE_PRECONFIG, NULL, NULL, 0);
HINTERNET hConnect = InternetConnect(hSession, _T("localhost"),
	54880, NULL, NULL, INTERNET_SERVICE_HTTP, 0, 1);
HINTERNET hRequest = HttpOpenRequest(hConnect, "POST",
	_T("ImageCapture"), NULL, NULL, (LPCTSTR*)accept, 0, 1);
if (HttpSendRequest(hRequest, headers, strlen(headers),
		requestData, strlen(requestData))) {
	TCHAR szHttpInfo[10] = _T("");
	DWORD lenHttpInfo = sizeof(szHttpInfo);
	if (HttpQueryInfo( hRequest, HTTP_QUERY_STATUS_CODE ,
			szHttpInfo, &lenHttpInfo, 0L)) {
		if (_ttoi( szHttpInfo) == 200) { // 200 = OK
			lenHttpInfo = sizeof(szHttpInfo);
			if (HttpQueryInfo( hRequest, HTTP_QUERY_CONTENT_LENGTH,
					szHttpInfo, &lenHttpInfo, 0L)) {
				char* resultData = (char*)LocalAlloc( LPTR, _ttoi( szHttpInfo));
				if (InternetReadFile( hRequest, resultData, _
						ttoi( szHttpInfo), &lenHttpInfo)) {
					// Just for test purposes, we store the received XML into the 
					// file resultData.xml (note the current working directory!)
					DeleteFile( _T("resultData.xml"));
					HANDLE hf = CreateFile( _T("resultData.xml"),
									GENERIC_ALL, 0, 0L, 1, 0x80L, 0);
					if (hf != INVALID_HANDLE_VALUE) {
						WriteFile( hf, resultData, lenHttpInfo, &lenHttpInfo, 0L);
						CloseHandle( hf);
					}
					LocalFree( resultData);
				}
			}
		}
	}
}
InternetCloseHandle( hRequest);
InternetCloseHandle( hConnect);
InternetCloseHandle( hSession);

You may use any XML library to retrieve the image data contained in resultData (or to prepare requestData to be sent). However, if you are still free to use a library we recommend pugixml (http://pugixml.org). pugixml is a light-weight and easy to use C++ XML processing library. Provided on source code basis, it just consists of one implementation and two header files and fits perfectly to the light-weight approach of a REST web service. Apart from the advices and code snippets above, we do not offer further example code for C++.

Examples

We provide several examples demonstrating the usage of the SDK. The examples are intended as supplement to these articles. First of all, use these articles to get a starting point regarding the SDK's basic functionality. The discussions regarding the usage with different programming languages, can be used to get a first approach to start the practical implementation. The examples are intended as a reference implementation for the usage and functionality of the SDK. Feel free to pick those parts from the examples which may be helpful for you.

You can find the examples in the examples directory of the SDK installation.

Nexus Documentation