Introduction

Help File Overview

DataWedge is a Motorola mobile device application that reads data from input devices and sends that data as keystrokes to the foreground application on the mobile device.

DataWedge runs on Windows CE 5, Windows Mobile 5 , Windows CE 6 and Windows Mobile 6 based Motorola mobile devices.

The DataWedge API provides the means to control the behavior of DataWedge from within a user's application. The API is exposed through an ActiveX object.

The help file is organized into three sections, providing the following information:

  • Standard API definitions
  • Design notes
  • Sample code

API Definitions

Syntax, return values, comments and examples are detailed for each property, method and event provided in the API. The API requirements are the same as those of DataWedge, summarized as follows.

OS Versions:

  • Windows® Mobile 5.0 and later
  • Windows CE 5.0 and later

ActiveX component:

  • DataWedgeAPI.dll (installed and registered as part of the DataWedge installation)

Design Notes

This section provides application notes that the developer may find helpful in implementing the API into their application.

Sample Code

Two sample code examples are provided showing how to use the API to start and stop DataWedge and get it's status.


API Definition

Overview

The DataWedge API provides interfaces to control the state of DataWedge. It allows user applications to control DataWedge and determine it's status. The API is exposed through an ActiveX object.

The DataWedge ActiveX object provides methods, properties and events. There are methods to start stop enable and disable DataWedge, properties to query the state and DataWedge version and OnStart, Onstop and OnData events which make it easy to add the ability to control DataWedge to one's application, with very little software development effort.


Status

status Property

The status property provides the current status of the DataWedge Application .

Syntax

long status;

Return Values

Return value of 0 indicates DataWedge is NOT running, Other values indicates that DataWedge application is running.

Status codes
0 - Stopped, DataWedge is not running
1 - Ready, DataWedge is running and ready to capture data
2 - Disabled, DataWedge is running but disabled
3 - Sleeping, DataWedge is running and has no active configuration
4 - Idle, DataWedge is Running but no capture devices are available

Examples

C++

    CComPtr srcObj;
srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
LONG lStatus;
srcObj->get_status(&lStatus);
...
//Do
 something based on the status
...
srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();

    if (DWCtrl.status
 != DataWedgeLib.DataWedgeState.Stopped)
{
//Do Something while running
}

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    function showstatus()
{
// check status poperty
if (DWCtrl.status
 != 0)
{
alert("DataWedge
 is running.");
}
else
{
alert("DataWedge
 is not running!");
}
}


Status

IDataWedgeAPI::DWVersion Property

DWVersion property returns the version of the DataWedge Application .

Syntax

BSTR DWVersion;

RetuReturn Values

DataWdge version in the form of <Major Version>.<Minor Version>.<Build Number> Ex: 3.3.10.

Examples

C++

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    CComBSTR bstrVersion;
    srcObj->get_DWVersion(&bstrVersion);
    ...

   //Do something based on the
    ...
version
    ...
      srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();

    MessageBox.Show(DWCtrl.DWVersion);

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    alert(DWCtrl.DWVersion);


Start

Start Method

The Start method starts DataWedge if it is not running.

Syntax

BOOL Start(void);

Comments

The Start method only invokes DataWedge.exe.

Note: It does not invoke DataWedge tray application and components to support browser based configuration.

Examples

C++

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    VARIANT_BOOL bResult;
    srcObj->Start(&bResult);
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();
    DWCtrl.Start();

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    function start()
     {
        DWCtrl.Start();
    }


Stop

Stop Method

The Stop method causes DataWedge to terminate if it is running.

SyntaxSyntax

 BOOL Stop(void);

Comments

The Stop method only causes DataWedge.exe to terminate.

Note: It does not stop DataWedge tray application or components to support browser based configuration.

Examples

C++

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    VARIANT_BOOL bResult;
       srcObj->Stop(&bResult);
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();
    DWCtrl.Stop();

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    function stop()
    {
        DWCtrlr.Stop();
      }


Enable

Enable Method

The Enable method causes DataWedge to enable if it is running and disabled.

Syntax

 BOOL Enable(BOOL bPersist);

Comments

The Enable method enable DataWedge if it is running and disabled . In Enabled state, DataWedge application is running and Data reading and processing (Data Routing) is taken place. If bPersist parameter is TRUE, DataWedge enabled flag is written to the DataWedge configuration and enable state is persisted for subsequent start of datawedge.

Examples

C++

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    VARIANT_BOOL bResult, bPersist=VARIANT_TRUE;
    srcObj->Enable(bPersist,&bResult);
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();
    DWCtrl.Enable(true);

HTML>

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    function enable()
    {
        DWCtrl.Enable(true);
    }


Disable

Disable Method

The Disable method causes DataWedge to disable if it is running and enabled.

Syntax

 BOOL Disable(BOOL bPersist);

Comments

The Disable method disable DataWedge if it is running and enabled . In disabled state, DataWedge application is running but data reading and processing (Data Routing) is stopped. If bPersist parameter is TRUE, DataWedge enabled flag is written to the DataWedge configuration and disable state is persisted for subsequent start of DataWedge.

Examples

C++

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    VARIANT_BOOL bResult, bPersist=VARIANT_TRUE;
    srcObj->Disable(bPersist,&bResult);
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();
    DWCtrl.Disable(true);

HTML>

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    function disable()
    {
        DWCtrl.Enable(true);
    }


OnStart

OnStart Event

OnStart event is fired when DataWedge application is started/launched.

Syntax

void OnStart(void);

Examples

C++

     #include "DataWedge.h"
    ......
    static _ATL_FUNC_INFO OnStartInfo = {CC_CDECL, VT_EMPTY, 0, {}};
    ......
    class CDWEventSink : public IDispEventSimpleImpl<1234, CDWEventSink, &__uuidof(_IDataWedgeAPIEvents)>
    {
        .....
        BEGIN_SINK_MAP(CDWEventSink)
            SINK_ENTRY_INFO(1234, __uuidof(_IDataWedgeAPIEvents), 1, OnStart, &OnStartInfo)
            ....
        END_SINK_MAP()
        ......
        HRESULT __stdcall OnStart(void)
        {
            ..... // On Start event handling
        }
        ......
    }

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    CDWEventSink eventSink=new CDWEventSink();
    eventSink->DispEventAdvise(srcObj);
    ...
    Receive events
    ...
    eventSink->DispEventUnadvise(srcObj);
    delete eventSink;
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();

    // Add OnStart Event Listener
    DWCtrl.OnStart += new DataWedgeLib._IDataWedgeAPIEvents_OnStartEventHandler(Started);

    private void Started()
    {
        DataWedgeStatus.Text = "DataWedge application Started";
    }

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

     <!-- OnStart Event Handler -->
    <script for="DWCtrl" event="OnStart">
        chkRunning.checked=true;
    </script>


OnStop

OnStop Event

OnStop event is fired when DataWedge application stops/terminates.

Syntax

void OnStop(void);

Examples

C++

     #include "DataWedge.h"
    ......
      static _ATL_FUNC_INFO OnStopInfo = {CC_CDECL, VT_EMPTY, 0, {}};
    ......
    class CDWEventSink : public IDispEventSimpleImpl<1234, CDWEventSink, &__uuidof(_IDataWedgeAPIEvents)>
    {
        .....
        BEGIN_SINK_MAP(CDWEventSink)
            ....
            SINK_ENTRY_INFO(1234, __uuidof(_IDataWedgeAPIEvents), 2, OnStop, &OnStopInfo)
            ....
        END_SINK_MAP()
        ......
        HRESULT __stdcall OnStop(void)
        {
            ..... // On Stop event handling
        }
        ......
    }

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    CDWEventSink eventSink=new CDWEventSink();
    eventSink->DispEventAdvise(srcObj);
    ...
    Receive events
    ...
    eventSink->DispEventUnadvise(srcObj);
    delete eventSink;
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();

    // Add OnStop event listener
    DWCtrl.OnStop += new DataWedgeLib._IDataWedgeAPIEvents_OnStopEventHandler(Stopped);

    private void Stopped()
    {
        DataWedgeStatus.Text = "DataWedge application Stopped";
    }

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

    <!-- OnStop Event Handler -->
    <script for="DWCtrl" event="OnStop">
        chkRunning.checked=false;
    </script>


OnData

OnData Event

OnData event is fired when DataWedge status is changed after starting and before stopping.

Syntax

void OnData(BSTR bstrData);

Comments

OnData Event is raised when DataWedge is started and it state is changed. This event can be used to identify intermidiate state changes while DataWedge is running. Parameter bstrData is reserved for future.

Examples

C++

     #include "DataWedge.h"
    ......
    static _ATL_FUNC_INFO OnDataInfo = {CC_CDECL, VT_EMPTY, 1, {VT_BSTR}};
    ......
    class CDWEventSink : public IDispEventSimpleImpl<1234, CDWEventSink, &__uuidof(_IDataWedgeAPIEvents)>
    {
        .....
        BEGIN_SINK_MAP(CDWEventSink)
            SINK_ENTRY_INFO(1234, __uuidof(_IDataWedgeAPIEvents), 3, OnData, &OnDataInfo)
            ....
        END_SINK_MAP()
        ......
        HRESULT __stdcall OnData(BSTR bstrData)
        {
            ..... // On Data event handling, Check status property to find current status
        }
        ......
    }

    CComPtr srcObj;
    srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    CDWEventSink eventSink=new CDWEventSink();
    eventSink->DispEventAdvise(srcObj);
    ...
            Receive events
    ...
            eventSink->DispEventUnadvise(srcObj);
    delete eventSink;
    srcObj.Release();

C#

    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();

    // Add OnStart Event Listener
    DWCtrl.OnData += new DataWedgeLib._IDataWedgeAPIEvents_OnDataEventHandler(DataReceived);

    private void DataReceived()
    {
        DataWedgeStatus.Text = "DataWedge Status:"+DWCtrl.status;
    }

HTML

    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

     <!-- OnData Event Handler -->
    <script for="DWCtrl" event="OnData">
        chkRunning.checked=true;
        if (DWCtrl.status==0) chkRunning.disabled=true;
        else chkRunning.disabled=false;
    </script>


Design Notes

In order for any of the sample to work, DataWedge must be installed and working on the mobile device. As part of it's installation, DataWedge installs and registers the ActiveX component refered to in this help file. No further intsallation on the part of the developer is required.

For clarity the code snippets do include any error checking. It is recommended the developer add appropriate error checking to his/her code.

HTML Application Guidelines

Although there are many ways of instantiating ActiveX objects in HTML/JavaScript, we recommend the following method as the DataWedge API events have been tried and tested using this method.

    <object id="NGDW" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59"></object>

C# Application Guidelines

The DataWedgeAPI type library is provided as part of DataWedge SDK, enabling C# developers to access the ActiveX component. This type library is available under the .\SDK\V1.0\Lib folder. Add the type library as a reference to your C# project to use the DataWedge API ActiveX component.


Examples

C++ Example

Please refer to the Samples\C++ for the complete C++ project for the bellow code sample.

#include "..\..\..\Include\DataWedge.h"
#include <atlbase.h>
#include <atlcom.h>

// DataWedge API event method descriptions
static _ATL_FUNC_INFO OnStartInfo = {CC_CDECL, VT_EMPTY, 0, {}};
static _ATL_FUNC_INFO OnStopInfo = {CC_CDECL, VT_EMPTY, 0, {}};

class CDWEventSink : public IDispEventSimpleImpl<1234, CDWEventSink, &__uuidof(_IDataWedgeAPIEvents)>
{

    BEGIN_SINK_MAP(CDWEventSink)
        SINK_ENTRY_INFO(1234, __uuidof(_IDataWedgeAPIEvents), 1, OnStart, &OnStartInfo)
        SINK_ENTRY_INFO(1234, __uuidof(_IDataWedgeAPIEvents), 2, OnStop, &OnStopInfo)
    END_SINK_MAP()

    HRESULT __stdcall OnStart(void)
    {
        MessageBox(NULL,TEXT("Started"),TEXT("DW Event"),0);
        return S_OK;
    }

    HRESULT __stdcall OnStop(void)
    {
        MessageBox(NULL,TEXT("Stopped"),TEXT("DW Event"),0);
        return S_OK;
    }
}

CComPtr srcObj;

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPTSTR lpCmdLine, int nCmdShow)
{

        CoInitializeEx(NULL,0);
    CComPtr srcObj;
        srcObj.CoCreateInstance(OLESTR("DataWedge.API"));
    CDWEventSink eventSink=new CDWEventSink();
    eventSink->DispEventAdvise(srcObj);

    while (GetMessage(&msg, NULL, 0, 0))
    {
           if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg)) {
          TranslateMessage(&msg); DispatchMessage(&msg);
       }
    }

               eventSink->DispEventUnadvise(srcObj);
    delete eventSink;
    srcObj.Release();
    CoUninitialize();
    return 0;
}

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    VARIANT_BOOL bResult;
    int wmId, wmEvent;

    switch (message) {
      case WM_COMMAND:
         wmId = LOWORD(wParam);
         wmEvent = HIWORD(wParam);
         switch (wmId) {
           case IDM_OK:
             SendMessage (hWnd, WM_CLOSE, 0, 0);
             break;
                        case IDM_START:
             srcObj->Start(&bResult);
             break;
                        case IDM_STOP:
             srcObj->Stop(&bResult);
             break;
                        case IDM_ENABLE:
             srcObj->Enable(VARIANT_TRUE,&bResult);
             break;
                        case IDM_DISABLE:
             srcObj->Disable(VARIANT_TRUE,&bResult);
             break;
                        case IDM_GETSTATUS:
             GetStatusText(g_szTemp);
             break;
          }
                               return DefWindowProc(hWnd, message, wParam, lParam);
     }
}

C# Example

Please refer to the Samples\C# for the complete C# project for the bellow code sample.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

namespace CShartDWAPISample
{
  public partial class Form1 : Form
  {
    // Create an instance of Datawedge API Interface
    private DataWedgeLib.DataWedgeAPIClass DWCtrl = new DataWedgeLib.DataWedgeAPIClass();

    public Form1()
    {
      InitializeComponent();
      // Add OnStart Event Listener
      DWCtrl.OnStart += new DataWedgeLib._IDataWedgeAPIEvents_OnStartEventHandler(Started);
      // Add OnStop event listener
      DWCtrl.OnStop += new DataWedgeLib._IDataWedgeAPIEvents_OnStopEventHandler(Stopped);
      // Check Status and Update Initial Status
      if (DWCtrl.status> 0)
      {
        Started();
      }
      else
      {
        Stopped();
      }
    }

    private void btnStart_Click(object sender, EventArgs e)
    {
      if (DWCtrl.status == 0)
      {
        // Call Start Method
        DWCtrl.Start();
      }
    }

    private void btnStop_Click(object sender, EventArgs e)
    {
      if (DWCtrl.status != 0 )
      {
        // Call Stop Method
        DWCtrl.Stop();
      }
    }

    private void btnEnable_Click(object sender, EventArgs e)
    {
      if (DWCtrl.status != 0 )
      {
        // Call Enable Method
        DWCtrl.Enable(checkBoxPersist.Checked);
      }
    }

    private void btnDisable_Click(object sender, EventArgs e)
    {
      if (DWCtrl.status != 0 )
      {
        // Call Disable Method
        DWCtrl.Disable(checkBoxPersist.Checked);
      }
    }

    private void Started()
    {
       DataWedgeStatus.Text = "DataWedge application Started";
    }

    private void Stopped()
    {
       DataWedgeStatus.Text = "DataWedge application Stopped";
    }
  }
}

HTML/JavaScript Example

Please refer to the Samples\HTML for the complete HTML file for the below code sample.

<html>
  <head>
    <title>DataWedge API - Web Sample</title>
    <script>
      function start()
      {
        // Call Start Method
        DWCtrl.Start();
      }
      function stop()
      {
        // Call Stop Method
        DWCtrl.Stop();
      }
      function enable()
      {
        // Call Enable Method
        DWCtrl.Enable(true);
      }
      function disable()
      {
        // Call Disable Method
        DWCtrl.Disable(true);
      }
      function showstatus()
      {
        // check status poperty
        if (DWCtrl.status!=0)
        {
          alert("DataWedge is running.");
        }
        else
        {
          alert("DataWedge is not running!");
        }
      }

      // Set Initial Status
      function InitAPI(msg)
      {
        // check status poperty
        if (DWCtrl.status!=0)
        {
          chkRunning.checked=true;
        }
      }
    </script>

    <!-- OnStart Event Handler -->

    <script for="DWCtrl" event="OnStart">
      chkRunning.checked=true;
    </script>

    <!-- OnStop Event Handler -->

    <script for="DWCtrl" event="OnStop">
      chkRunning.checked=false;
    </script>
  </head>
  <body onload="InitAPI()">
    <h2>DataWedge API - Web Sample</h2>
    <!-- Initialize DataWedge.API ActiveX Object -->
    <object id="DWCtrl" height=0 width=0 classid="CLSID:7292BC27-A53D-4C1E-92FF-D234BBEB0E59">
    </object>

    <table>
      <tr>
        <td colspan=2>
          <!-- DataWedge Status check box -->
          <input type="checkbox" name="chkRunning" />Running<br />
        </td>
      </tr>
      <tr>
        <td>
          <!-- Start DataWedge by selecting the button -->
          <input type="button" name="btnStart" onclick="start()" value="Start" />
        </td>
        <td>
          <!-- Stop DataWedge by selecting the button -->
          <input type="button" name="btnStop" onclick="stop()" value="Stop" /><br />
        </td>
      </tr>
      <tr>
        <td>
          <!-- Enable DataWedge by selecting the button -->
          <input type="button" name="btnEnable" onclick="enable()" value="Enable" />
        </td>
        <td>
          <!-- Disable DataWedge by selecting the button -->
          <input type="button" name="btnDisable" onclick="disable()" value="Disable" /><br />
        </td>
      </tr>
      <tr>
        <td colspan="2">
          <!-- Check current status by selecting the button -->
          <input type="button" name="btnStatus" onclick="showstatus()" value="Status" /><br />
        </td>
      </tr>
    </table>
  </body>
</html>