This module should not be used in new development it will be removed
in the next major release. Use |
The udp
module is an interface to User Datagram Protocol (UDP
). Rather
than using the socket library as an interface to sockets, the aim of the
udp
library is to provide an easy-to-use interface directly to UDP
.
Starts the udp
server and returns {ok, Pid}
. This function must
be called before any other functions in this module are called.
send(Address, Port, Packet) -> ok | { error, Reason }
Address = { integer(), integer(), integer(), integer()}
| atom() | string()
Port = integer(0..65535)
Packet = [byte()] | binary()
Reason = term()
Sends Packet
to the specified address (address, port). It
returns ok
, or {error, Reason}
. Address
can be an
IP address expressed as a tuple, for example {192, 0, 0, 1}
. It can also be a host name expressed as an atom or a string, for example 'somehost.some.domain'.
Port
is an integer, and Packet
is either a list of bytes or
a binary.
open(Port, Options) -> {ok, Id } | { error, Reason }
open(Port) -> {ok, Id } | { error, Reason }
Port = integer(0..65535)
Options = [binary|list]
Id = integer()
Reason = term()
Associates a UDP port number (Port
) with the process calling it. It returns
{ok, Id}
, or {error, Reason}
. The returned Id
is used to
send packets from this port. Options
is a list of options
associated with this port. The list can contain either the atom
binary
or list
.
open/1
is equivalent to open(PortNo, [list])
. (This makes open/1
backwards compatible with previous versions of the udp
library).
A process which calls open
receives
messages of the type {udp, Id, IP, InPortNo, Packet}
when UDP
packets arrive at that port. IP
and InPortNo
define the address
from where Packet
came. Packet
is a list of bytes if the
option list
was used. Packet
is a binary if the option binary
was used.
If you set Port to 0, the underlying Operating System assigns a free UDP port. (You can find out which port by calling udp:port(Id)
.)
If any of the following functions are called with an Id
that was not opened by the
process which calls the function, they will return {error,
not_owner}
.
close(Id) -> ok | { error, Reason }
Removes the association Id
that was performed with open. Returns
ok
, or {error, Reason}
.
send(Id, Address, Port, Packet) -> ok | { error, Reason }
Same as send/3, except that it sends from the UDP port associated
with Id
. Returns ok
, or {error, Reason}
.
send_same(Id, Packet) -> ok | { error, Reason }
Sends the packet to the same IP address and port as the previous
send/4
function which was used for the association Id
. Returns ok
, or {error,
Reason}
.
port(Id) -> { ok, Port } | { error, Reason }
Port = integer(0..65535)
Returns the UDP port number associated with Id
. Returns {ok,
PortNo}
, or {error, Reason}
.
gethostbyname(HostName) -> { ok, IPAddress } | { error, Reason }
HostName = atom() | string()
IPAddress = { integer(), integer(), integer(), integer() }
Uses HostName
, which is an atom or a string, and tries to
find out the IP address of this host by using the gethostbyname(3)
(C) library call. Returns {ok, IPAddress}
, or {error, Reason}
.
Since UDP packets are carried in IP datagrams, they have a maximum size
of 65508 bytes. In reality, this limit is usually lower and depends on
implementation, buffer sizes, and other factors. The udp
library does not give an error indicatation if you try to send too large packets. The packet is just
dropped silently.
Most operating systems limit the number of files which one process
can have open at the same time. The limitation in the udp
library is 255,
regardless of whether the OS limit is higher. This is because
the Id
is one byte.