DALI User Manual: C Client

Diamond Systems provides a simple cross platform C client API which can be used to communicate with the DALI server over the Internet. This software hides details of SOAP and network communication and allows the user to write software just as if they were using a driver to communicate with an I/O board on the local system.

DALI Win32 developers can use a higher level API with Windows specific features instead. See the Windows Client section of this manual for more information

Example Program

#include <stdio.h>
#include "dalic.h"

int main(int argc, char *argv[])
{
    DALIENV dali;
    DALIADSETTINGS adsettings;
    int channel = 0;
    int value;

    DALIInit(&dali);
    dali.service = "http://myhost.example.com:8444/dali/soap/demo";
    adsettings.range = 5;
    adsettings.gain = 1;
    adsettings.polarity = DALI_BIPOLAR;

    if ( DALIADSample(&dali, channel, &adsettings, &value) )
        printf("Error: %s\n", dali.last_error);
    else
        printf("Sample: %d\n", value);

    DALIFree(&dali);
}

Compiling the Example Program

Copy the above program to a file dalidemo.c. Edit the dali.service initialization to point to the IP address where the DALI server is running. Edit the string demo at the end of the URL to the name of a board you have configured for your DALI server. See the Board Configuration section of the manual for more information.

Instructions for Linux

• gcc -o dalidemo dalidemo.c -I/usr/local/dali/include -L/usr/local/dali/lib/linux/ -ldaliclient -pthread
• type ./dalidemo to run.

Instructions for QNX

• gcc -o dalidemo dalidemo.c -I/opt/dali/include -L/opt/dali/lib/linux/ -ldaliclient -pthread
• type ./dalidemo to run.

Instructions for Windows

• Open Microsoft Visual C++.
• Select File->New.. and create a new Windows Console Application [empty] named dalidemo.
• Add dalidemo.c to the 'Source Files' project listing.
• Press Alt+F7 for the Project Settings dialog and go to the C/C++ tab.
• Select Code Generation from the Category dropdown and select Debug Multithreaded DLL from the run-time library dropdown.
• Go to the Link tab.
• Add dalic.lib and ws2_32.lib to the 'Object/library modules:' edit field.
• Press the OK button.
• Press F7 to build the program. A warning will appear because you are building a debug version of dalidemo, but dalic.lib uses the release version of msvcrt. This can be ignored.
• Press Ctrl+F5 to run the program in debug mode with pause enabled.

The dalidemo program will connect to the DALI server and board specified in the dali.service string and request an AD sample.

OpenSSL Support

The C/C++ Client includes support for encrypted network communication using OpenSSL. To use this you will have to have OpenSSL installed on your client systems. This software is available from OpenSSL.org. If you will be using OpenSSL in your DALI application you need to link with the SSL enabled client library. This is called "dalic-ssl.a" on Linux and QNX, and "dalic-ssl.lib" on Windows.

Once you've linked with the SSL enabled library you just have to change your dali.service parameters to use the "https" protocol instead of "http".

A Note on SOAP Service URLs

Several data structures are used to specify a service URL. This is a SOAP endpoint which specifies a DALI server on the network and a service on that server. It has the following format:

PROTOCOL://HOSTNAME:PORT/dali/soap/BOARDNAME

PROTOCOL is "http" for plain text or "https" for SSL encrypted communications. SSL puts a much larger resource strain on the server so it should only be used for requests which contain sensitive information.

HOSTNAME is the valid DNS hostname or IP address of the DALI server. Use "127.0.0.1" to request a connection to the same machine the client software is running on.

PORT is the TCP/IP port the DALI server is listening on. By default this is 8444.

/dali/soap/ is text which should not be modified. It indicates to the DALI server that this is a request for its services.

BOARDNAME is the unique name of a board on the DALI server. See the Board Configuration section of this manual for more information.

DALI Client Data Structures

The DALI Client uses two data structures in the requests sent to the DALI server, plus a number of other data structures for presenting the data returned by the server.

Initialization and Deinitialization Functions

A/D Functions

D/A Functions

Digital I/O Functions

Configuration Query Functions

Misc Utility Functions

Alarm Functions

DALI alarms let the client specify a condition and request asynchronous notification when this condition becomes true. For example, the client can request that the server contact it when an analog value exceeds a specified range.

This is implemented with a kind of SOAP callback, in which the server temporarily becomes a SOAP client and connects back to the DALI application which is waiting to receive this connection. This is only possible if direct TCP/IP connections from the server to the client are possible. For example, network firewalls or NAT security will prevent this feature from working.

The DALIALARM struct specifies the parameters of the alarm. This struct is documented earlier in data structures section of this manual. The notify_url specifies a SOAP service URL which the DALI server will contact when the alarm becomes true. In the case of DALI this URL should always be in the form of http://yourhost:8444/dali/soap/.

More information on the internals of DALI alarm is available in the server section of this manual.