xPL SDK

4.3.0

Using the SDK

Installation

The xPL SDK is supplied packaged as an MSI file. Simply double click on the xPLSDK.msi file and follow the on screen instructions. Be sure to note the location you choose to install the SDK, since you will need this when configuring your projects.

Project Configuration

When creating a project for an xPL-enabled application, the following settings must be applied:

Adding xPL support to your program

Creating an object of the xplDevice class is all that is required to provide generic xPL support. Once initialised, the xplDevice will run in its own thread, signalling events when an xPL message is received, or when the application configuration has changed.

The easiest method is to create your application by adapting one of the samples, but if that is not possible, the necessary steps for adding xPL support from scratch are as follows:

Sending xPL Messages

To send an xPL message is a simple matter of creating an xplMsg object through a call to the static method xplMsg::Create, adding the message body elements and then passing it in a call to xplDevice::SendMessage.

Receiving xPL Messages

When xPL messages are received they are stored in a queue and an event is signalled. A handle to this event can be obtained through a call to xplDevice::GetMsgEvent. The next message in the queue can be obtained by calling xplDevice::GetMsg. Once all the messages have been removed from the queue, the event returns to an unsignalled state. When the application is finished with a message, it should delete it by calling xplMsg::Release.

Configuration

When a user changes the application's configuration (usually via xPLHal), the xPL device will process the message and update the values of the config items. An event is then signalled to let your application know that its configuration may have changed. A handle to this event can be obtained by calling xplDevice::GetConfigEvent. When the event is signalled, your application should check the values of each of its config items, and take appropriate action for any that have changed.

Note that the config event, unlike all the others, is an auto-reset event.

Main Thread

With all the initialisation completed, your application is free to do its own thing. Since the xPL side of things is being handled in other threads, your application can block - for example, waiting for a comm port event to be signalled. It is important to include the message and config events from xplDevice when blocking. This will enable the application to respond in a timely manner.

In case you need to pause operations (for example, if your application is a Windows service), you should use the Pause and Resume methods provided by the xplDevice.

Closing down

Simply call the static method xplDevice::Destroy, with the pointer to your xplDevice object. The method will also deal with cleaning up and destroying any xplConfigItems that were created before Init was called.


Samples

The SDK package includes skeleton code for creating xPL-enabled applications. Code is provided for three types of application - a Windows service, a Windowed application, and a console application. The Windows service is quite flexible - it will run as a console application if no command line parameters are passed to it. This makes it possible to ship one application that will run on all versions of Windows, whether or not there is support for services. It is also useful for debugging.

The full source code for the W800RF32 service is also provided as a real life example of using the SDK to build a complete xPL application.


Licensing

In a change from the old xPLCppLib, the xPL SDK is now licensed for use under far more generous terms than allowed by the GNU public licence. The new licence is based on the MIT licence and allows completely free use of the software even in commercial for-profit applications. The licence only covers the xPL SDK. It does not conflict with any less generous terms that may be applied to software built using the xPL SDK.


Support

Assistance with all xPL issues can be obtained by posting a message to the xPL Forums (http://xpl-home.org/forums)


References

The xPL Project home page, including the protocol documentation is at http://www.xplproject.org.uk
Generated on Sun Jan 21 14:30:23 2007 for xPL SDK by  doxygen 1.5.1-p1