CreateUDPChannelConfig
int CreateUDPChannelConfig (unsigned int localPort, const char *localInterfaceAddress, unsigned int exclusive, UDPCallbackPtr callbackFunction, void *callbackData, unsigned int *channel);
Purpose
Creates and configures a UDP channel object that you can use to send and/or receive UDP datagrams.
You must create a UDP channel object to send or receive any unicast, multicast, or broadcast messages. The new channel can receive messages sent only to the specified port number, though it can send messages to any port.
You must call DisposeUDPChannel to free resources when you finish using the channel.
Parameters
| Input | ||||
| Name | Type | Description | ||
| localPort | unsigned int | The local port number to open for UDP communication.
Applications must agree on the port number(s) to use for communication. According to the Internet Assigned Numbers Authority (IANA), do not use ports in the Well Known (0-1023) or Registered (1024-49151) ranges without IANA registration. Instead, use port numbers in the Dynamic/Private range: 49152-65535.
|
||
| localInterfaceAddress | const char * | The local network interface on which this channel will communicate. This parameter is relevant only if the computer has multiple network interface cards. You can pass a string representing the IP address in dot-decimal notation, such as 127.0.0.1, or pass an alphanumeric string representing the host name, such as HAL9000. You also can pass UDP_ANY_ADDRESS, NULL, or an empty string to use any available interfaces. In this case, your channel is assigned a single interface on which to send and receive datagrams. |
||
| exclusive | unsigned int | A boolean value indicating whether to reserve the port for exclusive use. Passing a non-zero value ensures that no application can open or use the port on the same interface until you dispose of this channel. If the port is already open on the interface, the function fails with the error kUDP_PortInUse.
|
||
| callbackFunction | UDPCallbackPtr | Pointer to the callback function that processes messages associated with your UDP channel. Events are sent synchronously to the callback function. The callback function must have the following form: int CVICALLBACK UDPCallback (unsigned channel, int eventType, int errCode, void *callbackData); channel specifies the channel that received the event. eventType specifies the type of event that occurred. UDP_DATAREADY, which is the only supported event, indicates that a datagram has arrived on the channel's port and is waiting to be read. Your program must call UDPRead to obtain the data.
|
||
| callbackData | void * | A pointer-width value that the UDP Support Library passes to the callback function each time the library invokes the callback for the same channel. You must define the meaning of the callback data. For example, you can use the parameter as a pointer to a data object that you need to access in the callback function to avoid declaring the data object as a global variable. If you do not need to use the callbackData parameter, you can pass zero. |
||
| Output | ||||
| Name | Type | Description | ||
| channel | unsigned int | A handle that uniquely identifies a UDP channel object. | ||
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful.
Zero indicates successful execution and 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 CreateUDPChannelConfig function:
- udp\DNSResolver.cws
Open example - udp\UDPWriter.cws
Open example