Echelon OpenLDV User Manual download pdf (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

ONWORKS 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

1 2 ... 31 32 33 34 35 36 37 38 39 40 41 ... 193 194

Comments to this Manuals

No comments

Echelon OpenLDV User Manual Page 36

Comments to this Manuals

Related products and manuals for Software Echelon OpenLDV