The communication with a device is performed by the use of messages. A message is a packet of data that is sent from the library to a device and vice versa. The DLN adapters utilize three types of messages:
commands;
responses;
events.
Here is a short comparison to make things more logical and simple.
| Name | Sender | Recepient | Description | |
Command | DLN_DO_SOME_ACTION_CMD | User application | Device | Contains an instruction to a device. |
Response | DLN_DO_SOME_ACTION_RSP | Device | User application | Contains information about some changes that took place. |
Event | DLN_SOMETHING_CHANGED_EV | Device | User application | Contains information about some changes that took place. |
Commands are sent from the user application to a device. They contain some instructions to the device. You may instruct the device to perform an action (for example, to change voltage on a pin) or to configure the settings of the device. Each command has corresponding response.
A response is sent from the device to the user application after a command execution. A response always returns the result of the command execution. If the command was successfully executed, the response informs the user application about this. If it is impossible to complete the command, the response returns the error code. Some commands request specific data (for example, the serial number of a device or the total number of connected adapters). In this case the response returns the requested data in addition to the result of the command execution.
Events are sent from the device to the user application. They contain information about some changes that have taken place. A user can predefine the condition of an event generation. For example, an event may be generated when a new device is connected or when voltage changes on an input pin.
All the messages are transferred through the DLN library.
The messages (commands, responses and events) are delivered with the help of three functions:
DlnSendMessage() - sends a specified message (an asynchronous command) to the device.
DlnGetMessage() - retrieves messages (responses and events) sent by the device.
DlnTransaction() - sends a synchronous command, waits for a response and returns the response details. Messages sent by the device (responses and events) are pushed into the DLN library message queue. The user may call the DlnGetMessage() function to get the message from the queue.
The DlnGetMessage() function removes the message from the queue and passes the message details to the user application.