The DatagramSocket class enables code to send and receive Universal Datagram Protocol (UDP) packets.

You can test for support at run time using the DatagramSocket.isSupported property.

OpenFL target support: This feature is supported on all desktop operating systems, on iOS, and on Android.

Adobe AIR profile support: his feature is supported on all desktop operating systems, on iOS (starting with AIR 3.8), and on Android (starting with AIR 3.8). This feature is not supported on AIR for TV devices. See AIR Profile Support for more information regarding API support across multiple profiles.

Datagram packets are individually transmitted between the source and destination. Packets can arrive in a different order than they were sent. Packets lost in transmission are not retransmitted, or even detected.

Data sent using a datagram socket is not automatically broken up into packets of transmittable size. If you send a UDP packet that exceeds the maximum transmission unit (MTU) size, network discards the packet (without warning). The limiting MTU is the smallest MTU of any interface, switch, or router in the transmission path.

The Socket class uses TCP which provides guaranteed packet delivery and automatically divides and reassembles large packets. TCP also provides better network bandwidth management. These features mean that data sent using a TCP socket incurs higher latency, but for most uses, the benefits of TCP far outweigh the costs. Most network communication should use the Socket class rather than the DatagramSocket class.

The DatagramSocket class is useful for working with applications where a small transmission latency is important and packet loss is tolerable. For example, network operations in voice-over-IP (VoIP) applications and real-time, multiplayer games can often benefit from UDP. The DatagramSocket class is also useful for some server-side applications. Since UDP is a stateless protocol, a server can handle more requests from more clients than it can with TCP.

The DatagramSocket class can only be used in targets that support UDP.

Events:

data

Dispatched when this socket receives a packet of data.

Static variables

@:value(true)staticread onlyisSupported:Bool = true

Indicates whether or not DatagramSocket features are supported in the run-time environment.

Constructor

new()

Creates a DatagramSocket object

Variables

read onlybound:Bool

Indicates whether this socket object is currently bound to a local address and port.

read onlyconnected:Bool

Indicates whether this socket object is currently connected to a remote address and port.

read onlylocalAddress:String

The IP address this socket is bound to on the local machine.

read onlylocalPort:Int

The port this socket is bound to on the local machine.

read onlyremoteAddress:String

The IP address of the remote machine to which this socket is connected.

read onlyremotePort:Int

The port on the remote machine to which this socket is connected.

Methods

@:value({ localAddress : "0.0.0.0", localPort : 0 })bind(localPort:Int = 0, localAddress:String = "0.0.0.0"):Void

Binds this socket to the specified local address and port.

The bind() method executes synchronously. The bind operation completes before the next line of code is executed.

Once a DatagramSocket is bound, it should be closed with the close() method before disposal to avoid subsequent receiving of messages.

Parameters:

localPort

The number of the port to bind to on the local computer. If localPort, is set to 0 (the default), the next available system port is bound. Permission to connect to a port number below 1024 is subject to the system security policy. On Mac and Linux systems, for example, the application must be running with root privileges to connect to ports below 1024.

localAddress

The IP address on the local machine to bind to. This address can be an IPv4 or IPv6 address. If localAddress is set to 0.0.0.0 (the default), the socket listens on all available IPv4 addresses. To listen on all available IPv6 addresses, you must specify "::" as the localAddress argument. To use an IPv6 address, the computer and network must both be configured to support IPv6. Furthermore, a socket bound to an IPv4 address cannot connect to a socket with an IPv6 address. Likewise, a socket bound to an IPv6 address cannot connect to a socket with an IPv4 address. The type of address must match.

Throws:

IOError

This error occurs if the socket cannot be bound, such as when: 1. localPort is already in use by another socket. 2. the user account under which the application is running doesn't have sufficient system privileges to bind to the specified port. (Privilege issues typically occur when localPort < 1024.) 3. This DatagramSocket object is already bound. 4. This DatagramSocket object has been closed.

ArgumentError

This error occurs when localAddress is not a syntactically well-formed IP address.

RangeError

This error occurs when localPort is less than 0 or greater than 65535.

close():Void

Closes the socket.

The socket is disconnected from the remote machine and unbound from the local machine. A closed socket cannot be reused.

connect(remoteAddress:String, remotePort:Int):Void

Connects the socket to a specified remote address and port.

When a datagram socket is "connected," datagram packets can only be sent to and received from the specified target. Packets from other sources are ignored. Connecting a datagram socket is not required. Establishing a connection can remove the need to filter out extraneous packets from other sources. However, a UDP socket connection is not a persistent network connection (as it is for a TCP connection). It is possible that the remote end of the socket does not even exist.

If the bind() method has not been called, the socket is automatically bound to the default local address and port.

Parameters:

remoteAddress

The IP address of the remote machine with which to establish a connection. This address can be an IPv4 or IPv6 address. If bind() has not been called, the address family of the remoteAddress, IPv4 or IPv6, is used when calling the default bind().

remotePort

The port number on the remote machine used to establish a connection.

Throws:

ArgumentError

This error occurs when localAddress is not a syntactically valid address. Or when a default route address ('0.0.0.0' or '::') is used.

RangeError

This error occurs when localPort is less than 1 or greater than 65535.

IOError

This error occurs if the socket cannot be connected, such as when bind() has not been called before the call to connect() and default binding to the remote address family is not possible.

receive():Void

Enables the DatagramSocket object to receive incoming packets on the bound IP address and port.

The function returns immediately. The DatagramSocket object dispatches a data event when a data packet is received.

@:value({ port : 0, address : null, length : 0, offset : 0 })send(bytes:ByteArray, offset:UInt = 0, length:UInt = 0, ?address:String, port:Int = 0):Void

Sends packet containing the bytes in the ByteArray using UDP.

If the socket is connected, the packet is sent to the remote address and port specified in the connect() method and no destination IP address and port can be specified. If the socket is not connected, the packet is sent to the specified address and port and you must supply valid values for address and port. If the bind() method has not been called, the socket is automatically bound to the default local address and port.

Note: Sending data to a broadcast address is not supported.

Parameters:

bytes

A ByteArray containing the packet data.

offset

The zero-based offset into the bytes ByteArray object at which the packet begins.

length

The number of bytes in the packet. The default value of 0 causes the entire ByteArray to be sent, starting at the value specified by the offset parameter.

address

The IPv4 or IPv6 address of the remote machine. An address is required if one has not already been specified using the connect() method.

port

The port number on the remote machine. A value greater than 0 and less than 65536 is required if the port has not already been specified using the connect() method.

Throws:

ArgumentError

If the socket is not connected and address is not a well-formed IP address.

RangeError

This error occurs when port is less than 1 or greater than 65535.

IOError

This error occurs: If bind() has not been called, and when default binding to the destination address family is not possible. On some operating systems, an IOError is thrown if the connect() method is called when an ICMP "destination unreachable" message has already been received from the target host. (Thus, the error is thrown on the second failed attempt to send data, not the first.) Other operating systems, such as Windows, disregard these ICMP messages, so no error is thrown.

RangeError

If offset is greater than the length of the ByteArray specified in bytes or if the amount of data specified to be written by offset plus length exceeds the data available.

IllegalOperationError

If the address or port parameters are specified when the socket has already been connected.

Inherited Variables

Inherited Methods

Defined by EventDispatcher

dispatchEvent(event:Event):Bool

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters:

event

The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its target property cannot be changed, so you must create a new copy of the event for redispatching to work.

Returns:

A value of true if the event was successfully dispatched. A value of false indicates failure or that preventDefault() was called on the event.

Throws:

Error

The event dispatch recursion limit has been reached.

hasEventListener(type:String):Bool

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use willTrigger().

The difference between hasEventListener() and willTrigger() is that hasEventListener() examines only the object to which it belongs, whereas willTrigger() examines the entire event flow for the event specified by the type parameter.

When hasEventListener() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type is registered; false otherwise.

toString():String

willTrigger(type:String):Bool

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns true if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the hasEventListener() and the willTrigger() methods is that hasEventListener() examines only the object to which it belongs, whereas the willTrigger() method examines the entire event flow for the event specified by the type parameter.

When willTrigger() is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

type

The type of event.

Returns:

A value of true if a listener of the specified type will be triggered; false otherwise.