Node.js v14.21.1 文档


目录

dgram 数据报#

中英对照

dgram 模块提供了 UDP 数据报套接字的实现。


dgram.Socket#

中英对照

    封装数据报功能。

    'close' 事件#

    中英对照

    在使用 close() 关闭套接字后会触发 'close' 事件。 一旦触发,则此套接字上将不会触发新的 'message' 事件。

    'connect' 事件#

    中英对照

    'connect' 事件在套接字关联到远程地址作为成功的 connect() 调用的结果之后触发。

    'error' 事件#

    中英对照

      每当发生任何错误时都会触发 'error' 事件。 事件句柄被传入单一的 Error 对象。

      'listening' 事件#

      中英对照

      一旦 dgram.Socket 可寻址并且可以接收数据,则会触发 'listening' 事件。 这会在 socket.bind() 中显式地发生,或者在第一次使用 socket.send() 发送数据时隐式地发生。 直到 dgram.Socket 正在监听,底层系统资源不存在,则调用 socket.address()socket.setTTL() 等将失败。

      'message' 事件#

      中英对照

      当套接字上有新的数据报可用时,则会触发 'message' 事件。 事件句柄传入了两个参数:msgrinfo

        socket.addMembership(multicastAddress[, multicastInterface])#

        中英对照

          使用 IP_ADD_MEMBERSHIP 套接字选项告诉内核在给定的 multicastAddressmulticastInterface 上加入多播组。 如果未指定 multicastInterface 参数,则操作系统将选择一个接口并为其添加成员资格。 要为每个可用接口添加成员资格,则多次调用 addMembership,每个接口一次。

          
          

          socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])#

          中英对照

            告诉内核在给定的 sourceAddressgroupAddress 上加入特定于源的多播频道,使用 multicastInterfaceIP_ADD_SOURCE_MEMBERSHIP 套接字选项。 如果未指定 multicastInterface 参数,则操作系统将选择一个接口并为其添加成员资格。 要为每个可用接口添加成员资格,则多次调用 socket.addSourceSpecificMembership(),每个接口一次。

            socket.address()#

            中英对照

              返回包含套接字地址信息的对象。 对于 UDP 套接字,此对象将包含 addressfamilyport 属性。

              socket.bind([port][, address][, callback])#

              中英对照

                对于 UDP 套接字,使 dgram.Socket 在命名的 port 和可选的 address 上监听数据报消息。 如果未指定 port0,则操作系统将尝试绑定到随机端口。 如果未指定 address,则操作系统将尝试监听所有地址。 一旦绑定完成,则会触发 'listening' 事件并调用可选的 callback 函数。

                
                

                socket.bind(options[, callback])#

                中英对照

                  对于 UDP 套接字,使 dgram.Socket 监听命名 port 和可选 address 上的数据报消息,这些消息作为作为第一个参数传入的 options 对象的属性传入。 如果未指定 port0,则操作系统将尝试绑定到随机端口。 如果未指定 address,则操作系统将尝试监听所有地址。 一旦绑定完成,则会触发 'listening' 事件并调用可选的 callback 函数。

                  
                  

                  socket.close([callback])#

                  中英对照

                    关闭底层套接字并停止监听其上的数据。 如果提供回调,则将其添加为 'close' 事件的监听器。

                    socket.connect(port[, address][, callback])#

                    中英对照

                      dgram.Socket 关联到远程地址和端口。 此句柄发送的每条消息都会自动发送到该目标。 此外,套接字将只接收来自该远程对等方的消息。 尝试在已连接的套接字上调用 connect() 将导致 ERR_SOCKET_DGRAM_IS_CONNECTED 异常。 如果未提供 address,则默认使用 '127.0.0.1'(适用于 udp4 套接字)或 '::1'(适用于 udp6 套接字)。 一旦连接完成,就会触发 'connect' 事件并调用可选的 callback 函数。 如果失败,则调用 callback,或者触发 'error' 事件。

                      socket.disconnect()#

                      中英对照

                      将连接的 dgram.Socket 与其远程地址分离的同步函数。 尝试在未绑定或已断开连接的套接字上调用 disconnect() 将导致 ERR_SOCKET_DGRAM_NOT_CONNECTED 异常。

                      socket.dropMembership(multicastAddress[, multicastInterface])#

                      中英对照

                        指示内核使用 IP_DROP_MEMBERSHIP 套接字选项离开 multicastAddress 处的多播组。 当套接字关闭或进程终止时,内核会自动调用此方法,因此大多数应用程序永远没有理由调用此方法。

                        socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])#

                        中英对照

                          指示内核使用 IP_DROP_SOURCE_MEMBERSHIP 套接字选项在给定的 sourceAddressgroupAddress 处保留特定于源的多播通道。 当套接字关闭或进程终止时,内核会自动调用此方法,因此大多数应用程序永远没有理由调用此方法。

                          socket.getRecvBufferSize()#

                          中英对照

                            如果在未绑定的套接字上调用此方法将抛出 ERR_SOCKET_BUFFER_SIZE

                            socket.getSendBufferSize()#

                            中英对照

                              如果在未绑定的套接字上调用此方法将抛出 ERR_SOCKET_BUFFER_SIZE

                              socket.ref()#

                              中英对照

                                默认情况下,只要套接字处于打开状态,则绑定套接字将导致它阻止 Node.js 进程退出。 socket.unref() 方法可用于从保持 Node.js 进程处于活动状态的引用计数中排除套接字。 socket.ref() 方法将套接字添加回引用计数并恢复默认行为。

                                socket.remoteAddress()#

                                中英对照

                                  返回包含远程端点的 addressfamilyport 的对象。 如果套接字未连接,则此方法将抛出 ERR_SOCKET_DGRAM_NOT_CONNECTED 异常。

                                  socket.send(msg[, offset, length][, port][, address][, callback])#

                                  中英对照

                                    在套接字上广播数据报。 对于无连接套接字,则必须指定目标 portaddress。 另一方面,已连接的套接字将使用其关联的远程端点,因此不得设置 portaddress 参数。

                                    
                                    

                                    
                                    

                                    
                                    
                                    关于 UDP 数据报大小的说明#

                                    中英对照

                                    IPv4/v6 数据报的最大大小取决于 MTU(最大传输单元)和 Payload Length 字段大小。

                                      socket.setBroadcast(flag)#

                                      中英对照

                                        设置或清除 SO_BROADCAST 套接字选项。 当设置为 true 时,UDP 数据包可能会被发送到本地接口的广播地址。

                                        socket.setMulticastInterface(multicastInterface)#

                                        中英对照

                                          本节中对范围的所有引用均指 IPv6 区域索引,由 RFC 4007 定义。 以字符串形式,具有作用域索引的 IP 写成 'IP%scope',其中作用域是接口名称或接口编号。

                                          IPv6 发送多播数据包#

                                          中英对照

                                          在大多数系统上,范围格式使用接口名称:

                                          
                                          

                                          
                                          
                                          IPv4 发送多播数据包#

                                          中英对照

                                          所有系统都在所需的物理接口上使用主机的 IP:

                                          
                                          
                                          调用的结果#

                                          中英对照

                                          对未准备好发送或不再打开的套接字的调用可能会抛出 Not running Error

                                          socket.setMulticastLoopback(flag)#

                                          中英对照

                                            设置或清除 IP_MULTICAST_LOOP 套接字选项。 当设置为 true 时,本地接口也会收到多播数据包。

                                            socket.setMulticastTTL(ttl)#

                                            中英对照

                                              设置 IP_MULTICAST_TTL 套接字选项。 虽然 TTL 通常代表 "生存时间",但在此上下文中,它指定了允许数据包通过的 IP 跃点数,特别是对于多播流量。 转发数据包的每个路由器或网关都会递减 TTL。 如果 TTL 被路由器递减为 0,则不会转发。

                                              socket.setRecvBufferSize(size)#

                                              中英对照

                                                设置 SO_RCVBUF 套接字选项。 设置最大套接字接收缓冲区(以字节为单位)。

                                                socket.setSendBufferSize(size)#

                                                中英对照

                                                  设置 SO_SNDBUF 套接字选项。 设置最大套接字发送缓冲区(以字节为单位)。

                                                  socket.setTTL(ttl)#

                                                  中英对照

                                                    设置 IP_TTL 套接字选项。 虽然 TTL 通常代表"生存时间",但在此上下文中,它指定了允许数据包通过的 IP 跃点数。 转发数据包的每个路由器或网关都会递减 TTL。 如果 TTL 被路由器递减为 0,则不会转发。 更改 TTL 值通常用于网络探测或多播。

                                                    socket.unref()#

                                                    中英对照

                                                      默认情况下,只要套接字处于打开状态,则绑定套接字将导致它阻止 Node.js 进程退出。 socket.unref() 方法可用于将套接字从保持 Node.js 进程处于活动状态的引用计数中排除,即使套接字仍在监听,也允许进程退出。

                                                      dgram 模块的函数#

                                                      dgram.createSocket(options[, callback])#

                                                      中英对照

                                                        创建 dgram.Socket 对象。 一旦创建了套接字,则调用 socket.bind() 将指示套接字开始监听数据报消息。 当 addressport 没有传给 socket.bind() 时,则该方法会将套接字绑定到随机端口上的“所有接口”地址(它对 udp4udp6 套接字都做正确的事情)。 可以使用 socket.address().addresssocket.address().port 检索绑定的地址和端口。

                                                        
                                                        

                                                        dgram.createSocket(type[, callback])#

                                                        中英对照

                                                          创建指定 typedgram.Socket 对象。

                                                          返回顶部