Name
CreateUDPObject -- create a new UDP object (V5.0)
Synopsis
[id] = CreateUDPObject(id[, port, ip$, mode, protocol])
Function
This command can be used to create a new UDP object that can receive data and send data to other network participants. The optional argument port can be used to specify at which local port the UDP object should be created. If you do not specify this argument, CreateUDPObject() will choose a vacant port automatically, and you can use GetLocalPort() later to find out the port number of the UDP object. In the first argument, you need to pass an identifier which is needed to refer to this UDP object later on. Alternatively, you can pass Nil as the first argument. In that case, CreateUDPObject() will select a vacant identifier automatically and return it to you.

Starting with Hollywood 8.0 there is a new mode argument which allows you to specify the type of UDP object that should be created for you. This can be one of the following predefined values:

#UDPSERVER:
Create an UDP server object. In that case, the optional argument ip$ can be used to specify a local IP address the UDP object should be bound to. This defaults to "*", which means that the server will accept connections from the whole network. You can also specify "127.0.0.1" (or "::1" in IPv6) to allow only connections from the local host. Note that passing "*", which is also the default, might trigger the firewall on some configurations. #UDPSERVER is the default mode for CreateUDPObject().

#UDPCLIENT:
Create a client UDP object. In that case, the optional arguments ip$ and port must be specified to specify the server the client should be connected to. If your UDP object always sends data to the same server, it is recommended to create it as a #UDPCLIENT object because SendUDPData() is faster then. (V8.0)

#UDPNONE:
Create an unconnected UDP object. In that case, the optional arguments ip$ and port are ignored. Unconnected UDP objects are useful if you need to send data to different servers without being able to receive data on your own. (V8.0)

Additionally, Hollywood 8.0 introduces an optional new protocol argument which allows you to specify the Internet protocol that should be used by the UDP object. This can be one of the following special constants:

#IPV4:
Use Internet Protocol version 4 (IPv4). IPv4 addresses are limited to 32 bits and are represented using four numbers separated by three dots, e.g. 127.0.0.1.

#IPV6:
Use Internet Protocol version 6 (IPv6). IPv6 addresses use 128 bits and are represented by eight groups of four hexadecimal digits, e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334. Note that #IPV6 is currently unsupported on AmigaOS and compatible systems.

#IPAUTO:
Let the host operating system determine the Internet protocol to use. You can then use GetLocalProtocol() or GetConnectionProtocol() to find out which Internet protocol the host operating system has chosen for the UDP object

The protocol argument defaults to the default protocol type set using SetNetworkProtocol(). By default, this is #IPV4 due to historical and portability reasons. See SetNetworkProtocol for details.

Once the UDP object is created, you can use the commands SendUDPData(), ReceiveUDPData(), and the OnReceiveUDPData event handler to communicate with other systems in the network.

Please note that UDP is an unreliable transfer protocol. It is faster than the TCP protocol but data may arrive incompletely or out of order. Thus, it is only suitable for purposes that do not depend on the integrity of the transferred data.

Inputs
id
identifier for the new UDP object or Nil for auto id selection
port
optional: port for this UDP object, or 0 for automatic port selection (defaults to 0); must be set for #UDPCLIENT
ip$
optional: IP address to bind server to (for #UDPSERVER) or to connect UDP object to (for #UDPCLIENT) (defaults to "*" for #UDPSERVER); must be set for #UDPCLIENT
mode
optional: desired mode for this UDP object (see above for possible values) (V8.0)
protocol
optional: Internet protocol to use (see above for possible values); defaults to the protocol type set using SetNetworkProtocol() (V8.0)
Results
id
optional: identifier of the new UDP object; this will only be returned when you pass Nil as argument 1 (see above)

Show TOC