{"type":"doc","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":".NET with C# and Microsoft Visual Studio","type":"text"}]},{"type":"paragraph","content":[{"text":"In this service integration the SDK's SOAP interface is called from a simple Windows Forms Application named ","type":"text"},{"text":"WindowsFormsTestApp","type":"text","marks":[{"type":"em"}]},{"text":". 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.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Visual Studio's ","type":"text"},{"text":"Solution Explorer","type":"text","marks":[{"type":"strong"}]},{"text":" window, right click the project name and select ","type":"text"},{"text":"Add Service Reference...","type":"text","marks":[{"type":"strong"}]},{"text":" in the menu.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":250,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":349,"id":"2a7c3d51-0579-40c9-b7fb-a9ba9417d18e","collection":"contentId-65348644","type":"file","height":185}}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Add Service Reference","type":"text","marks":[{"type":"strong"}]},{"text":" dialog opens. Click ","type":"text"},{"text":"Advanced...","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":535,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":535,"alt":"098d9012-1c83-4a9a-a35d-8364da08a3c5.png","id":"e2d47e1d-b2df-4816-9292-90be43b01a4f","collection":"contentId-65348644","type":"file","height":436}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Service Reference Settings ","type":"text","marks":[{"type":"strong"}]},{"text":"dialog opens. Click ","type":"text"},{"text":"Add Web Reference...","type":"text","marks":[{"type":"strong"}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":551,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":551,"id":"1affe5f2-4736-4869-872a-a45d36ca9acd","collection":"contentId-65348644","type":"file","height":517}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Add Web Reference ","type":"text","marks":[{"type":"strong"}]},{"text":"dialog opens.","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Enter the WSDL URL of the Web service (1) (","type":"text"},{"text":"http://localhost:54880/?wsdl","type":"text","marks":[{"type":"em"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Press ","type":"text"},{"text":"Enter","type":"text","marks":[{"type":"strong"}]},{"text":" or click the white/green arrow button (2). The service and its methods are displayed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Enter a meaningful name like CardSDK for the Web reference name (3).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Click ","type":"text"},{"text":"Add Reference","type":"text","marks":[{"type":"strong"}]},{"text":" (4) to create the Web reference and to close the dialog.","type":"text"},{"type":"hardBreak"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":701,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":701,"alt":"491daca6-c833-460e-91d3-d46cd79e0808.png","id":"dc8bca17-dfa5-403d-99c4-5ad9c7a1cc82","collection":"contentId-65348644","type":"file","height":492}}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"The reference is now ready to use.","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"private void button1_Click(object sender, EventArgs e)\n{\n\tint iResultId;\n\tString strResultText;\n\tString strResultData;\n\tString strRequestData = \"\"\n\t+ \"\";\n\n\tCardSDK.IDProductionService ws = new CardSDK.IDProductionService();\n\tiResultId = ws.ImageCapture(strRequestData,\n\t\tout strResultText, out strResultData);\n\tif (iResultId == 0)\n\t{\n\t\t// ... strResultData contains the request's response XML which contains\n\t\t// the returned image. You may process it using any XML parser\n\t\t// (e.g. .NET's XmlDocument)\n\t}\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Java","type":"text"}]},{"type":"paragraph","content":[{"text":"Using Java and the web service's SOAP interface, the Java API for XML Web Services (JAX-WS) in combination with the ","type":"text"},{"text":"wsimport","type":"text","marks":[{"type":"em"}]},{"text":" tool, is usually the first choice to access a web service. API and ","type":"text"},{"text":"wsimport","type":"text","marks":[{"type":"em"}]},{"text":" tool are part of the JDK package since Version 6.","type":"text"}]},{"type":"paragraph","content":[{"text":"Also Apache Axis can be used. But as Axis requires additional packages, we will only show the ","type":"text"},{"text":"wsimport","type":"text","marks":[{"type":"em"}]},{"text":" way here.","type":"text"}]},{"type":"paragraph","content":[{"text":"When developing an application using Java, the SOAP way with ","type":"text"},{"text":"wsimport","type":"text","marks":[{"type":"em"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"JavaScript","type":"text"}]},{"type":"paragraph","content":[{"text":"Using JavaScript is typically used to access a web service from an HTML page in a browser. For this purpose, JavaScript offers the ","type":"text"},{"text":"XMLHttpRequest","type":"text","marks":[{"type":"em"}]},{"text":" 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.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this code to start the capture dialog from an HTML in a browser:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"try {\n\tvar req = new XMLHttpRequest();\n\tvar strRequestData = \"\"\n\t\t+ \"\";\n\treq.open(\"POST\", \"ImageCapture\", false);\n\treq.setRequestHeader(\"Content-Type\",\"text/xml\");\n\treq.send(strRequestData);\n\tif (req.status == 200) {\n\t\t// req.responseText contains the returned XML as string\n\t\t// req.responseXML contains the returned XML accessable\n\t\t// as XML DOM object\n\t}\n} catch (ex) {\n\talert(ex);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"try {\n\tvar req = new XMLHttpRequest();\n\treq.onreadystatechange=function() {\n\t\ttry {\n\t\t\tif (req.readyState==4) {\n\t\t\t\tif (req.status == 200) {\n\t\t\t\t\t// req.responseText contains the returned XML as string\n\t\t\t\t\t// req.responseXML contains the returned XML accessable\n\t\t\t\t\t// as XML DOM object\n\t\t\t\t}\n\t\t\t}\n\t\t} catch (ex) {\n\t\t\talert(ex);\n\t\t}\n\t}\n\tvar strRequestData = \"\"\n\t+ \"\";\n\treq.open(\"POST\", \"ImageCapture\", true);\n\treq.setRequestHeader(\"Content-Type\",\"text/xml\");\n\treq.send(strRequestData);\n} catch (ex) {\n\talert(ex);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"var date = new Date();\nvar reloadTrigger = \"?\"+date.getTime()\nreq.open(\"GET\", \"ImageCapture\" + reloadTrigger, false);","type":"text"}]},{"type":"paragraph","content":[{"text":"There are a lot of example code implemented in the HTMLs of the web service's service interface (http://localhost:54880/components.htm and ","type":"text"},{"text":"http://localhost:54880/development.htm).","type":"text","marks":[{"type":"link","attrs":{"href":"http://localhost:54880/development.htm)."}}]}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Notes for Internet Explorer","type":"text"}]},{"type":"paragraph","content":[{"text":"XMLHttpRequest","type":"text","marks":[{"type":"em"}]},{"text":" (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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IE 5, 5.5 and 6 support XHR, but require a different object instantiation.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IE 7 allows the usage as described in this article.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"IDProductionService","type":"text","marks":[{"type":"em"}]},{"text":", application server and production service domain are identical. Instead, Microsoft introduced the ","type":"text"},{"text":"XDomainRequest","type":"text","marks":[{"type":"em"}]},{"text":" (XDR) object to make cross-domain requests. XDR is a stripped-down XHD.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"IE 10 allows cross-domain requests using ","type":"text"},{"text":"XMLHttpRequest","type":"text","marks":[{"type":"em"}]},{"text":". It can be used in the same way as used with Mozilla, Opera and Chrome.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Using ","type":"text"},{"text":"XMLHttpRequest","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"XDomainRequest","type":"text","marks":[{"type":"em"}]},{"text":" 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 (","type":"text"},{"type":"inlineCard","attrs":{"url":"http://jquery.com"}},{"text":" ) 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.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"C/C++","type":"text"}]},{"type":"paragraph","content":[{"text":"C or C++ as more low level languages indicate to use the lean implementable REST interface. This is done using the Windows ","type":"text"},{"text":"WinINet","type":"text","marks":[{"type":"em"}]},{"text":" API to communicate with a peer using HTTP.","type":"text"}]},{"type":"paragraph","content":[{"text":"This code shows the basics to call the capture dialog:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"TCHAR headers[] = _T(\"Content-Type: application/x-www-form-urlencoded\");\nLPSTR accept[2]={\"*/*\", NULL};\nTCHAR requestData[] =\n_T(\"\");\nHINTERNET hSession = InternetOpen(\"MyAgent\",\n\tINTERNET_OPEN_TYPE_PRECONFIG, NULL, NULL, 0);\nHINTERNET hConnect = InternetConnect(hSession, _T(\"localhost\"),\n\t54880, NULL, NULL, INTERNET_SERVICE_HTTP, 0, 1);\nHINTERNET hRequest = HttpOpenRequest(hConnect, \"POST\",\n\t_T(\"ImageCapture\"), NULL, NULL, (LPCTSTR*)accept, 0, 1);\nif (HttpSendRequest(hRequest, headers, strlen(headers),\n\t\trequestData, strlen(requestData))) {\n\tTCHAR szHttpInfo[10] = _T(\"\");\n\tDWORD lenHttpInfo = sizeof(szHttpInfo);\n\tif (HttpQueryInfo( hRequest, HTTP_QUERY_STATUS_CODE ,\n\t\t\tszHttpInfo, &lenHttpInfo, 0L)) {\n\t\tif (_ttoi( szHttpInfo) == 200) { // 200 = OK\n\t\t\tlenHttpInfo = sizeof(szHttpInfo);\n\t\t\tif (HttpQueryInfo( hRequest, HTTP_QUERY_CONTENT_LENGTH,\n\t\t\t\t\tszHttpInfo, &lenHttpInfo, 0L)) {\n\t\t\t\tchar* resultData = (char*)LocalAlloc( LPTR, _ttoi( szHttpInfo));\n\t\t\t\tif (InternetReadFile( hRequest, resultData, _\n\t\t\t\t\t\tttoi( szHttpInfo), &lenHttpInfo)) {\n\t\t\t\t\t// Just for test purposes, we store the received XML into the \n\t\t\t\t\t// file resultData.xml (note the current working directory!)\n\t\t\t\t\tDeleteFile( _T(\"resultData.xml\"));\n\t\t\t\t\tHANDLE hf = CreateFile( _T(\"resultData.xml\"),\n\t\t\t\t\t\t\t\t\tGENERIC_ALL, 0, 0L, 1, 0x80L, 0);\n\t\t\t\t\tif (hf != INVALID_HANDLE_VALUE) {\n\t\t\t\t\t\tWriteFile( hf, resultData, lenHttpInfo, &lenHttpInfo, 0L);\n\t\t\t\t\t\tCloseHandle( hf);\n\t\t\t\t\t}\n\t\t\t\t\tLocalFree( resultData);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\nInternetCloseHandle( hRequest);\nInternetCloseHandle( hConnect);\nInternetCloseHandle( hSession);","type":"text"}]},{"type":"paragraph","content":[{"text":"You may use any XML library to retrieve the image data contained in ","type":"text"},{"text":"resultData","type":"text","marks":[{"type":"code"}]},{"text":" (or to prepare ","type":"text"},{"text":"requestData","type":"text","marks":[{"type":"code"}]},{"text":" to be sent). However, if you are still free to use a library we recommend ","type":"text"},{"text":"pugixml","type":"text","marks":[{"type":"em"}]},{"text":" (","type":"text"},{"text":"http://pugixml.org","type":"text","marks":[{"type":"link","attrs":{"href":"http://pugixml.org"}}]},{"text":"). ","type":"text"},{"text":"pugixml","type":"text","marks":[{"type":"em"}]},{"text":" 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++.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Examples","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"You can find the examples in the examples directory of the SDK installation.","type":"text"}]}],"version":1}

Browser not supported