Generic Functions

You can use the following functions to establish communication with DLN series adapters, identify them using ID and serial numbers, and obtain version information for all components involved in the communication.

Rating:

DlnConnect() Function

The DlnConnect() function establishes the connection to the DLN server.

Syntax

C/C++

DLN_RESULT DlnConnect(
   const char* host,
   uint16_t port
);

Parameters

host: A server to which the function establishes connection. This value can be a URL (e.g., example.com), or an IP address (e.g., 127.0.0.1). To connect to a server launched on the same computer, you can use the predefined "localhost" value as a host name.
port: A port number of the DLN server. If you use DLN-series device on the same computer use "9656" port value or the predefined DLN_DEFAULT_SERVER_PORT constant.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully established connection to the DLN server.

Remarks

The DlnConnect() function is the dln_generic.h file.

DlnDisconnect() Function

The DlnDisconnect() function closes the connection to the specified DLN server.

Syntax

C/C++

DLN_RESULT DlnDisconnect(
   const char* host,
   uint16_t port
);

Parameters

host: A server to which the function closes connection. This value can be a URL (e.g., example.com), or an IP address (e.g., 127.0.0.1). To close the connection to a server, launched on the same computer, you can use the predefined "localhost" value as a host name.
port: A port of the DLN server.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully closed connection to the DLN server.
DLN_RES_NOT_CONNECTED (0xA1): Connection with the specified server is not established.

Remarks

The DlnDisconnect() function is defined in the dln_generic.h file.

DlnDisconnectAll() Function

The DlnDisconnectAll() function closes connections to all servers at once.

Syntax

C/C++

DLN_RESULT DlnDisconnectAll(
);

Return Value

DLN_RES_SUCCESS (0x00): The function successfully closed connection to all DLN servers.
DLN_RES_NOT_CONNECTED (0xA1): Connections with no servers are established.

Remarks

The DlnDisconnectAll() function is defined in the dln_generic.h file.

DlnGetDeviceCount() Function

The DlnGetDeviceCount() function retrieves the total number of DLN devices available. If connection is established with several DLN servers, this function will return the total number of DLN adapters, connected to all servers.

Syntax

C/C++

DLN_RESULT DlnGetDeviceCount(
   uint32_t* deviceCount
);

Parameters

deviceCount: A pointer to an unsigned 32-bit integer that receives the total number of available DLN-series adapters.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the number of available DLN devices.

Remarks

The DlnGetDeviceCount() function is defined in the dln_generic.h file.

DlnOpenDevice() Function

The DlnOpenDevice() function opens the specified device. This function uses an index number of the device. This number is randomly system-assigned to each connected device. It cannot be used to identify the device. If you need to open a specific device, use the DlnOpenDeviceBySn() or DlnOpenDeviceById() functions.

Syntax

C/C++

DLN_RESULT DlnOpenDevice(
   uint32_t deviceNumber,
   HDLN* deviceHandle
);

Parameters

deviceNumber: A number of the device.
deviceHandle: A pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device.
DLN_RES_NOT_CONNECTED (0xA1): The library is not connected to any server.
DLN_RES_MEMORY_ERROR (0x86): Not enough memory to process this command.
DLN_RES_HARDWARE_NOT_FOUND (0x81): Invalid device number. To check the number of available devices, call the DlnGetDeviceCount() function.
DLN_RES_DEVICE_REMOVED (0x8E): The device was disconnected during the function execution.

Remarks

The DlnOpenDevice() function is defined in the dln_generic.h file.

DlnOpenDeviceById() Function

The DlnOpenDeviceById() function opens the device defined by its ID number.

Syntax

C/C++

DLN_RESULT DlnOpenDeviceById(
   uint32_t id,
   HDLN* deviceHandle
);

Parameters

id: An ID of the DLN-series adapter.
deviceHandle: A pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device defined by ID.

Remarks

You can change the device ID by using the DlnSetDeviceId() function.

The DlnOpenDeviceById() function is defined in the dln_generic.h file.

DlnOpenDeviceBySn() Function

The DlnOpenDeviceBySn() function opens the device defined by its serial number. A device serial number is factory-assigned and cannot be changed.

Syntax

C/C++

DLN_RESULT DlnOpenDeviceBySn(
   uint32_t sn,
   HDLN* deviceHandle
);

Parameters

sn: The serial number of the DLN-series adapter.
deviceHandle: A pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device defined by serial number.

Remarks

The DlnOpenDeviceBySn() function is defined in the dln_generic.h file.

DlnOpenDeviceByHwType() Function

The DlnOpenDeviceByHwType() function opens the DLN-series device defined by its type.

Syntax

C/C++

DLN_RESULT DlnOpenDeviceByHwType(
    DLN_HW_TYPE hwType, 
    HDLN *deviceHandle
);

Parameters

hwType

The DLN_HW_TYPE variable that represents the hardware type value. The following values are available:

DLN_HW_TYPE_DLN5
DLN_HW_TYPE_DLN4M
DLN_HW_TYPE_DLN4S
DLN_HW_TYPE_DLN3
DLN_HW_TYPE_DLN2
DLN_HW_TYPE_DLN1

deviceHandle

Pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device defined by its hardware type.

Remarks

The DlnOpenDeviceByHwType() function is defined in the dln_generic.h file.

DlnOpenUsbDevice() Function

The DlnOpenUsbDevice() function opens the device connected to the USB port of local PC. Use this function if your application is intended to work with single device. It cannot be used to select the specific device when multiple devices are connected. If you need to open a specific device, use the DlnOpenUsbDeviceBySn() or DlnOpenUsbDeviceById() functions.

Syntax

C/C++

DLN_RESULT DlnOpenUsbDevice(
   HDLN* deviceHandle
);

Parameters

deviceHandle: A pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device.
DLN_RES_NOT_CONNECTED (0xA1): In case of server-based interface, the library is not connected to a local server.
DLN_RES_MEMORY_ERROR (0x86): Not enough memory to process this command.
DLN_RES_HARDWARE_NOT_FOUND (0x81): No devices are connected to the USB port of local PC.
DLN_RES_DEVICE_REMOVED (0x8E): The device was disconnected during the function execution.

Remarks

The DlnOpenUsbDevice() function is defined in the dln_generic.h file.

DlnOpenUsbDeviceById() Function

The DlnOpenUsbDeviceById() function opens the device, connected to the USB bus of the local computer, with ID number equal to the value passed in the id parameter.

Syntax

C/C++

DLN_RESULT DlnOpenUsbDeviceById(
   uint32_t id,
   HDLN* deviceHandle
);

Parameters

id: An ID of the DLN-series adapter.
deviceHandle: A pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device specified by ID.

Remarks

You can change the device ID by using the DlnSetDeviceId() function.

The DlnOpenUsbDeviceById() function is defined in the dln_generic.h file.

DlnOpenUsbDeviceBySn() Function

The DlnOpenUsbDeviceBySn() function opens the device, connected to the USB bus of the local computer, with serial number equal to the value passed in the sn parameter. A device serial number is factory-assigned and cannot be changed.

Syntax

C/C++

DLN_RESULT DlnOpenUsbDeviceBySn(
   uint32_t sn,
   HDLN* deviceHandle
);

Parameters

sn: The serial number of the DLN-series adapter.
deviceHandle: A pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device defined by serial number.

Remarks

The DlnOpenUsbDeviceBySn() function is defined in the dln_generic.h file.

DlnOpenUsbDeviceByHwType() Function

The DlnOpenUsbDeviceByHwType() function opens the DLN-series device, connected to the USB bus of the local computer, defined by its type.

Syntax

C/C++

DLN_RESULT DlnOpenUsbDeviceByHwType(
    DLN_HW_TYPE hwType, 
    HDLN *deviceHandle
);

Parameters

hwType

The DLN_HW_TYPE variable that represents the hardware type. The following values are available:

DLN_HW_TYPE_DLN5
DLN_HW_TYPE_DLN4M
DLN_HW_TYPE_DLN4S
DLN_HW_TYPE_DLN3
DLN_HW_TYPE_DLN2
DLN_HW_TYPE_DLN1

deviceHandle

Pointer to the HDLN type variable that receives the device handle.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully opened the DLN device defined by its hardware type.

Remarks

The DlnOpenUsbDeviceByHwType() function is defined in the dln_generic.h file.

DlnCloseHandle() Function

The DlnCloseHandle() function closes the handle to an opened DLN-series adapter (stream).

Syntax

C/C++

DLN_RESULT DlnCloseHandle(
   HDLN handle
);

Parameters

handle: A handle to the DLN-series adapter.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully closed the handle to an opened DLN adapter.

Remarks

The DlnCloseHandle() function is defined in the dln_generic.h file.

DlnCloseAllHandles() Function

The DlnCloseAllHandles() function closes handles to all opened DLN-series adapters and streams.

Syntax

C/C++

DLN_RESULT DlnCloseAllHandles(
 );

Return Value

DLN_RES_SUCCESS (0x00): The function successfully closed all opened DLN adapters.

Remarks

The DlnCloseAllHandles() function is defined in the dln_generic.h file.

DlnGetVersion() Function

The DlnGetVersion() function retrieves the following data about the DLN-series adapter:

Hardware type - the type of the device (for example, DLN-4M).
Hardware version - the version of the hardware, used in the device.
Firmware version - the version of the firmware, installed in the device.
Server version - the version of the server.
Library version - the version of the DLN-library.

Syntax

C/C++

DLN_RESULT DlnGetVersion(
    HDLN handle,
    DLN_VERSION* version
 );

Parameters

handle: A handle to the DLN-series device.
version: A pointer to a DLN_VERSION structure that receives information about the DLN adapter version.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the version information of the DLN adapter.

Remarks

The DlnGetVersion() function is defined in the dln_generic.h file.

DlnGetHardwareType() Function

The DlnGetHardwareType() function determines the type of the connected DLN device.

Syntax

C/C++

DLN_RESULT DlnGetHardwareType
(
    HDLN handle, 
    DLN_HW_TYPE *type
);

Parameters

handle: A handle to the DLN-series adapter.
type: The pointer to the DLN_HW_TYPE type variable that receives the device type.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the type of the DLN adapter.

Remarks

The DlnGetHardwareType() function is defined in the dln_generic.h file.

DlnGetDeviceId() Function

The DlnGetDeviceId() function retrieves the device ID number.

Syntax

C/C++

DLN_RESULT DlnGetDeviceId(
    HDLN handle,
    uint32_t* id
 );

Parameters

handle: A handle to the DLN-series device.
id: A pointer to an unsigned 32-bit integer that receives the ID number.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the DLN device ID.

Remarks

You can change the device ID number using the DlnSetDeviceId() function.

The DlnGetDeviceId() function is defined in the dln_generic.h file.

DlnSetDeviceId() Function

The DlnSetDeviceId() function sets a new ID number to the DLN-series adapter.

Syntax

C/C++

DLN_RESULT DlnSetDeviceId(
   HDLN handle,
   uint32_t id
);

Parameters

handle: HDLN type variable. A handle to the DLN-series adapter.
id: Unsigned 32-bit integer type variable. An id number to be set.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully specified the DLN device ID.

Remarks

The DlnSetDeviceId() function is defined in the dln_generic.h file.

DlnGetDeviceSn() Function

The DlnGetDeviceSn() function retrieves the device serial number. A serial number is factory-assigned and cannot be changed.

Syntax

C/C++

DLN_RESULT DlnGetDeviceSn(
    HDLN handle,
    uint32_t* sn
);

Parameters

handle: A handle to the DLN-series device.
sn: A pointer to the unsigned 32-bit integer that receives the device serial number.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the serial number of the DLN adapter.

Remarks

The DlnGetDeviceSn() function is defined in the dln_generic.h file.

DlnGetPinCfg() Function

The DlnGetPinCfg() function retrieves the current configuration of the specified pin of the DLN adapter.

Syntax

C/C++

DLN_RESULT DlnGetPinCfg(
    HDLN handle, 
    uint16_t pin, 
    DLN_PIN_CFG *cfg
);

Parameters

handle: A handle to the DLN-series device.
pin: A pin number.
cfg: A pointer to the DLN_PIN_CONFIG structure that receives the pin configuration.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the pin configuration.
DLN_RES_INVALID_PIN_NUMBER (0xAB): The pin number is not valid.

Remarks

The DlnGetPinCfg() function is defined in the dln_generic.h file.

DlnRegisterNotification() Function

The DlnRegisterNotification() function registers notification settings.

Syntax

C/C++

DLN_RESULT DlnRegisterNotification(
    HDLN handle,
    DLN_NOTIFICATION notification
 );

Parameters

handle: A handle to the DLN-series adapter. You may specify either the handle to a specific device (stream) or the HDLN_ALL_DEVICES value to apply the notification setting for all the devices (streams).
notification: Defines the notification settings. The settings are passed as the DLN_NOTIFICATION structure.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully registered notification settings.

Remarks

The DlnRegisterNotification() function is defined in the dln_generic.h file.

DlnUnregisterNotification() Function

The DlnUnregisterNotification() function unregisters notification settings.

Syntax

C/C++

DLN_RESULT DlnUnregisterNotification(
   HDLN handle
);

Parameters

handle: A HDLN type handle to the DLN-series adapter (stream). You may specify either the handle to a specific device (stream) or the HDLN_ALL_DEVICES value to unregister notification setting for all the devices (streams).

Return Value

DLN_RES_SUCCESS (0x00): The function successfully unregistered notification settings.

Remarks

The DlnUnregisterNotification() function is defined in the dln_generic.h file.

DlnGetMessage() Function

The DlnGetMessage() function retrieves a message (response or event) sent by the device.

Syntax

C/C++

DLN_RESULT DlnGetMessage(
    HDLN handle,
    void* messageBuffer,
    uint16_t messageSize
 );

Parameters

handle: A handle to the DLN-series adapter.
messageBuffer: A pointer to the buffer that receives the message information.
messageSize: The maximum number of bytes that can be retrieved.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the message.

Remarks

The DlnGetMessage() function is defined in the dln.h file.

DlnSendMessage() Function

The DlnSendMessage() function sends a specified message (an asynchronous command) to the device.

Syntax

C/C++

DLN_RESULT DlnSendMessage(
    void* message
 );

Parameters

message: A pointer to a variable that contains a message to be sent.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully sent the message.

Remarks

The DlnSendMessage() function is defined in the dln.h file.

DlnTransaction() Function

The DlnTransaction() function sends a synchronous command, waits for a response and returns the response details.

Syntax

C/C++

DLN_RESULT DlnTransaction(
   void* command,
   void* responseBuffer,
   uint16_t responseBufferSize
);

Parameters

command: A pointer to a variable that contains the command that should be sent.
responseBuffer: A pointer to the buffer that receives the response information.
responseBufferSize: The maximum number of bytes that can be retrieved.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully performed the transaction.

Remarks

The DlnTransaction() function is defined in the dln.h file.

DlnRestart() Function

The DlnRestart() function restarts the currently opened DLN-series device by its handle.

Syntax

C/C++

DLN_RESULT DlnRestart(
    HDLN handle
);

Parameters

handle: A handle to the DLN device.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully reset the specified DLN adapter.

Remarks

The DlnRestart() function is defined in the dln_generic.h file.

DlnGetCommandRestriction() Function

The DlnGetCommandRestriction() function retrieves the command restrictions under the current conditions. This allows to avoid errors when executing functions. For details, read Specific Command Restrictions.

Syntax

C/C++

DLN_RESULT DlnGetCommandRestriction(
    HDLN handle,
    DLN_MSG_ID msgId, 
    uint16_t entity, 
    DLN_RESTRICTION *restriction
);

Parameters

handle: A handle to the DLN device.
msgId: A code of the command. You can find command codes in header files of the corresponding module.
entity: A number of a pin or a port (depending on the entity used in the command).
restriction: A pointer to the DLN_RESTRICTION structure that receives the command restriction.

Return Value

DLN_RES_SUCCESS (0x00): The function successfully retrieved the command restriction.

Remarks

The DlnGetCommandRestriction() function is defined in the dln_generic.h file.