Echelon OpenLDV - Manual (Page 36)

28 Using the OpenLDV API
Table 14. ldv_read() Parameters
Parameter Direction Description
handle
Input The network interface device to be read. This value was
returned as the handle parameter when you opened the
network interface with one of the open functions
(ldv_open(), ldv_open_cap(), or ldvx_open()).
msg_p Output A pointer to a buffer allocated by your application that will
receive the next uplink message. You must provide a
sufficiently large buffer to receive each message. The length
of this buffer is specified by the len parameter.
For information about the different uplink messages you
might read with this function, and descriptions of the
application buffer structure that each one uses, see Chapter
3, Sending and Receiving Messages with the OpenLDV API,
on page 57.
len Input The length of the application buffer to receive the message,
in bytes.
For communications that use the SICB format, the
maximum length of a message is 257 bytes. When possible,
use a buffer length of at least 257 bytes. For
communications that use the LdvEx format, allocate
additional buffer space.
Remarks
All messages from a network interface are buffered by the OpenLDV runtime
until a client application reads them with this function. You can program your
application to poll the network interface for incoming messages by periodically
calling this function. The function returns LDV_OK when it has successfully
read a message from the network interface, or returns LDV_NO_MSG_AVAIL if
no messages are currently available. Alternatively, you can use the
ldv_register_event() function to set up an event to signal the receipt of each
new message. For each poll loop within your application, you should call the
ldv_read() function until you receive LDV_NO_MSG_AVAIL.
Most incoming messages will be responses to prior requests or unsolicited
messages (such as network variable updates or application messages). Although
incoming messages are buffered, the OpenLDV application must process these
messages and provide suitable responses to the L ON W ORKS network, in a timely
fashion. The acceptable duration for providing these responses depends on the
arrival rate of messages from the network, the number of buffers in the network
interface driver involved, and the speed and current processing load of the
computer running the application. Therefore, the OpenLDV application must
process all incoming messages promptly, and with high priority.
The ldv_read() function returns LDV_INVALID_BUF_LEN if the specified
buffer is too small to contain the next incoming message. In this case, allocate a
larger buffer to receive the message, and call the function again, specifying a
larger value for the len input parameter. For communications that use the SICB