DLN API is designed for a maximum flexibility. It allows to build simple applications that interface a single device with only a few lines of code. It also provides a lot of functions to build more complex applications, which can interface several adapters simultaneously, even if they are connected to different computers. There is a number of approaches to distinguish between different adapters, different types of adapters, and check what subset of the functionality the particular adapter supports.
We will cover all the details in the following subsections. Some information may seem to be complex in the beginning. Feel free to skip it and move to the next chapter. Most of the applications need to call a single function to establish a connection with the DLN series adapter - DlnOpenUsbDevice() (or DlnOpenBleDevice(), DlnOpenTcpDevice(), etc.).
When the device is opened, the DLN library allocates resources required to maintain the connection and associates a device handle with this device. Most of the functions in the dln.dll library expects this handle to be passed as the first parameter. It is used to identify the adapter.
You can open the same adapter several times by calling one of the DlnOpenXXX() functions. We do not recommend this approach and in most cases changing the application architecture eliminates the necessity to open the same hardware repeatedly. Each time you call one of those functions, a new handle is associated with the same hardware and additional resources to manage this handle are allocated. If application design requires you to open the same device multiple times, it is important to close all handles when you don't need them. The C++ programmers can use our C++11-like unique_hdln class to manage the device handle.
The device handle is represented by the HDLN type which is defined in the dln.h file as:
- C/C++
typedef uint16_t HDLN;
The allocated resources are automatically cleared up when the application terminates. Nevertheless, it is a good practice to explicitly close the device handle by calling the DlnCloseHandle() function.