C-Bus Module Windows DLL Usage Guide
C-Bus Module Windows DLL Usage Guide
C-Bus Module Windows DLL Usage Guide
Commercial In Confidence
The following document is issued commercial in confidence and cannot be reproduced or transmitted to
unauthorised personnel without the expressed written permission of Clipsal Integrated Systems Pty Ltd.
Clipsal Australia Pty Ltd Document: CBUS-CBDLL
ABN 27 007 873 529 Issue: 2.6
Date: 18 November 2008
C-Bus Module Windows DLL Usage Guide
CHANGE HISTORY
1 Purpose............................................................................................................... 4
2 Scope.................................................................................................................. 4
3 References.......................................................................................................... 4
4 Introduction.......................................................................................................... 4
5 Installation and Removal ..................................................................................... 5
5.1 Installing..................................................................................................... 5
5.2 Removing ................................................................................................... 5
5.3 File locations .............................................................................................. 5
6 C-Bus Module Properties..................................................................................... 6
7 Additional functions supplied with DLL................................................................. 7
7.1 Enumerating the Communications Ports..................................................... 7
7.2 Opening a Com Port................................................................................... 7
7.3 Closing the Comm Port .............................................................................. 7
8 C-Bus DLL Usage................................................................................................ 8
8.1 Using the DLL with Borland C-Builder ........................................................ 8
8.1.1 General notes ............................................................................... 8
8.1.2 Examples...................................................................................... 8
8.1.2.1 Determining Com Ports .............................................. 8
8.1.2.2 Registering Event Handlers ........................................ 8
8.1.2.3 Calling DLL Functions................................................. 9
8.1.2.4 Handling C-Bus Module Errors ................................... 9
8.2 Using the DLL with Borland Delphi ........................................................... 10
8.2.1 General notes ............................................................................. 10
8.2.2 Examples.................................................................................... 10
8.2.2.1 Determining Com Ports ............................................ 10
8.2.2.2 Opening Com Ports .................................................. 10
8.2.2.3 Calling DLL Functions/Procedures............................ 10
8.2.2.4 Including Definition Files........................................... 10
9 Copyright........................................................................................................... 11
1 PURPOSE
This document defines the use of the C-Bus DLL for Win32 platforms.
The complete functions and interface to the C-Bus Module are defined in the C-Bus
Module Interface Specification.
2 SCOPE
The contents of this document apply to version 3 of the C-Bus Module and C-Bus DLL.
3 REFERENCES
C-Bus Module Interface Specification CBUS-CBMIS
4 INTRODUCTION
The C-Bus Module provides a general-purpose library for software that needs a C-Bus
interface.
The C-Bus DLL is made by adding a small number of additional services to support
PC/Windows serial ports, and then compiling to a Windows Dynamic Link Library.
The device in which the C-Bus DLL is used is generally an embedded system,
communicating with C-Bus via a PC Interface as shown in Figure 1. The C-Bus DLL
provides a user-friendly interface between the User Application Firmware and the C-
Bus PC Interface.
User Device
User C-Bus PC
Application DLL Interface C-Bus
Firmware
5.1 Installing
The C-Bus Module for Windows is supplied as a self-installing setup program. To
install, just double-click the supplied program setup.exe.
5.2 Removing
To remove, open the Control Panel and select Add/Remove Programs. Select the item
"C-Bus Module v3" from the list, and click the Remove button.
What Where
Documentation (PDF and text C:\CLIPSAL\C-Bus Module\doc
format)
Windows DLL C:\WINNT\SYSTEM32
Or
C:\WINDOWS\SYSTEM32
C header files C:\CLIPSAL\C-Bus Module\include
This function that inspects the registry to determine what comm ports are available.
The function returns a count of the number of com ports, and fills in the supplied array
with null-terminated strings corresponding to the ports.
The method used to determine the available comm ports may not work with some
operating systems. In this case you will need to supply your own function to do this.
When called, this function closes the com port if open, and stops the 100 ms timer.
This effectively shuts down the C-Bus Module. If does not unload the DLL.
1
If these functions are not used, then equivalents will need to be written and used instead.
8.1.2 Examples
The following examples are snippets of code from working applications and are here
only as a guide.
//----------------------------------------------------------------
// Process incoming set level messages. Match the application and
// group before proceeding
//----------------------------------------------------------------
void My_event_handler(byte application,
byte group,
byte level,
byte rate)
{
...
}
if (cbus_if_get_last_error() != CBM_SUCCESS)
{
sprintf(Msg, "CBM error = %02x", cbus_if_get_last_error());
Application->MessageBox(Msg, "Set level error", IDOK);
}
8.2.2 Examples
The following examples are snippets of code from working applications and are here
only as a guide.
var
Num_Coms: Integer;
Ports: TArrayChar; // Array of chars to store com port strings
uses
Windows, Messages, SysUtils, Classes, Graphics, Controls,
Forms, Dialogs, StdCtrls, Spin, ExtCtrls, jpeg,
cbus_pas_defs, cbus_lighting_defs, ComCtrls, cbus_comms;
9 COPYRIGHT
The C-Bus Module is NOT free software, and is NOT open source. The C-Bus Module
is copyright (c) 2005, 2008 Clipsal Australia Pty Ltd.