模块 java.base

包 java.net

类 DatagramSocket

java.lang.Object

java.net.DatagramSocket

所有已实现的接口：

Closeable , AutoCloseable

已知子类：

MulticastSocket

public class DatagramSocket extends Object implements Closeable 
      

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

数据报套接字是数据包传送服务的发送点或接收点。在数据报套接字上发送或接收的每个数据包都被单独寻址和路由。从一台机器发送到另一台机器的多个数据包可能会有不同的路由，并且可能以任何顺序到达。

在可能的情况下，新建的 DatagramSocket 启用了 SO_BROADCAST 套接字选项，以允许传输广播数据报。为了接收广播数据包，DatagramSocket 应该绑定到通配符地址。在某些实现中，当 DatagramSocket 绑定到更具体的地址时，也可能会收到广播数据包。

示例：

       DatagramSocket s = new DatagramSocket(null);
       s.bind(new InetSocketAddress(8888));
  

相当于：

       DatagramSocket s = new DatagramSocket(8888);
  

这两种情况都将创建一个能够在 UDP 端口 8888 上接收广播的 DatagramSocket。

DatagramSocket 类定义了设置和获取多个套接字选项的便捷方法。此类还定义了 setOption 和 getOption 方法来设置和查询套接字选项。 DatagramSocket 支持以下套接字选项：

套接字选项

选项名称	Description
SO_SNDBUF	套接字发送缓冲区的大小（以字节为单位）
SO_RCVBUF	套接字接收缓冲区的大小（以字节为单位）
SO_REUSEADDR	重复使用地址
SO_BROADCAST	允许传输广播数据报
IP_TOS	互联网协议 (IP) 标头中的服务类型 (ToS) 八位字节

此外，DatagramSocket类定义了join和leave多播组的方法，并支持多播选项，这在joining、离开或向多播组发送数据报时很有用。支持以下多播选项：

组播选项

选项名称	Description
IP_MULTICAST_IF	网际协议 (IP) 多播数据报的网络接口
IP_MULTICAST_TTL	time-to-live 用于 Internet 协议 (IP) 多播数据报
IP_MULTICAST_LOOP	互联网协议 (IP) 多播数据报的环回

一个实现也可能支持额外的选项。

API 注意：

使用 DatagramSocket 进行多播

DatagramChannel 实现 MulticastChannel 接口并提供用于发送和接收多播数据报的替代 API。 MulticastChannel API 支持 任何来源 和 来源特定 多播。考虑使用 DatagramChannel 进行多播。

DatagramSocket 可直接用于多播。但是，与 MulticastSocket 相反，DatagramSocket 默认情况下不会调用 setReuseAddress(boolean) 方法来启用 SO_REUSEADDR 套接字选项。如果创建一个 DatagramSocket 打算稍后加入多播组，调用者应该考虑显式启用 SO_REUSEADDR 选项。

DatagramSocket 的实例可用于发送或接收多播数据报包。不必为了发送多播数据报而加入多播组。但是，在发送多播数据报包之前，应首先使用 setOption 和 StandardSocketOptions.IP_MULTICAST_IF 配置用于发送多播数据报的默认传出接口：

  DatagramSocket sender = new DatagramSocket(new InetSocketAddress(0));
  NetworkInterface outgoingIf = NetworkInterface.getByName("en0");
  sender.setOption(StandardSocketOptions.IP_MULTICAST_IF, outgoingIf);

  // optionally configure multicast TTL; the TTL defines the scope of a
  // multicast datagram, for example, confining it to host local (0) or
  // link local (1) etc...
  int ttl = ...; // a number between 0 and 255
  sender.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);

  // send a packet to a multicast group
  byte[] msgBytes = ...;
  InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
  int port = 6789;
  InetSocketAddress dest = new InetSocketAddress(mcastaddr, port);
  DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, dest);
  sender.send(hi);
  

DatagramSocket 的实例也可用于接收多播数据报包。应创建一个旨在接收多播数据报的DatagramSocket未绑定.在绑定套接字之前，setReuseAddress(true) 应该配置：

  DatagramSocket socket = new DatagramSocket(null); // unbound
  socket.setReuseAddress(true); // set reuse address before binding
  socket.bind(new InetSocketAddress(6789)); // bind

  // joinGroup 228.5.6.7
  InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
  InetSocketAddress group = new InetSocketAddress(mcastaddr, 0);
  NetworkInterface netIf = NetworkInterface.getByName("en0");
  socket.joinGroup(group, netIf);
  byte[] msgBytes = new byte[1024]; // up to 1024 bytes
  DatagramPacket packet = new DatagramPacket(msgBytes, msgBytes.length);
  socket.receive(packet);
  ....
  // eventually leave group
  socket.leaveGroup(group, netIf);
  

平台依赖

多播实现旨在直接映射到本地多播设施。因此，在开发接收 IP 多播数据报的应用程序时应考虑以下事项：

1. 与 DatagramChannel 相反，DatagramSocket 的构造函数不允许指定底层套接字的 ProtocolFamily 。因此，底层套接字的协议族可能与DatagramSocket 将尝试加入的多播组的协议族不对应。
   当多播组的地址对应于另一个协议系列时，无法保证具有在一个协议系列中创建的底层套接字的DatagramSocket可以加入和接收多播数据报。例如，如果 DatagramSocket 到 IPv6 套接字可以加入 IPv4 多播组并接收发送到该组的多播数据报，则它是特定于实现的。
2. 在加入多播组之前，DatagramSocket 应该绑定到通配符地址。如果套接字绑定到特定地址，而不是通配符地址，那么如果套接字接收多播数据报，则它是特定于实现的。
3. 应该在绑定套接字之前启用 SO_REUSEADDR 选项。这是允许该组的多个成员绑定到同一地址所必需的。

自从：

1.0

参见：

• DatagramPacket
• DatagramChannel

构造方法总结

构造方法

修饰符	构造方法	描述
	DatagramSocket()	构造数据报套接字并将其绑定到本地主机上的任何可用端口。
	DatagramSocket(int port)	构造数据报套接字并将其绑定到本地主机上的指定端口。
	DatagramSocket(int port, InetAddress laddr)	创建绑定到指定本地地址的数据报套接字。
protected	DatagramSocket(DatagramSocketImpl impl)	使用指定的 DatagramSocketImpl 创建一个未绑定的数据报套接字。
	DatagramSocket(SocketAddress bindaddr)	创建一个数据报套接字，绑定到指定的本地套接字地址。

方法总结

修饰符和类型	方法	描述
void	bind(SocketAddress addr)	将此 DatagramSocket 绑定到特定地址和端口。
void	close()	关闭此数据报套接字。
void	connect(InetAddress address, int port)	将套接字连接到此套接字的远程地址。
void	connect(SocketAddress addr)	将此套接字连接到远程套接字地址（IP 地址 + 端口号）。
void	disconnect()	断开套接字。
boolean	getBroadcast()	测试是否启用了 SO_BROADCAST。
DatagramChannel	getChannel()	返回与此数据报套接字关联的唯一 DatagramChannel 对象（如果有）。
InetAddress	getInetAddress()	返回此套接字连接到的地址。
InetAddress	getLocalAddress()	获取套接字绑定到的本地地址。
int	getLocalPort()	返回此套接字绑定到的本地主机上的端口号。
SocketAddress	getLocalSocketAddress()	返回此套接字绑定到的端点的地址。
<T> T	getOption(SocketOption<T> name)	返回套接字选项的值。
int	getPort()	返回此套接字连接到的端口号。
int	getReceiveBufferSize()	获取此 DatagramSocket 的 SO_RCVBUF 选项的值，即平台用于在此 DatagramSocket 上输入的缓冲区大小（以字节为单位）。
SocketAddress	getRemoteSocketAddress()	返回此套接字连接到的端点的地址，如果未连接则返回 null。
boolean	getReuseAddress()	测试是否启用了 SO_REUSEADDR。
int	getSendBufferSize()	获取此 DatagramSocket 的 SO_SNDBUF 选项的值，即平台用于在此 DatagramSocket 上输出的缓冲区大小（以字节为单位）。
int	getSoTimeout()	检索 SO_TIMEOUT 的设置。返回 0 意味着该选项被禁用（即无限超时）。
int	getTrafficClass()	获取从此 DatagramSocket 发送的数据包的 IP 数据报标头中的流量类或服务类型。
boolean	isBound()	返回套接字的绑定状态。
boolean	isClosed()	返回套接字是否关闭。
boolean	isConnected()	返回套接字的连接状态。
void	joinGroup(SocketAddress mcastaddr, NetworkInterface netIf)	加入多播组。
void	leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)	在指定的本地接口上保留多播组。
void	receive(DatagramPacket p)	从此套接字接收数据报包。
void	send(DatagramPacket p)	从此套接字发送数据报包。
void	setBroadcast(boolean on)	启用/禁用 SO_BROADCAST。
static void	setDatagramSocketImplFactory(DatagramSocketImplFactory fac)	已弃用。 使用 DatagramChannel 或直接子类化 DatagramSocket。
<T> DatagramSocket	setOption(SocketOption<T> name, T value)	设置套接字选项的值。
void	setReceiveBufferSize(int size)	将 SO_RCVBUF 选项设置为此 DatagramSocket 的指定值。
void	setReuseAddress(boolean on)	启用/禁用 SO_REUSEADDR 套接字选项。
void	setSendBufferSize(int size)	将 SO_SNDBUF 选项设置为此 DatagramSocket 的指定值。
void	setSoTimeout(int timeout)	启用/禁用指定超时的 SO_TIMEOUT，以毫秒为单位。
void	setTrafficClass(int tc)	为从此 DatagramSocket 发送的数据报设置 IP 数据报头中的流量类别或服务类型八位字节。
Set<SocketOption<?>>	supportedOptions()	返回此套接字支持的一组套接字选项。

在类 java.lang.Object 中声明的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

DatagramSocket

public DatagramSocket() throws SocketException 
            

构造数据报套接字并将其绑定到本地主机上的任何可用端口。套接字将绑定到 wildcard 地址。

如果有安全管理器，它的 checkListen 方法首先以 0 作为参数调用，以确保允许操作。这可能会导致 SecurityException。

抛出：

SocketException - 如果无法打开套接字，或者无法绑定套接字。

SecurityException - 如果安全管理器存在且其 checkListen 方法不允许该操作。

参见：

• SecurityManager.checkListen(int)

DatagramSocket

protected DatagramSocket(DatagramSocketImpl  impl)
            

使用指定的 DatagramSocketImpl 创建一个未绑定的数据报套接字。

参数：

impl - 一个实例DatagramSocketImpl子类希望在 DatagramSocket 上使用。

自从：

1.4

DatagramSocket

public DatagramSocket(SocketAddress  bindaddr) throws SocketException 
            

创建一个数据报套接字，绑定到指定的本地套接字地址。

如果地址是null，将创建一个未绑定的套接字。

如果有安全管理器，它的 checkListen 方法首先会以套接字地址中的端口作为参数调用，以确保允许操作。这可能会导致 SecurityException。

参数：

bindaddr - 要绑定的本地套接字地址，或 null 用于未绑定的套接字。

抛出：

SocketException - 如果套接字无法打开，或者套接字无法绑定到指定的本地端口。

SecurityException - 如果安全管理器存在且其 checkListen 方法不允许该操作。

IllegalArgumentException - 如果 bindaddr 是此套接字不支持的 SocketAddress 子类。

自从：

1.4

参见：

• SecurityManager.checkListen(int)

DatagramSocket

public DatagramSocket(int port) throws SocketException 
            

构造数据报套接字并将其绑定到本地主机上的指定端口。套接字将绑定到 wildcard 地址。

如果有安全管理器，它的 checkListen 方法首先以 port 参数作为参数调用，以确保允许操作。这可能会导致 SecurityException。

参数：

port - 在绑定操作中使用的本地端口。

抛出：

SocketException - 如果套接字无法打开，或者套接字无法绑定到指定的本地端口。

SecurityException - 如果安全管理器存在且其 checkListen 方法不允许该操作。

IllegalArgumentException - 如果端口是 超出范围。

参见：

• SecurityManager.checkListen(int)

DatagramSocket

public DatagramSocket(int port, InetAddress  laddr) throws SocketException 
            

创建绑定到指定本地地址的数据报套接字。

本地端口必须介于 0 和 65535 之间（含）。 zero 端口号将使系统在 bind 操作中选择一个临时端口。

如果 IP 地址是 wildcard 地址，或者是 null ，套接字将绑定到通配符地址。

如果有安全管理器，它的 checkListen 方法首先以 port 参数作为参数调用，以确保允许操作。这可能会导致 SecurityException。

参数：

port - 在绑定操作中使用的本地端口。

laddr - 要绑定的本地地址（可以是 null ）

抛出：

SocketException - 如果套接字无法打开，或者套接字无法绑定到指定的本地端口。

SecurityException - 如果安全管理器存在且其 checkListen 方法不允许该操作。

IllegalArgumentException - 如果端口是 超出范围。

自从：

1.1

参见：

• SecurityManager.checkListen(int)

方法详情

bind

public void bind(SocketAddress  addr) throws SocketException 
            

将此 DatagramSocket 绑定到特定地址和端口。

如果地址是 null ，那么系统将选择一个临时端口和一个有效的本地地址来绑定套接字。

参数：

addr - 要绑定的地址和端口。

抛出：

SocketException - 如果绑定期间发生任何错误，或者套接字已经绑定。

SecurityException - 如果安全管理器存在且其 checkListen 方法不允许该操作。

IllegalArgumentException - 如果 addr 是此套接字不支持的 SocketAddress 子类。

自从：

1.4

connect

public void connect(InetAddress  address, int port)
            

将套接字连接到此套接字的远程地址。当套接字连接到远程地址时，数据包只能发送到该地址或从该地址接收。默认情况下，数据报套接字未连接。如果套接字已经关闭，则此方法无效。

如果未绑定此套接字，则此方法将首先使套接字绑定到自动分配的地址，就好像调用带参数 null 的 bind 方法一样。如果套接字连接到的远程目的地不存在，或者无法到达，并且如果已收到该地址的 ICMP 目的地无法到达的数据包，则随后的发送或接收调用可能会抛出 PortUnreachableException。请注意，不能保证会抛出异常。

如果安装了安全管理器，则会调用它来检查对远程地址的访问。具体来说，如果给定的 address 是一个 multicast address ，则使用给定的 address 调用安全管理器的 checkMulticast 方法。否则，将调用安全管理器的 checkConnect 和 checkAccept 方法，使用给定的 address 和 port 来验证是否允许分别发送和接收数据报。

应注意确保连接的数据报套接字不与不受信任的代码共享。连接套接字时，receive 和 send 不会执行任何安全检查在传入和传出数据包上，除了匹配数据包和套接字的地址和端口。在发送操作中，如果设置了数据包的地址并且数据包的地址和套接字的地址不匹配，则会抛出IllegalArgumentException。连接到多播地址的套接字只能用于发送数据包。套接字的 套接字接收缓冲区 中的数据报在调用此方法之前尚未被 已收到 处理，可能会被丢弃。

参数：

address - 套接字的远程地址

port - 套接字的远程端口。

抛出：

IllegalArgumentException - 如果地址为空，或者端口为 超出范围。

SecurityException - 如果安装了安全管理器并且它不允许访问给定的远程地址

UncheckedIOException - 如果连接失败可能会抛出，例如，如果目标地址不可路由

自从：

1.2

参见：

• disconnect()

connect

public void connect(SocketAddress  addr) throws SocketException 
            

将此套接字连接到远程套接字地址（IP 地址 + 端口号）。

如果给定一个 InetSocketAddress ，此方法的行为就像使用给定的套接字地址 IP 地址和端口号调用 connect(InetAddress,int) 一样，除了可能引发的 SocketException 没有包装在 UncheckedIOException 中。套接字的 套接字接收缓冲区 中的数据报在调用此方法之前尚未被 已收到 处理，可能会被丢弃。

参数：

addr - 远程地址。

抛出：

SocketException - 如果连接失败

IllegalArgumentException - 如果 addr 是 null，或者 addr 是此套接字不支持的 SocketAddress 子类

SecurityException - 如果安装了安全管理器并且它不允许访问给定的远程地址

自从：

1.4

disconnect

public void disconnect()
            

断开套接字。如果套接字已关闭或未连接，则此方法无效。

API 注意：

如果此方法抛出 UncheckedIOException，则套接字可能处于未指定状态。强烈建议在断开连接失败时关闭套接字。

抛出：

UncheckedIOException - 如果断开连接未能解除关联并将套接字恢复到一致状态，则可能会抛出。

自从：

1.2

参见：

• connect(java.net.InetAddress, int)

isBound

public boolean isBound()
            

返回套接字的绑定状态。

如果在 closed 之前绑定了套接字，则此方法将在套接字关闭后继续返回 true。

返回：

如果套接字成功绑定到地址，则为真

自从：

1.4

isConnected

public boolean isConnected()
            

返回套接字的连接状态。

如果套接字在 closed 之前已连接，则此方法将在套接字关闭后继续返回 true。

返回：

如果套接字成功连接到服务则为真

自从：

1.4

getInetAddress

public InetAddress  getInetAddress()
            

返回此套接字连接到的地址。如果未连接套接字，则返回 null。

如果套接字在 closed 之前已连接，则此方法将在套接字关闭后继续返回已连接的地址。

返回：

此套接字连接到的地址。

自从：

1.2

getPort

public int getPort()
            

返回此套接字连接到的端口号。如果未连接套接字，则返回 -1。

如果 socket 在 closed 之前被连接，那么这个方法将在 socket 关闭后继续返回连接的端口号。

返回：

此套接字连接到的端口号。

自从：

1.2

getRemoteSocketAddress

public SocketAddress  getRemoteSocketAddress()
            

返回此套接字连接到的端点的地址，如果未连接则返回 null。

如果套接字在 closed 之前已连接，则此方法将在套接字关闭后继续返回已连接的地址。

返回：

一个 SocketAddress 代表这个套接字的远程端点，或者 null 如果它还没有连接。

自从：

1.4

参见：

• getInetAddress()
• getPort()
• connect(SocketAddress)

getLocalSocketAddress

public SocketAddress  getLocalSocketAddress()
            

返回此套接字绑定到的端点的地址。

返回：

一个 SocketAddress 表示此套接字的本地端点，或者 null 如果它已关闭或尚未绑定。

自从：

1.4

参见：

• getLocalAddress()
• getLocalPort()
• bind(SocketAddress)

send

public void send(DatagramPacket  p) throws IOException 
            

从此套接字发送数据报包。 DatagramPacket 包含指示要发送的数据、其长度、远程主机的 IP 地址以及远程主机上的端口号的信息。

如果存在安全管理器，并且套接字当前未连接到远程地址，则此方法首先执行一些安全检查。首先，如果 p.getAddress().isMulticastAddress() 为真，则此方法以 p.getAddress() 作为参数调用安全管理器的 checkMulticast 方法。如果该表达式的计算结果为假，则此方法会调用安全管理器的 checkConnect 方法，参数为 p.getAddress().getHostAddress() 和 p.getPort() 。如果不允许操作，则每次调用安全管理器方法都可能导致 SecurityException。

参数：

p - 要发送的 DatagramPacket。

抛出：

IOException - 如果发生 I/O 错误。

SecurityException - 如果安全管理器存在且其 checkMulticast 或 checkConnect 方法不允许发送。

PortUnreachableException - 如果套接字连接到当前无法到达的目的地，则可能会抛出。请注意，不能保证会抛出异常。

IllegalBlockingModeException - 如果此套接字有关联的通道，并且通道处于非阻塞模式。

IllegalArgumentException - 如果套接字已连接，并且连接地址和数据包地址不同，或者套接字未连接且未设置数据包地址，或者其端口为超出范围。

参见：

• DatagramPacket
• SecurityManager.checkMulticast(InetAddress)
• SecurityManager.checkConnect(java.lang.String, int)

receive

public void receive(DatagramPacket  p) throws IOException 
            

从此套接字接收数据报包。此方法会阻塞，直到收到数据报。当此方法返回时，DatagramPacket 的缓冲区将填充接收到的数据。数据报包还包含发件人的 IP 地址和发件人机器上的端口号。数据报包对象的 length 字段包含接收到的消息的长度。如果消息比数据包的长度长，消息将被截断。

此方法在以下情况下是可中断的：

1. 数据报套接字是 联系 和 DatagramChannel 。在这种情况下，中断接收数据报包的线程将关闭底层通道并导致此方法抛出 ClosedByInterruptException 并设置中断状态。
2. 数据报套接字使用系统默认套接字实现和虚拟线程^PREVIEW 正在接收数据报包。在那种情况下，中断虚拟线程将导致它唤醒并关闭套接字。然后此方法将抛出 SocketException 并设置中断状态。

如果有安全管理器，并且套接字当前未连接到远程地址，则如果安全管理器的 checkAccept 方法不允许，则无法接收数据包。安全管理器不允许的数据报被静默丢弃。

参数：

p - 用于放置传入数据的 DatagramPacket。

抛出：

IOException - 如果发生 I/O 错误。

SocketTimeoutException - 如果先前调用了 setSoTimeout 并且超时已过期。

PortUnreachableException - 如果套接字连接到当前无法到达的目的地，则可能会抛出。请注意，不能保证会抛出异常。

IllegalBlockingModeException - 如果此套接字有关联的通道，并且通道处于非阻塞模式。

参见：

• DatagramPacket
• DatagramSocket

getLocalAddress

public InetAddress  getLocalAddress()
            

获取套接字绑定到的本地地址。

如果有安全管理器，它的 checkConnect 方法首先以主机地址和 -1 作为参数调用，以查看是否允许该操作。

返回：

套接字绑定到的本地地址，null 如果套接字关闭，或者 InetAddress 表示 wildcard 地址，如果套接字未绑定，或者安全管理器 checkConnect 方法不允许操作

自从：

1.1

参见：

• SecurityManager.checkConnect(java.lang.String, int)

getLocalPort

public int getLocalPort()
            

返回此套接字绑定到的本地主机上的端口号。

返回：

此套接字绑定到的本地主机上的端口号，如果套接字已关闭，则为 -1，如果尚未绑定，则为 0。

setSoTimeout

public void setSoTimeout(int timeout) throws SocketException 
            

启用/禁用指定超时的 SO_TIMEOUT，以毫秒为单位。将此选项设置为正超时值后，为此 DatagramSocket 调用 receive() 将仅阻塞这段时间。如果超时到期，一个java.net.SocketTimeoutException被引发，尽管 DatagramSocket 仍然有效。零超时被解释为无限超时。选项必须在进入阻塞操作之前启用才能生效。

参数：

timeout - 以毫秒为单位的指定超时。

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

IllegalArgumentException - 如果 timeout 为负

自从：

1.1

参见：

• getSoTimeout()

getSoTimeout

public int getSoTimeout() throws SocketException 
            

检索 SO_TIMEOUT 的设置。返回 0 意味着该选项被禁用（即无限超时）。

返回：

SO_TIMEOUT 的设置

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

自从：

1.1

参见：

• setSoTimeout(int)

setSendBufferSize

public void setSendBufferSize(int size) throws SocketException 
            

将 SO_SNDBUF 选项设置为此 DatagramSocket 的指定值。网络实现使用 SO_SNDBUF 选项作为调整底层网络 I/O 缓冲区大小的提示。网络实现也可以使用 SO_SNDBUF 设置来确定可以在此套接字上发送的数据包的最大大小。

由于 SO_SNDBUF 是一个提示，想要验证缓冲区大小的应用程序应该调用 getSendBufferSize() 。

增加缓冲区大小可能会允许多个传出数据包在发送速率较高时由网络实现排队。

注意：如果 send(DatagramPacket) 用于发送大于 SO_SNDBUF 设置的 DatagramPacket，则发送或丢弃数据包是特定于实现的。

API 注意：

如果是 size > 0 ，这个方法相当于调用 setOption(StandardSocketOptions.SO_SNDBUF, size) 。

参数：

size - 设置发送缓冲区大小的大小，以字节为单位。该值必须大于 0。

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

IllegalArgumentException - 如果值为 0 或负数。

自从：

1.2

参见：

• getSendBufferSize()
• StandardSocketOptions.SO_SNDBUF

getSendBufferSize

public int getSendBufferSize() throws SocketException 
            

获取此 DatagramSocket 的 SO_SNDBUF 选项的值，即平台用于在此 DatagramSocket 上输出的缓冲区大小（以字节为单位）。

API 注意：

此方法相当于调用 getOption(StandardSocketOptions.SO_SNDBUF) 。

返回：

这个 DatagramSocket 的 SO_SNDBUF 选项的值

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

自从：

1.2

参见：

• setSendBufferSize(int)
• StandardSocketOptions.SO_SNDBUF

setReceiveBufferSize

public void setReceiveBufferSize(int size) throws SocketException 
            

将 SO_RCVBUF 选项设置为此 DatagramSocket 的指定值。网络实现使用 SO_RCVBUF 选项作为调整底层网络 I/O 缓冲区大小的提示。网络实现也可以使用 SO_RCVBUF 设置来确定可以在此套接字上接收的数据包的最大大小。

因为 SO_RCVBUF 是一个提示，所以想要验证缓冲区大小的应用程序应该调用 getReceiveBufferSize() 。

当数据包到达速度快于使用 receive(DatagramPacket) 接收速度时，增加 SO_RCVBUF 可能允许网络实现缓冲多个数据包。

注意：是否可以接收到大于 SO_RCVBUF 的数据包是特定于实现的。

API 注意：

如果是 size > 0 ，这个方法相当于调用 setOption(StandardSocketOptions.SO_RCVBUF, size) 。

参数：

size - 设置接收缓冲区大小的大小，以字节为单位。该值必须大于 0。

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

IllegalArgumentException - 如果值为 0 或负数。

自从：

1.2

参见：

• getReceiveBufferSize()
• StandardSocketOptions.SO_RCVBUF

getReceiveBufferSize

public int getReceiveBufferSize() throws SocketException 
            

获取此 DatagramSocket 的 SO_RCVBUF 选项的值，即平台用于在此 DatagramSocket 上输入的缓冲区大小（以字节为单位）。

API 注意：

此方法等同于调用 getOption(StandardSocketOptions.SO_RCVBUF) 。

返回：

这个 DatagramSocket 的 SO_RCVBUF 选项的值

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

自从：

1.2

参见：

• setReceiveBufferSize(int)
• StandardSocketOptions.SO_RCVBUF

setReuseAddress

public void setReuseAddress(boolean on) throws SocketException 
            

启用/禁用 SO_REUSEADDR 套接字选项。

对于 UDP 套接字，可能需要将多个套接字绑定到同一套接字地址。这通常是为了接收多播数据包（参见 MulticastSocket ）。如果在使用 bind(SocketAddress) 绑定套接字之前启用 SO_REUSEADDR 套接字选项，则 SO_REUSEADDR 套接字选项允许将多个套接字绑定到相同的套接字地址。

注意：并非所有现有平台都支持此功能，因此是否忽略此选项取决于具体实现。但是，如果不支持，则 getReuseAddress() 将始终返回 false。

创建 DatagramSocket 时，禁用 SO_REUSEADDR 的初始设置。

未定义在绑定套接字后启用或禁用 SO_REUSEADDR 时的行为（请参阅 isBound() ）。

API 注意：

此方法相当于调用 setOption(StandardSocketOptions.SO_REUSEADDR, on) 。

参数：

on - 是否启用或禁用

抛出：

SocketException - 如果启用或禁用 SO_REUSEADDR 套接字选项时发生错误，或者套接字已关闭。

自从：

1.4

参见：

• getReuseAddress()
• bind(SocketAddress)
• isBound()
• isClosed()
• StandardSocketOptions.SO_REUSEADDR

getReuseAddress

public boolean getReuseAddress() throws SocketException 
            

测试是否启用了 SO_REUSEADDR。

API 注意：

此方法等同于调用 getOption(StandardSocketOptions.SO_REUSEADDR) 。

返回：

boolean 指示是否启用 SO_REUSEADDR。

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

自从：

1.4

参见：

• setReuseAddress(boolean)
• StandardSocketOptions.SO_REUSEADDR

setBroadcast

public void setBroadcast(boolean on) throws SocketException 
            

启用/禁用 SO_BROADCAST。

某些操作系统可能要求 Java 虚拟机以实现特定权限启动，以启用此选项或发送广播数据报。

API 注意：

此方法相当于调用 setOption(StandardSocketOptions.SO_BROADCAST, on) 。

参数：

on - 是否开启广播。

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

自从：

1.4

参见：

• getBroadcast()
• StandardSocketOptions.SO_BROADCAST

getBroadcast

public boolean getBroadcast() throws SocketException 
            

测试是否启用了 SO_BROADCAST。

API 注意：

此方法等同于调用 getOption(StandardSocketOptions.SO_BROADCAST) 。

返回：

boolean 指示是否启用 SO_BROADCAST。

抛出：

SocketException - 如果底层协议有错误，例如 UDP 错误。

自从：

1.4

参见：

• setBroadcast(boolean)
• StandardSocketOptions.SO_BROADCAST

setTrafficClass

public void setTrafficClass(int tc) throws SocketException 
            

为从此 DatagramSocket 发送的数据报设置 IP 数据报头中的流量类别或服务类型八位字节。由于底层网络实现可能会忽略此值，应用程序应将其视为提示。

TC必须在 0 <= tc <= 255 范围内，否则将抛出 IllegalArgumentException。

笔记：

对于 Internet 协议 v4，该值由 integer 组成，其中最低有效 8 位表示套接字发送的 IP 数据包中的 TOS 八位字节的值。 RFC 1349 定义 TOS 值如下：

• IPTOS_LOWCOST (0x02)
• IPTOS_RELIABILITY (0x04)
• IPTOS_THROUGHPUT (0x08)
• IPTOS_LOWDELAY (0x10)

最后一个低位总是被忽略，因为它对应于 MBZ（必须为零）位。

在优先级字段中设置位可能会导致 SocketException 指示不允许该操作。

对于 Internet 协议 v6，tc 是将放入 IP 标头的 sin6_flowinfo 字段中的值。

API 注意：

此方法等同于调用 setOption(StandardSocketOptions.IP_TOS, tc) 。

参数：

tc - 位集的 int 值。

抛出：

SocketException - 如果设置流量类别或服务类型时出错

自从：

1.4

参见：

• getTrafficClass()
• StandardSocketOptions.IP_TOS

getTrafficClass

public int getTrafficClass() throws SocketException 
            

获取从此 DatagramSocket 发送的数据包的 IP 数据报标头中的流量类或服务类型。

由于底层网络实现可能会忽略使用 setTrafficClass(int) 设置的流量类别或服务类型，因此此方法可能会返回与之前在此 DatagramSocket 上使用 setTrafficClass(int) 方法设置的值不同的值。

API 注意：

此方法相当于调用 getOption(StandardSocketOptions.IP_TOS) 。

返回：

已设置的流量类别或服务类型

抛出：

SocketException - 如果获取流量类别或服务类型值时出错。

自从：

1.4

参见：

• setTrafficClass(int)
• StandardSocketOptions.IP_TOS

close

public void close()
            

关闭此数据报套接字。

当前在该套接字上的 receive(java.net.DatagramPacket) 中阻塞的任何线程都将抛出 SocketException 。

如果此套接字有关联的通道，则该通道也会关闭。

指定者：

close 在接口 AutoCloseable 中

指定者：

close 在接口 Closeable 中

isClosed

public boolean isClosed()
            

返回套接字是否关闭。

返回：

如果套接字已关闭，则为真

自从：

1.4

getChannel

public DatagramChannel  getChannel()
            

返回与此数据报套接字关联的唯一 DatagramChannel 对象（如果有）。

当且仅当通道本身是通过 DatagramChannel.open 方法创建的时，数据报套接字才会有通道。

返回：

与此数据报套接字关联的数据报通道，如果此套接字不是为通道创建的，则为 null

自从：

1.4

setDatagramSocketImplFactory

@Deprecated (since ="17") public static void setDatagramSocketImplFactory(DatagramSocketImplFactory  fac) throws IOException 
            

已弃用。

使用 DatagramChannel 或直接子类化 DatagramSocket。
此方法在早期的 JDK 版本中提供了一种方法来替换 DatagramSocket 的系统范围实现。自 Java 1.4 以来，它已基本过时。如果需要，可以通过扩展 DatagramSocket 并使用以 执行 作为参数的 受保护的构造函数 创建 DatagramSocket 以使用自定义实现。

为应用程序设置数据报套接字实现工厂。工厂只能指定一次。

当应用程序创建新的数据报套接字时，将调用套接字实现工厂的 createDatagramSocketImpl 方法来创建实际的数据报套接字实现。

将 null 传递给方法是空操作，除非工厂已经设置。

如果有安全管理器，此方法首先调用安全管理器的checkSetFactory方法以确保允许操作。这可能会导致 SecurityException。

参数：

fac - 所需的工厂。

抛出：

IOException - 如果在设置数据报套接字工厂时发生 I/O 错误。

SocketException - 如果工厂已经定义。

SecurityException - 如果安全管理器存在且其 checkSetFactory 方法不允许该操作。

自从：

1.3

参见：

• DatagramSocketImplFactory.createDatagramSocketImpl()
• SecurityManager.checkSetFactory()

setOption

public <T> DatagramSocket  setOption(SocketOption <T> name, T value) throws IOException 
            

设置套接字选项的值。

类型参数：

T - 套接字选项值的类型

参数：

name - 套接字选项

value - 套接字选项的值。 null 的值可能对某些选项有效。

返回：

这个数据报套接字

抛出：

UnsupportedOperationException - 如果数据报套接字不支持该选项。

IllegalArgumentException - 如果该值对选项无效。

IOException - 如果发生 I/O 错误，或者套接字已关闭。

SecurityException - 如果设置了安全管理器并且套接字选项需要安全权限并且调用者没有所需的权限。 StandardSocketOptions 不需要任何安全许可。

NullPointerException - 如果名字是 null

自从：

9

getOption

public <T> T getOption(SocketOption <T> name) throws IOException 
            

返回套接字选项的值。

类型参数：

T - 套接字选项值的类型

参数：

name - 套接字选项

返回：

套接字选项的值。

抛出：

UnsupportedOperationException - 如果数据报套接字不支持该选项。

IOException - 如果发生 I/O 错误，或者套接字已关闭。

NullPointerException - 如果名字是 null

SecurityException - 如果设置了安全管理器并且套接字选项需要安全权限并且调用者没有所需的权限。 StandardSocketOptions 不需要任何安全许可。

自从：

9

supportedOptions

public Set <SocketOption <?>> supportedOptions()
            

返回此套接字支持的一组套接字选项。即使套接字已关闭，此方法仍将继续返回选项集。

返回：

此套接字支持的一组套接字选项。如果无法创建套接字的 DatagramSocketImpl，则该集合可能为空。

自从：

9

joinGroup

public void joinGroup(SocketAddress  mcastaddr, NetworkInterface  netIf) throws IOException 
            

加入多播组。

为了加入多播组，调用者应指定要加入的多播组的 IP 地址，以及要从中接收多播数据包的本地 网络接口。

• mcastaddr 参数表示要加入的多播组的 IP 地址。由于历史原因，这被指定为 SocketAddress 。默认实现仅支持 InetSocketAddress 而忽略 port 信息。
• netIf 参数指定用于接收多播数据报包的本地接口，或 null 指定用于传出多播数据报的接口集。如果 null 并且没有设置接口，则行为未指定：可以选择任何接口或者操作可能会失败并显示 SocketException 。

可以多次调用此方法以加入多个不同的多播组，或者加入多个不同网络中的同一个组。但是，如果套接字已经是该组的成员，则会抛出 IOException 。

如果有安全管理器，此方法首先调用其 checkMulticast 方法，并将 mcastaddr 参数作为其参数。

API 注意：

用于发送传出多播数据报的默认接口可以配置为 setOption(SocketOption, Object) 和 StandardSocketOptions.IP_MULTICAST_IF 。

参数：

mcastaddr - 表示要加入的多播地址。

netIf - 指定接收多播数据报包的本地接口，或 null 。

抛出：

IOException - 如果加入错误，或者地址不是多播地址，或者平台不支持多播

SecurityException - 如果安全管理器存在且其 checkMulticast 方法不允许加入。

IllegalArgumentException - 如果 mcastaddr 是 null 或者是此套接字不支持的 SocketAddress 子类

自从：

17

参见：

• SecurityManager.checkMulticast(InetAddress)
• MulticastChannel.join(InetAddress, NetworkInterface)
• StandardSocketOptions.IP_MULTICAST_IF

leaveGroup

public void leaveGroup(SocketAddress  mcastaddr, NetworkInterface  netIf) throws IOException 
            

在指定的本地接口上保留多播组。

如果有安全管理器，此方法首先调用其 checkMulticast 方法，并将 mcastaddr 参数作为其参数。

API 注意：

mcastaddr 和 netIf 参数应该标识一个多播组，该多播组之前是 加入 由这个 DatagramSocket 。

可以多次调用此方法以离开以前加入的多个不同的多播组，或者离开以前加入的同一个组在多个不同的网络中。但是，如果套接字不是指定网络中指定组的成员，则会抛出 IOException 。

参数：

mcastaddr - 是要离开的多播地址。这应该包含与用于 joining 组的 IP 地址相同的 IP 地址。

netIf - 指定本地接口或 null 以遵从为传出多播数据报设置的接口。如果 null 并且没有设置接口，则行为未指定：可以选择任何接口或者操作可能会失败并显示 SocketException 。

抛出：

IOException - 如果离开时出现错误或地址不是多播地址。

SecurityException - 如果安全管理器存在且其 checkMulticast 方法不允许该操作。

IllegalArgumentException - 如果 mcastaddr 是 null 或者是此套接字不支持的 SocketAddress 子类。

自从：

17

参见：

• SecurityManager.checkMulticast(InetAddress)
• joinGroup(SocketAddress, NetworkInterface)
• StandardSocketOptions.IP_MULTICAST_IF