DatagramSocket API 详解

此类表示用来发送和接收数据报包的套接字。

数据报套接字是包投递服务的发送或接收点。每个在数据报套接字上发送或接收的包都是单独编址和路由的。从一台机器发送到另一台机器的多个包可能选择不同的路由，也可能按不同的顺序到达。

在 DatagramSocket 上总是启用 UDP 广播发送。为了接收广播包，应该将 DatagramSocket 绑定到通配符地址。在某些实现中，将 DatagramSocket 绑定到一个更加具体的地址时广播包也可以被接收。

示例：DatagramSocket s = new DatagramSocket(null); s.bind(new InetSocketAddress(8888)); 这等价于：DatagramSocket s = new DatagramSocket(8888); 两个例子都能创建能够在 UDP 8888 端口上接收广播的 DatagramSocket。

version	1.101, 06/08/06
since	JDK1.0
See also	java.net.DatagramPacket, java.nio.channels.DatagramChannel

Constructors
public	DatagramSocket() throws SocketException zh_cn 构造数据报套接字并将其绑定到本地主机上任何可用的端口。套接字将被绑定到通配符地址，IP 地址由内核来选择。 如果有安全管理器，则首先使用 0 作为变量来调用其 checkListen 方法，以确保允许该操作。这可能会导致 SecurityException 异常。 Throws SocketException:  zh_cn 如果套接字不能被打开，或不能将其绑定到指定的本地端口。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。 See also checkListen
protected	DatagramSocket(DatagramSocketImpl impl) zh_cn 创建带有指定 DatagramSocketImpl 的未绑定数据报套接字。 impl zh_cn 子类希望在 DatagramSocket 上使用的 DatagramSocketImpl 的实例。 since 1.4
public	DatagramSocket(SocketAddress bindaddr) throws SocketException zh_cn 创建数据报套接字，将其绑定到指定的本地套接字地址。 如果地址为 null，创建未绑定的套接字。 如果有安全管理器，则首先使用套接字中的端口作为变量来调用其 checkListen 方法，以确保允许该操作。这可能会导致 SecurityException 异常。 bindaddr zh_cn 要绑定的本地套接字地址，对于未绑定的套接字为 null。 Throws SocketException:  zh_cn 如果套接字不能被打开，或不能将其绑定到指定的本地端口。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。 since 1.4 See also checkListen
public	DatagramSocket(int port) throws SocketException zh_cn 创建数据报套接字并将其绑定到本地主机上的指定端口。套接字将被绑定到通配符地址，IP 地址由内核来选择。 如果存在安全管理器，则首先使用 port 参数作为参数调用其 checkListen 方法，以确保允许该操作。这可能会导致 SecurityException 异常。 port zh_cn 要使用的端口。 Throws SocketException:  zh_cn 如果套接字不能被打开，或不能将其绑定到指定的本地端口。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。 See also checkListen
public	DatagramSocket(int port, InetAddress laddr) throws SocketException zh_cn 创建数据报套接字，将其绑定到指定的本地地址。本地端口必须在 0 到 65535 之间（包括两者）。如果 IP 地址为 0.0.0.0，套接字将被绑定到通配符地址，IP 地址由内核选择。 如果存在安全管理器，则首先使用 port 参数作为参数调用其 checkListen 方法，以确保允许该操作。这可能会导致 SecurityException 异常。 port zh_cn 要使用的本地端口 laddr zh_cn 要绑定的本地地址 Throws SocketException:  zh_cn 如果套接字不能被打开，或不能将其绑定到指定的本地端口。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。 since JDK1.1 See also checkListen

Methods
public void	bind(SocketAddress addr) throws SocketException zh_cn 将此 DatagramSocket 绑定到特定的地址和端口。 如果地址为 null，则系统将挑选一个临时端口和一个有效本地地址来绑定套接字。 addr zh_cn 要绑定的地址和端口。 Throws SocketException:  zh_cn 如果绑定过程中发生错误，或者套接字已经被绑定。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkListen 方法不允许进行该操作。 Throws IllegalArgumentException:  zh_cn 如果 addr 是不受此套接字支持的 SocketAddress 子类。 since 1.4
public void	close() zh_cn 关闭此数据报套接字。 在此套接字上 #receive 中所有当前阻塞的线程将会抛出 SocketException。 如果此套接字有一个与之关联的通道，则关闭该通道。 revised 1.4 spec JSR-51
public void	connect(InetAddress address, int port) zh_cn 将套接字连接到此套接字的远程地址。当套接字连接到远程地址时，包就只能从该地址发送或接收。默认情况下不连接数据报套接字。 如果套接字要连接的远程目标不存在或不可到达，并且收到了该地址的目标不可达 ICMP 包，那么后续发送和接收的调用可能会抛出 PortUnreachableException。注意，不能保证一定抛出该异常。 在连接时检查调用者对给定主机和端口的发送和接收数据报权限。当连接建立起来后，接收和发送除了对包和套接字的地址和端口进行匹配外，对传入和传出的包将不再执行任何安全性检查。对于发送操作，如果设置了包的地址并且包的地址和套接字的地址不匹配，则将抛出 IllegalArgumentException。连接到多播地址的套接字只能用于发送包。 address zh_cn 套接字的远程地址。 port zh_cn 套接字的远程端口。 Throws IllegalArgumentException:  zh_cn 如果地址为 null，或端口超出了范围。 Throws SecurityException:  zh_cn 如果不允许调用者向此地址和端口发送也不允许从此地址接收数据报。 See also disconnect, send, receive
public void	connect(SocketAddress addr) throws SocketException zh_cn 将此套接字连接到远程套接字地址（IP 地址 + 端口号）。 addr zh_cn 远程地址。 Throws SocketException:  zh_cn 如果连接失败 Throws IllegalArgumentException:  zh_cn 如果 addr 为 null 或者 addr 是不受此套接字支持的 SocketAddress 子类。 since 1.4 See also connect
public void	disconnect() zh_cn 断开套接字的连接。如果套接字没有连接，则此方法不执行任何操作。 See also connect
public void	receive(DatagramPacket p) throws IOException zh_cn 从此套接字接收数据报包。当此方法返回时，DatagramPacket 的缓冲区填充了接收的数据。数据报包也包含发送方的 IP 地址和发送方机器上的端口号。 此方法在接收到数据报前一直阻塞。数据报包对象的 length 字段包含所接收信息的长度。如果信息比包的长度长，该信息将被截短。 如果存在安全管理器，而安全管理器的 checkAccept 方法不允许接收操作，则包不能被接收。 p zh_cn 要放置传入数据的 DatagramPacket。 Throws IOException:  zh_cn 如果发生 I/O 错误。 Throws SocketTimeoutException:  zh_cn 如果先前调用了 setSoTimeout 且超时值已过。 Throws PortUnreachableException:  zh_cn 套接字连接到当前不可达的目标时可能抛出。注意，不能保证一定抛出该异常。 Throws java.nio.channels.IllegalBlockingModeException:  zh_cn 如果此套接字具有相关联的通道，且通道处于非阻塞模式。 revised 1.4 spec JSR-51 See also java.net.DatagramPacket, java.net.DatagramSocket
public void	send(DatagramPacket p) throws IOException zh_cn 从此套接字发送数据报包。DatagramPacket 包含的信息指示：将要发送的数据、其长度、远程主机的 IP 地址和远程主机的端口号。 如果存在安全管理器，且套接字当前没有连接到远程地址，则此方法首先执行某些安全性检查。首先，如果p.getAddress().isMulticastAddress() 为 true，则此方法以 p.getAddress() 作为参数调用安全管理器的 checkMulticast 方法。如果该表达式的值为 false，此方法改为调用安全管理器的以 p.getAddress().getHostAddress() 和 p.getPort() 为参数的 checkConnect 方法。如果不允许该操作，则每次调用安全管理器方法都会导致 SecurityException。 p zh_cn 将要发送的 DatagramPacket。 Throws IOException:  zh_cn 如果发生 I/O 错误。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkMulticast 或 checkConnect 方法不允许发送。 Throws PortUnreachableException:  zh_cn 套接字连接到当前不可达的目标时可能抛出。注意，不能保证一定抛出该异常。 Throws java.nio.channels.IllegalBlockingModeException:  zh_cn 如果此套接字具有相关联的通道，且通道处于非阻塞模式。 revised 1.4 spec JSR-51 See also java.net.DatagramPacket, checkMulticast(InetAddress), checkConnect

Properties
public boolean	isBound() zh_cn 返回套接字的绑定状态。 return zh_cn 如果将套接字成功地绑定到一个地址，则返回 true since 1.4
public void	setBroadcast(boolean on) throws SocketException zh_cn 启用/禁用 SO_BROADCAST。 on zh_cn 是否开启广播。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 since 1.4 See also getBroadcast()
public boolean	getBroadcast() throws SocketException zh_cn 检测是否启用了 SO_BROADCAST。 return zh_cn 指示是否启用 SO_BROADCAST 的 boolean 值。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 since 1.4 See also setBroadcast(boolean)
public DatagramChannel	getChannel() zh_cn 返回与此数据报套接字关联的唯一 java.nio.channels.DatagramChannel 对象（如果有）。 当且仅当通过 DatagramChannel.open 方法创建了通道本身时，数据报套接字才具有一个通道。 return zh_cn 与此数据报套接字关联的数据报通道，如果没有为通道创建套接字，则返回 null。 since 1.4 spec JSR-51
public boolean	isClosed() zh_cn 返回是否关闭了套接字。 return zh_cn 如果已经关闭了套接字，则返回 true since 1.4
public boolean	isConnected() zh_cn 返回套接字的连接状态。 return zh_cn 如果将套接字成功地连接到服务器，则为 true。 since 1.4
public static void	setDatagramSocketImplFactory(DatagramSocketImplFactory fac) throws IOException zh_cn 为应用程序设置数据报套接字实现工厂。工厂只能指定一次。 当应用程序创建新的数据报套接字时，调用套接字实现工厂的 createDatagramSocketImpl 方法创建实际的数据报套接字实现。 除非已经设置了工厂，否则向该方法传递 null 是无操作。 如果存在安全管理器，此方法首先调用安全管理器的 checkSetFactory 方法，确保允许该操作。这可能会导致 SecurityException 异常。 fac zh_cn 所需的工厂。 Throws IOException:  zh_cn 如果设置数据报套接字工厂时发生 I/O 错误。 Throws SocketException:  zh_cn 如果已经定义该工厂。 Throws SecurityException:  zh_cn 如果安全管理器存在并且其 checkSetFactory 方法不允许进行该操作。 since 1.3 See also createDatagramSocketImpl(), checkSetFactory
public InetAddress	getInetAddress() zh_cn 返回此套接字连接的地址。如果套接字未连接，则返回 null。 return zh_cn 此套接字连接的地址。
public InetAddress	getLocalAddress() zh_cn 获取套接字绑定的本地地址。 如果存在安全管理器，则首先使用主机地址和 -1 作为参数调用其 checkConnect 方法，以查看是否允许该操作。 return zh_cn 套接字绑定的本地地址，如果套接字没有绑定或安全管理器的 checkConnect 方法不允许该操作，则返回表示任何本地地址的 InetAddress。 since 1.1 See also checkConnect
public int	getLocalPort() zh_cn 返回此套接字绑定的本地主机上的端口号。 return zh_cn 此套接字绑定的本地主机上的端口。
public SocketAddress	getLocalSocketAddress() zh_cn 返回此套接字绑定的端点的地址，如果尚未绑定则返回 null。 return zh_cn 表示此套接字的本地端点的 SocketAddress，如果尚未绑定则返回 null。 since 1.4 See also getLocalAddress(), getLocalPort(), bind(SocketAddress)
public int	getPort() zh_cn 返回此套接字的端口。如果套接字未连接，则返回 -1。 return zh_cn 此套接字连接的端口。
public void	setReceiveBufferSize(int size) throws SocketException zh_cn 将此 DatagramSocket 的 SO_RCVBUF 选项设置为指定的值。网络实现使用 SO_RCVBUF 选项作为设置底层网络 I/O 缓冲区大小的提示。网络实现也可以使用 SO_RCVBUF 设置来决定在此套接字上可以接收的包的最大大小。 由于 SO_RCVBUF 是一种提示，想要验证缓冲区设置大小的应用程序应该调用 #getReceiveBufferSize()。 当包到达的速度快于使用 #receive(DatagramPacket) 接收包的速度时，增大 SO_RCVBUF 可以允许网络实现缓存多个包。 注：是否能接收大于 SO_RCVBUF 的包是特定于实现的。 size zh_cn 要设置的接收缓冲区大小。此值必须大于 0。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 Throws IllegalArgumentException:  zh_cn 如果值为 0 或负。 See also getReceiveBufferSize()
public int	getReceiveBufferSize() throws SocketException zh_cn 获取此 DatagramSocket 的 SO_RCVBUF 选项的值，该值是平台在 DatagramSocket 上输入时使用的缓冲区大小。 return zh_cn 此 DatagramSocket 的 SO_RCVBUF 选项的值。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 See also setReceiveBufferSize(int)
public SocketAddress	getRemoteSocketAddress() zh_cn 返回此套接字连接的端点的地址，如果未连接则返回 null。 return zh_cn 表示此套接字远程端点的 SocketAddress，如果尚未连接则返回 null。 since 1.4 See also getInetAddress(), getPort(), connect(SocketAddress)
public void	setReuseAddress(boolean on) throws SocketException zh_cn 启用/禁用 SO_REUSEADDR 套接字选项。 对于 UDP 套接字可能有必要把超过一个的套接字绑定到相同的套接字地址。这样做的目的通常是为了接收多播包。（请参阅java.net.MulticastSocket）。如果在使用 #bind(SocketAddress) 绑定套接字之前启用 SO_REUSEADDR 套接字选项，则 SO_REUSEADDR 套接字选项允许将多个套接字绑定到相同的套结字地址。 注意：所有现有平台都不支持此功能，因此不管是否将忽略此选项，它都是特定于实现的。但是，如果此功能不受支持，则#getReuseAddress() 将始终返回 false。 当创建 DatagramSocket 时，禁用 SO_REUSEADDR 的初始设置。 在绑定套接字（请参阅 #isBound()）后启用或禁用 SO_REUSEADDR 时的行为是不确定的。 on zh_cn 是否启用 SO_REUSEADDR 套接字选项 Throws SocketException:  zh_cn SO_RESUEADDR 套接字选项时发生错误，或者关闭了套接字。 since 1.4 See also getReuseAddress(), bind(SocketAddress), isBound(), isClosed()
public boolean	getReuseAddress() throws SocketException zh_cn 检测是否启用了 SO_REUSEADDR。 return zh_cn 指示是否启用 SO_REUSEADDR 的 boolean 值。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 since 1.4 See also setReuseAddress(boolean)
public void	setSendBufferSize(int size) throws SocketException zh_cn 将此 DatagramSocket 的 SO_SNDBUF 选项设置为指定的值。网络实现使用 SO_SNDBUF 选项作为设置底层网络 I/O 缓冲区大小的提示。网络实现也可以使用 SO_SNDBUF 设置来决定在此套接字上可以传送的包的最大大小。 由于 SO_SNDBUF 是一种提示，想要验证缓冲区大小的应用程序应该调用 #getSendBufferSize()。 当发送率很高时，增大缓冲区的大小可以允许网络实现对多个传出包进行排队。 注：如果使用 #send(DatagramPacket) 来发送比 SO_SNDBUF 设置大的 DatagramPacket，包是被发送还是被丢弃是特定于实现的。 size zh_cn 将设置的发送缓冲区大小。此值必须大于 0。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 Throws IllegalArgumentException:  zh_cn 如果值为 0 或负。 See also getSendBufferSize()
public int	getSendBufferSize() throws SocketException zh_cn 获取此 DatagramSocket 的 SO_SNDBUF 选项的值，该值是平台在 DatagramSocket 上输出时使用的缓冲区大小。 return zh_cn 此 DatagramSocket 的 SO_SNDBUF 选项的值。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 See also setSendBufferSize
public void	setSoTimeout(int timeout) throws SocketException zh_cn 启用/禁用带有指定超时值的 SO_TIMEOUT，以毫秒为单位。将此选项设为非零的超时值时，对此 DatagramSocket 调用 receive() 将只阻塞此时间长度。如果超过超时值，将引发 java.net.SocketTimeoutException，虽然 DatagramSocket 仍旧有效。选项必须在进入阻塞操作前被启用才能生效。超时值必须是 > 0 的数。超时值为 0 被解释为无穷大超时值。 timeout zh_cn 指定的以毫秒为单位的超时值。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 since JDK1.1 See also getSoTimeout()
public int	getSoTimeout() throws SocketException zh_cn 获取 SO_TIMEOUT 的设置。返回 0 意味着禁用了选项（即无穷大的超时值）。 return zh_cn SO_TIMEOUT 的设置。 Throws SocketException:  zh_cn 如果底层协议出现错误，例如 UDP 错误。 since JDK1.1 See also setSoTimeout(int)
public void	setTrafficClass(int tc) throws SocketException zh_cn 为从此 DatagramSocket 上发送的数据报在 IP 数据报头中设置流量类别 (traffic class) 或服务类型八位组 (type-of-service octet)。由于底层网络实现可能忽略此值，应用程序应该将其视为一种提示。 tc 的值必须在 0 <= tc <= 255 范围内，否则将抛出 IllegalArgumentException。 注： 对于 Internet Protocol v4 该值由包含优先级和 TOS 字段的八位组组成，这在 RFC 1349 中有详细叙述。TOS 字段是由以下逐位或所得值创建的位集： IPTOS_LOWCOST (0x02) IPTOS_RELIABILITY (0x04) IPTOS_THROUGHPUT (0x08) IPTOS_LOWDELAY (0x10) 末尾的最低位常常被忽略，因为该位对应于 MBZ（必须为 0）位。 设置优先级字段中的位可能导致 SocketException，指示不允许该操作。 对于 Internet Protocol v6 tc 是将被放置到 IP 头部的 sin6_flowinfo 字段中的值。 tc zh_cn 此位集的 int 值。 Throws SocketException:  zh_cn 如果设置流量类别或服务类型时出现错误 since 1.4 See also getTrafficClass
public int	getTrafficClass() throws SocketException zh_cn 为从此 DatagramSocket 上发送的包获取 IP 数据报头中的流量类别或服务类型。 由于底层网络实现可能忽略使用 #setTrafficClass(int) 设置的流量类别或服务类型，因而此方法可能返回一个不同于以前用#setTrafficClass(int) 在此 DatagramSocket 上设置的值。 return zh_cn 已经设置的流量类别或服务类型 Throws SocketException:  zh_cn 如果获取流量类别或服务类型值时出现错误。 since 1.4 See also setTrafficClass(int)