UDPRead
int UDPRead (unsigned int channel, void *inputBuffer, size_t inputBufferSize, unsigned int timeout, unsigned int *sourcePort, char sourceAddress[]);
Purpose
Reads a single datagram from the UDP channel.
This function polls the channel port for data and retrieves the first available datagram. On success, the function returns the number of bytes read. UDPRead never retrieves more than one datagram at a time; you must call the function exactly once for each datagram that arrives on the channel. When the function successfully reads a datagram, UDPRead also reports the sourcePort number and IP sourceAddress from which the datagram was sent.
If you pass 0 for inputBuffer or inputBufferSize, the function peeks at the port and returns the size of the first available datagram.
 |
Note Input buffering, which is handled by the system socket library, may or may not be provided. The UDP protocol provides no guarantee that datagrams will be delivered, but if you experience an excessive number of lost datagrams, try registering a UDP callback function to ensure that you read each datagram as soon as it is received. |
Parameters
| Input | ||
| Name | Type | Description |
| channel | unsigned int | A handle that uniquely identifies an open UDP communication endpoint. |
| inputBuffer | void * | A buffer into which to read the data. You must pass a buffer size large enough to hold the entire datagram.
If you pass a buffer that is not large enough to hold the entire datagram, UDPRead copies inputBufferSize bytes to the buffer and returns kUDP_DataLost. If you pass 0 as inputBuffer, UDPRead peeks at the port and returns the size of the next available datagram in status. If no datagram is available, UDPRead returns 0. |
| inputBufferSize | size_t | The size, in bytes, of inputBuffer. This function returns an error if you pass a value greater than INT_MAX. |
| timeout | unsigned int | The number of milliseconds to wait for data to become available before returning the kUDP_ReadTimeout error. Pass UDP_DO_NOT_WAIT (0) for UDPRead to return immediately. In this case, if no data is available, UDPRead returns 0 instead of a timeout error. Pass UDP_WAIT_FOREVER for the function block to wait indefinitely until data becomes available or until another thread calls DisposeUDPChannel on the channel. UDP_DEFAULT_TIMEOUT is defined as 5 seconds. |
| Output | ||
| Name | Type | Description |
| sourcePort | unsigned int | The port number from which the received datagram was originally sent. Pass 0 if you do not need to know the source port. |
| sourceAddress | char [] | The IP address from which the received datagram was originally sent. You must pass a pre-allocated buffer that is at least 16 bytes long. Pass 0 if you do not need to know the source address. |
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful.
If the function was successful, the return value is the number of bytes read. A negative number indicates that an error occurred. Call the GetUDPErrorString function to obtain a message that describes the error. |
Additional Information
Library: UDP Support Library
Include file: udpsupp.h
LabWindows/CVI compatibility: LabWindows/CVI 8.5 and later
Examples
Refer to the following examples that use the UDPRead function:
- udp\DNSResolver.cws
Open example - udp\UDPChat.cws
Open example - udp\UDPWriter.cws
Open example