►Rhombus Reference
►14 Operating System
▼14.5 Networking
14.5.1 TCP
14.5.2 UDP
14.5.3 Port Numbers and Waiting Modes
On this page:
UDP
UDP.close
UDP.bind
UDP.is_  bound
UDP.connect
UDP.is_  connected
UDP.receive
UDP.receive_  evt
UDP.receive_  ready_  evt
UDP.send_  to
UDP.send
UDP.send_  to_  evt
UDP.send_  evt
UDP.send_  ready_  evt
UDP.addresses
UDP.ttl
UDP.multicast_  join_  group
UDP.multicast_  leave_  group
UDP.multicast_  interface
UDP.multicast_  loopback_  on
UDP.multicast_  ttl
8.18
  top  contents    up   

14.5.2 UDP🔗ℹ

class

class UDP():

  implements Closeable

  constructor (

    ~family_host: family_host :: maybe(String) = #false,

    ~family_port: family_port :: maybe(PortNumber) = #false

  )

A UDP object represents a UDP socket.

Since UDP implements Closeable, the UDP constructor can be used with Closeable.let.

method

method (udp :: UDP).close() :: Void

Closes the UDP socket represented by udp. Closing an already-closed socket has no effect.

method

method (udp :: UDP).bind(

  ~host: host :: maybe(String) = #false,

  ~port: port :: ListenPortNumber = 0,

  ~reuse: reuse = #false

) :: Void

 

method

method (udp :: UDP).is_bound() :: Boolean

The UDP.bind method binds a UDP socket to a local IP address and port. The host and port optionally constrain the binding. When not bound explicitly, a UDP socket is bound automatically by a send or receive operation.

The UDP.is_bound method reports whether udp has been bound, independent of whether it was bound explicitly or automatically.

method

method (udp :: UDP).connect(

  ~host: host :: String,

  ~port: port :: PortNumber

) :: Void

 

method

method (udp :: UDP).is_connected() :: Boolean

The UDP.connect method connects a UDP socket to a remote IP address and port. A UDP socket does not need to be connected to send data; use UDP.send_to or UDP.send_to_evt with an unconnected socket, and use UDP.send or UDP.send_evt

The UDP.is_connected method reports whether udp has been connected.

method

method (udp :: UDP).receive(

  bytes :: MutableBytes,

  start_pos :: NonnegInt = 0,

  end_pos :: NonnegInt = bytes.length(),

  ~wait: wait :: Port.WaitMode && !matching(#'all) = #'some

) :: values(maybe(NonnegInt), maybe(String), maybe(PortNumber))

Receives data send to a UDP socket in a single packet. The data is written into bytes starting at start_pos, and if more data than start_pos - end_pos bytes are sent, the extra bytes are discarded.

If wait is #'some, then UDP.receive blocks until data is received, and the results are never #false. If wait is #'none, then UDP.receive never blocks, and it immediately returns with #false results if data is not immediately available. If wait is #'enable_break, then UDP.receive blocks the same as with #'some, but breaks are enabled while blocking; if breaks are disabled on entry, then either data is received or an Exn.Break exception is thrown, but not both.

method

method (udp :: UDP).receive_evt(

  bytes :: MutableBytes,

  start_pos :: NonnegInt = 0,

  end_pos :: NonnegInt = bytes.length()

) :: Evt

 

method

method (udp :: UDP).receive_ready_evt() :: Evt

The UDP.receive_evt method is similar to UDP.receive, but instead of receiving data, returns a synchronizable event that is ready for synchronization when data is available to receive at udp. Synchronizing has the effect of receiving data, and the synchronization result is a PairList of the three values (never #false) that UDP.receive would return.

The UDP.receive_ready_evt similarly returns a synchronizable event, but synchronization has no effect, and the synchronization result is the object itself.

method

method (udp :: UDP).send_to(

  ~host: host :: String,

  ~port: port :: PortNumber,

  bytes :: Bytes,

  start_pos :: NonnegInt = 0,

  end_pos :: NonnegInt = bytes.length(),

  ~wait: wait :: Port.WaitMode && !matching(#'some) = #'all

) :: Void || Boolean

Sends data to the indicated remote IP address and port number using an unconnected UDP socket represented by udp. The data to be sent is the bytes from start_pos (inclusive) to end_pos (exclusive) in bytes.

If wait is #'all, then UDP.send_to blocks until data can be sent (or, at least, queued at the operating-system level), and the result is #void. If wait is #'none, then UDP.send_to immediately returns without sending if data cannot be sent (or queued at the operating-system level), and the result is #false in that case; otherwise, data is sent (or queued) immediately, and the result is #true. If wait is #'enable_break, then UDP.send_to blocks the same as with #'some, but breaks are enabled while blocking; if breaks are disabled on entry, then either data is sent or an Exn.Break exception is thrown, but not both.

method

method (udp :: UDP).send(

  bytes :: Bytes,

  start_pos :: NonnegInt = 0,

  end_pos :: NonnegInt = bytes.length(),

  ~wait: wait :: Port.WaitMode && !matching(#'some) = #'all

)  :: Void || Boolean

Like UDP.send_to, but for a connected UDP socket (see UDP.connect) where the destination IP address and port number were specified as the connection.

method

method (udp :: UDP).send_to_evt(

  ~host: host :: String,

  ~port: port :: PortNumber,

  bytes :: Bytes,

  start_pos :: NonnegInt = 0,

  end_pos :: NonnegInt = bytes.length()

) :: Evt

 

method

method (udp :: UDP).send_evt(

  bytes :: Bytes,

  start_pos :: NonnegInt = 0,

  end_pos :: NonnegInt = bytes.length()

) :: Evt

 

method

method (udp :: UDP).send_ready_evt() :: Evt

The UDP.send_to_evt and UDP.send_evt methods are similar to UDP.send_to or UDP.send, but instead of sending data, returns a synchronizable event that is ready for synchronization when data is can be sent at udp. Synchroniziing has the effect of sending data, and the synchronization result is #void.

The UDP.send_ready_evt similarly returns a synchronizable event, but synchronization has no effect, and the synchronization result is the object itself.

method

method (udp :: UDP).addresses()

  :: values(String, ListenPortNumber, String, ListenPortNumber)

Returns a UDP socket’s local bound IP address and port number followed by the connection peer’s IP address and port number. If udp is unbound or unconnected, the corresponding results can be zeros.

property

property (udp :: UDP).ttl :: Byte

 

property

property (udp :: UDP).ttl := (n :: Byte)

A property for getting or setting a UDP socket’s time-to-live value (i.e., the time-to-live value that it uses for sent packets).

method

method (udp :: UDP).multicast_join_group(

  ~address: addr :: String,

  ~host: host :: maybe(String)

) :: Void

 

method

method (udp :: UDP).multicast_leave_group(

  ~address: addr :: String,

  ~host: host :: maybe(String)

) :: Void

 

property

property (udp :: UDP).multicast_interface :: String

 

property

property (udp :: UDP).multicast_interface := (intf :: maybe(String))

 

property

property (udp :: UDP).multicast_loopback_on :: Boolean

 

property

property (udp :: UDP).multicast_loopback_on := (on :: Any.to_boolean)

 

property

property (udp :: UDP).multicast_ttl :: Byte

 

property

property (udp :: UDP).multicast_ttl := (n :: Byte)

Methods and properties to inspect or set the multicast configuration of a UDP socket.

  top  contents    up