UDP Client/Server Communication
This page describes how to set up remote communication between processes using UDP.
Introduction
UDP is supported through the %Net.UDPOpens in a new tab class. This class provides methods to Send()Opens in a new tab a packet to a specified destination and port, to Recv()Opens in a new tab a packet from the socket, and to Reply()Opens in a new tab to the transmitter of the last received packet.
The destination is identified as a local host name or an IPv4 or IPv6 host address. The port can be either a specified port number or a dynamic port assignment.
Establishing a UDP Socket
To use UDP, you must use the %New()Opens in a new tab method to create a UDP socket object. This object instance is then used to send, receive, and reply to packet transmissions.
When you create a UDP socket object you can specify the port number and the host address, as shown in the following example:
SET UPDOref=##class(%Net.UDP).%New(3001,"0.0.0.0")
Both the port number and the host address are optional. The %New() method returns the OREF (object reference) of the UDP socket object instance.
There are two sides to a UDP transmission:
-
The server waits to receive a request and then provides the requested information. Thus this side of the transmission may be referred to as the Receiver or the Provider. When a provider creates an UDP object, it must define a port number on which it will receive requests.
-
The client sends a request for information and then receives a reply. Thus this side of the transmission may be referred to as the Sender or the Requestor. When a requestor creates an UDP object, it can use a dynamic port number. The default is 0. When it sends a packet, it must specify the host name and port number of the provider.
The Host Address
The Send() method specifies the binary address of the destination. This is a binary version of the host address. You must create this binary host address by using the GetHostAddr()Opens in a new tab method, as follows:
SET client=##class(%Net.UDP).%New()
SET addrbin=##class(%Net.UDP).GetHostAddr("172.16.61.196")
WRITE client.Send("message text",addrbin,3001)
You can specify a host name, an IPv4 address, or an IPv6 address to GetHostAddr(), as shown in the following examples:
SET hostname="MYLAPTOP"
SET IPv4="172.16.61.196"
SET IPv6="::1"
SET flag=$SYSTEM.INetInfo.CheckAddressExist(hostname)
IF flag=1 { SET addrbin=##class(%Net.UDP).GetHostAddr(hostname)
WRITE "host name valid",! }
ELSE { WRITE "not a hostname: ",hostname,! }
SET flag=$SYSTEM.INetInfo.CheckAddressExist(IPv4)
IF flag=1 { SET addrbin=##class(%Net.UDP).GetHostAddr(IPv4)
WRITE "IPv4 valid",! }
ELSE { WRITE "not an IPv4 address: ",IPv4,! }
SET flag=$SYSTEM.INetInfo.CheckAddressExist(IPv6)
IF flag=1 { SET addrbin=##class(%Net.UDP).GetHostAddr(IPv6)
WRITE "IPv6 valid",! }
ELSE { WRITE "not an IPv6 address: ",IPv6,! }
You can expand this binary host address back to the host name using the AddrToHostName()Opens in a new tab method, as shown in the following example:
SET addrbin=##class(%Net.UDP).GetHostAddr("MYLAPTOP")
WRITE $SYSTEM.INetInfo.AddrToHostName(addrbin)
You can use the LocalHostName()Opens in a new tab method to determine your host name. You can use the HostNameToAddr()Opens in a new tab method to translate a host name to an IPv4 or IPv6 address, as shown in the following example:
SET localhost=$SYSTEM.INetInfo.LocalHostName() /* get host name */
WRITE "local host name is ",localhost,!
SET addrbin=##class(%Net.UDP).GetHostAddr(localhost) /* compress to binary address */
WRITE "binary form of IP address is ",addrbin,!
SET hostname=$SYSTEM.INetInfo.AddrToHostName(addrbin) /* expand binary address to host name */
WRITE "binary IP address expands to ",hostname,!
SET ipaddr=$SYSTEM.INetInfo.HostNameToAddr(hostname) /* host name to IP address */
WRITE "hostname corresponds to IP address ",ipaddr,!
IPv4 and IPv6
UDP supports both IPv4 and IPv6 Internet protocols. Because these protocols are incompatible, both the server and the client must use the same Internet protocol or the transmission will fail.
An IPv4 address has the following format. n is a decimal integer in the range 0 through 255:
n.n.n.n
You can specify the IPv4 protocol as "0.0.0.0".
An IPv6 address has the following full format. h is a hexadecimal number with four hexadecimal digits:
h:h:h:h:h:h:h:h
Commonly, IPv6 addresses are abbreviated by eliminating leading zeros and replacing consecutive sections of zeros with a double colon (::); only one double colon may be used in an IPv6 address. By using IPv4 abbreviation rules, you can specify the IPv6 protocol as "::" (meaning that all eight h sections have the value 0000).
To establish the Internet protocol:
-
The client must establish either IPv4 or IPv6 in the %New() method. The default is IPv4.
-
This must match the IPv4 or IPv6 protocol specified in the GetHostAddr() method and supplied (in binary form) in the Send() method.
The following is an IPv4 transmission:
Server
SET sobj=##class(%Net.UDP).%New(3001,"127.0.0.1")
SET inmsg=sobj.Recv()
Client
SET cobj=##class(%Net.UDP).%New() /* the default is IPv4 */
SET bhost=##class(%Net.UDP).GetHostAddr("127.0.0.1")
SET outmsg="this is the message to send"
WRITE cobj.Send(outmsg,bhost,3001)
The following is an IPv6 transmission:
Server
SET x=##class(%SYSTEM.INetInfo).IsIPV6Enabled()
IF x=1 {
SET sobj=##class(%Net.UDP).%New(3001,"::1")
SET inmsg=sobj.Recv() }
ELSE {WRITE "IPv6 not enabled" }
Client
SET cobj=##class(%Net.UDP).%New(0,"::")
SET bhost=##class(%Net.UDP).GetHostAddr("::1")
SET outmsg="this is the message to send"
WRITE cobj.Send(outmsg,bhost,3001)
Methods for handling host addresses are found in the %SYSTEM.INetInfoOpens in a new tab class documentation. Further details on IPv4 and IPv6 formats can be found in Use of IPv6 Addressing.