Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleJava

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.

Expand
title

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:

Code Block
languagexml
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:

Code Block
languagexml
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:

Code Block
languagexml
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).

title
Expand
titleNotes 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.

Expand

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:

Code Block
languagecpp
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.