xPL SDK
4.3.0
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.
When creating a project for an xPL-enabled application, the following settings must be applied:
- Add the SDK src folder to the list of additional include directories. If the SDK was installed at the default location, this will be "c:\program files\xPL\xPLSDK\src"
- The SDK uses Winsock 2 and MSXML, so you must include ws2_32.lib and msxml2.lib in the list of libraries to link with.
- If you wish to use the EventLog class, then also include event.res in the list of libraries, and copy the event.res file from one of the sample projects into your own project folder.
- Any application built with the SDK will be multi-threaded, so make sure that the multi-threaded versions of the runtime libraries are selected.
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:
- Create a communications object. This will be used by the xplDevice to talk to other xPL enabled applications. Currently the only type of communications object supported is xplUDP, which handles the sending and receiving of data using the UDP protocol over a LAN or the Internet.
- Create the xplDevice. This object encapsulates all the basic xPL functionality, including configuration via xPLHal.
- Create your xplConfigItems. A config item represents a variable, which can be modified by the user in xPLHal, and is saved to the registry or configuration file to be reloaded when the application next starts.
- Initialise the xplDevice. This will cause any saved configuration to be loaded and applied to the config items. The config event will be signalled to let your application know that config items have been changed.
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.
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.
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.
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.
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.
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.
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.
Assistance with all xPL issues can be obtained by posting a message to the xPL Forums (http://xpl-home.org/forums)
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
1.5.1-p1