NS3 Socket类API说明

源文件位置：

src/netwrok/model/socket.h
socket.cc

描述：

一个基于BSD Socket API的低级Socket API。
内省没有找到任何典型的配置路径。
有几件事要记住这种类型的套接字：

 它使用ns-3 API构造，如ns3 :: Address类，而不是C风格的结构
 与原始的BSD套接字API相反，这个API是异步的：它不包含阻塞调用。 发送和接收操作必须使用提供的回调。
 它还使用类ns3 :: Packet作为奇特字节缓冲区，允许使用ns-3数据包而不是原始数据指针通过API传递数据。
 不是所有的POSIX套接字API都支持

除此之外，它试图坚持BSD API，使那些知道BSD API的人更容易使用这个API。
更多详细信息，请参见ns-3教程。

公共方法：

Socket (void)

virtual     ~Socket (void)

virtual int     Bind (const Address &address)=0
    为此套接字分配本地端点。

virtual int     Bind ()=0
    为此套接字分配本地IPv4端点。

virtual int     Bind6 ()=0
    为此套接字分配本地IPv6端点。

virtual void    BindToNetDevice (Ptr< NetDevice > netdevice)
    将套接字绑定到特定设备。
    此方法对应于使用真实网络或BSD套接字的setsockopt（）SO_BINDTODEVICE。 
        如果在套接字上设置，此选项将强制数据包离开绑定设备，而不管IP路由自然选择的设备。 
        在接收方向，只有从绑定接口接收的数据包将被传递。

    此选项与通过Socket :: Bind（）将地址绑定到地址没有特殊的关系。 
        可以通过调用Socket :: Bind（address）和Socket :: BindToNetDevice（device）
        将套接字绑定到绑定接口上的特定IP地址，但是也可以绑定到不匹配的设备和地址，
        即使 套接字不能接收任何数据包结果。

virtual int     Close (void)=0
    关闭套接字。

virtual int     Connect (const Address &address)=0
    启动与远程主机的连接。

virtual bool    GetAllowBroadcast () const =0
    查询是否允许广播数据报传输。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）SO_BROADCAST。

Ptr< NetDevice >    GetBoundNetDevice ()
    返回套接字的绑定netdevice（如果有）。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）SO_BINDTODEVICE。

virtual enum Socket::SocketErrno    GetErrno (void) const =0
    获取上一个错误号。

uint8_t     GetIpTos (void) const
    查询此套接字的IP服务类型的值。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IP_TOS。

virtual uint8_t     GetIpTtl (void) const
    查询此套接字的IP生存时间字段的值。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IP_TTL。

virtual uint8_t     GetIpv6HopLimit (void) const
    查询此套接字的IP Hop Limit字段的值。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IPV6_HOPLIMIT。

uint8_t     GetIpv6Tclass (void) const
    查询此套接字的“IPv6流量类”字段的值。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IPV6_TCLASS。

virtual Ptr< Node >     GetNode (void) const =0
    返回此套接字与之关联的节点。

virtual int     GetPeerName (Address &address) const =0
    获取连接的套接字的对等体地址。

uint8_t     GetPriority (void) const
    查询此套接字的优先级值。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）SO_PRIORITY。

virtual uint32_t    GetRxAvailable (void) const =0
    返回可以从一个或多个调用返回到Recv的字节数。
    必须可以从Recv回调中调用此方法。

virtual enum Socket::SocketType     GetSocketType (void) const =0
    套接字类型，类似于getsockopt（SO_TYPE）

virtual int     GetSockName (Address &address) const =0
    获取套接字地址。

virtual uint32_t    GetTxAvailable (void) const =0
    返回在单个调用Send中可以发送的字节数。
    对于数据报套接字，这返回可以通过底层协议原子传递的字节数。
    对于流套接字，这返回发送缓冲区中剩余的字节的可用空间。

virtual void    Ipv6JoinGroup (Ipv6Address address, Ipv6MulticastFilterMode filterMode,
                                                 std::vector< Ipv6Address > sourceAddresses)
    加入IPv6组播组。
    基于过滤器模式和源地址，这可以被解释为对多播组上的源过滤的加入，
        离开或修改。
    注意套接字只能加入一个多播组。 任何加入其他群组的尝试都会移除旧群组。

virtual void    Ipv6JoinGroup (Ipv6Address address)
    加入没有过滤器的IPv6组播组。
    套接字只能加入一个组播组。 任何加入其他群组的尝试都会移除旧群组。

virtual void    Ipv6LeaveGroup (void)
    离开此套接字加入的IPv6组播组。

bool    IsIpRecvTos (void) const
    询问套接字当前是否在堆栈上传递关于IP类型的服务的信息。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IP_RECVTOS。

bool    IsIpRecvTtl (void) const
    询问套接字当前是否将关于IP_TTL的信息传递到堆栈。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IP_RECVTTL。

bool    IsIpv6RecvHopLimit (void) const
    询问套接字当前是否将关于IPv6 Hop Limit的信息传递到堆栈。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IPV6_RECVHOPLIMIT。

bool    IsIpv6RecvTclass (void) const
    询问套接字当前是否在栈上传递关于IPv6流量类的信息。
    此方法对应于使用真实网络或BSD套接字的getsockopt（）IPV6_RECVTCLASS。

bool    IsRecvPktInfo () const
    获取状态指示是否启用/禁用数据包信息到套接字。

virtual int     Listen (void)=0
    监听传入连接。

virtual Ptr< Packet >   Recv (uint32_t maxSize, uint32_t flags)=0
    从套接字读取数据。

Ptr< Packet >   Recv (void)
    从套接字读取单个数据包。
    Recv的重载版本（maxSize，flags），maxSize隐式设置为最大大小的整数，
        并且标志设置为零。

int     Recv (uint8_t *buf, uint32_t size, uint32_t flags)
    从远程主机回收数据（或虚拟数据）。
    提供该方法以便具有在外观上更接近真实网络或BSD套接字的API。
    如果底层数据包携带空（假）数据，则此缓冲区将被归零，直到由返回值指定的长度。

virtual Ptr< Packet >   RecvFrom (uint32_t maxSize, uint32_t flags, Address &fromAddress)=0
    从套接字读取单个数据包并检索发送方地址。
    调用Recv（maxSize，flags），maxSize隐式设置为最大大小整数，标志设置为零。
    此方法具有与Recv（）类似的语义，但子类可能希望提供对套接字状态的检查
        因此实现推送到子类。

Ptr< Packet >   RecvFrom (Address &fromAddress)
    从套接字读取单个数据包并检索发送方地址。
    调用RecvFrom（maxSize，flags，fromAddress），maxSize隐式设置为
        最大大小的整数，标志设置为零。

int     RecvFrom (uint8_t *buf, uint32_t size, uint32_t flags, Address &fromAddress)
    从套接字读取单个数据包并检索发送方地址。
    提供该方法以便具有在外观上更接近真实网络或BSD套接字的API。

virtual int     Send (Ptr< Packet > p, uint32_t flags)=0
    将数据（或虚拟数据）发送到远程主机。

int     Send (Ptr< Packet > p)
    将数据（或虚拟数据）发送到远程主机。
    具有设置为零的标志的Send（...，flags）的重载版本。

int     Send (const uint8_t *buf, uint32_t size, uint32_t flags)
    将数据（或虚拟数据）发送到远程主机。
    提供该方法以便具有在外观上更接近真实网络或BSD套接字的API。

virtual int     SendTo (Ptr< Packet > p, uint32_t flags, const Address &toAddress)=0
    发送数据到指定的对等体。
    此方法具有与Send（）类似的语义，但子类可能希望提供对套接字状态的检查
        因此实现被推送到子类。

int     SendTo (const uint8_t *buf, uint32_t size, uint32_t flags, const Address &address)
    发送数据到指定的对等体。
    提供该方法以便具有在外观上更接近真实网络或BSD套接字的API。

void    SetAcceptCallback (Callback< bool, Ptr< Socket >, const Address & > connectionRequest, 
                            Callback< void, Ptr< Socket >, const Address & > newConnectionCreated)
    接受来自远程主机的连接请求。

virtual bool    SetAllowBroadcast (bool allowBroadcast)=0
    配置是否允许广播数据报传输。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）SO_BROADCAST。 
        如果在套接字上设置，此选项将启用或禁用要传输到广播目标地址的数据包。

void    SetCloseCallbacks (Callback< void, Ptr< Socket > > normalClose, 
                            Callback< void, Ptr< Socket > > errorClose)
    检测套接字recv（）事件，如正常关闭或错误。
    对于面向连接的套接字，第一个回调用于表示远程端正常关闭连接，
        第二个回调表示与传统recv（）套接字调用可能返回-1（错误）的情况相对应的错误。 
        如连接复位。 对于数据报套接字，这些回调可能永远不会被调用。

void    SetConnectCallback (Callback< void, Ptr< Socket > > connectionSucceeded, 
                             Callback< void, Ptr< Socket > > connectionFailed)
    指定回调以允许调用者确定连接是否成功失败。

void    SetDataSentCallback (Callback< void, Ptr< Socket >, uint32_t > dataSent)
    当数据包已从传输协议（非标准套接字调用）发送时通知应用程序

void    SetIpRecvTos (bool ipv4RecvTos)
    告诉套接字传递关于IP类型的服务的信息在堆栈。
    此方法对应于使用真实网络或BSD套接字的setsockopt（）IP_RECVTOS。 
        在我们的实现中，套接字简单地在将包传递到栈之前向该包添加SocketIpTosTag标签。

void    SetIpRecvTtl (bool ipv4RecvTtl)
    告诉套接字向栈上传递关于IP_TTL的信息。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IP_RECVTTL。 
        在我们的实现中，套接字简单地在将包传递到栈之前向该包添加SocketIpTtlTag标签。

void    SetIpTos (uint8_t ipTos)
    手动设置IP服务类型字段。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IP_TOS。 
        此选项仅适用于IPv4。 设置IP TOS还会根据手册页中所述更改套接字优先级。

virtual void    SetIpTtl (uint8_t ipTtl)
    手动设置IP时间到实时字段。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IP_TTL。

virtual void    SetIpv6HopLimit (uint8_t ipHopLimit)
    手动设置IPv6跳数限制。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IPV6_HOPLIMIT。

void    SetIpv6RecvHopLimit (bool ipv6RecvHopLimit)
    告诉套接字传递关于IPv6 Hop Limit的信息。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IPV6_RECVHOPLIMIT。 
        在我们的实现中，套接字简单地在将包传递到栈之前向包添加SocketIpv6HopLimitTag标签。

void    SetIpv6RecvTclass (bool ipv6RecvTclass)
    告诉套接字传递有关IPv6流量类的信息。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IPV6_RECVTCLASS。 
        在我们的实现中，套接字简单地在将包传递到栈之前向该包添加SocketIpv6TclasssTag标签。

void    SetIpv6Tclass (int ipTclass)
    手动设置IPv6流量类字段。
    此方法对应于使用实际网络或BSD套接字的setsockopt（）IPV6_TCLASS。
        此选项仅适用于IPv6。 将IPV6_TCLASSS设置为-1会清除该选项，并让套接字使用默认值。

void    SetPriority (uint8_t priority)
    手动设置套接字优先级。
    此方法对应于使用真实网络或BSD套接字的setsockopt（）SO_PRIORITY。

void    SetRecvCallback (Callback< void, Ptr< Socket > >)
    在新数据可用时读取应用程序。
    此回调旨在通知在阻塞套接字模型中已阻止数据可用于读取的套接字。

void    SetRecvPktInfo (bool flag)
    启用/禁用接收数据包信息到套接字。
    对于IP_PKTINFO / IP6_PKTINFO。 此方法只能用于Raw套接字和Datagram套接字。 
        不支持Stream套接字。
    方法不区分IPv4和IPv6。 如果启用，则对支持包信息的所有类型的套接字启用

void    SetSendCallback (Callback< void, Ptr< Socket >, uint32_t > sendCb)
    当添加了发送缓冲区中的空间时通知应用程序。
    此回调旨在通知在阻塞套接字模型中已阻塞的套接字，
        该套接字在发送缓冲区中有可用空间，并且可以再次调用Send（）。

virtual int     ShutdownRecv (void)=0
    不允许任何进一步的Recv回调。 此方法通常实现为Tcp套接字半关闭。

virtual int     ShutdownSend (void)=0
    不允许任何进一步的发送回调。 此方法通常实现为Tcp套接字半关闭。

static Ptr< Socket >    CreateSocket (Ptr< Node > node, TypeId tid)
    此方法包装由TypeId指定的SocketFactory在给定节点上执行的套接字的创建。

static TypeId   GetTypeId (void)

static uint8_t  IpTos2Priority (uint8_t ipTos)
    返回对应于给定TOS值的优先级。
    此函数在Linux rt_tos2priority函数之后实现。 
        TOS字节的使用最初是由RFC 1349（http://www.ietf.org/rfc/rfc1349.txt）定义的

保护方法：

virtual void    DoDispose (void)

bool    IsManualIpTtl (void) const
    检查套接字是否具有特定的IPv4 TTL集。

bool    IsManualIpv6HopLimit (void) const
    检查套接字是否设置了特定的IPv6跳跃限制。

bool    IsManualIpv6Tclass (void) const
    检查套接字是否具有特定的IPv6 Tclass集。

void    NotifyConnectionFailed (void)
    通过回调（如果设置）通知由于错误连接尚未建立。

bool    NotifyConnectionRequest (const Address &from)
    通过回调（如果设置）通知远程主机正在请求传入连接。
    此函数默认返回true（即，接受所有传入连接）。
         回调（如果设置）可能通过为应拒绝的连接返回零来限制此行为。

void    NotifyConnectionSucceeded (void)
    通过回调（如果设置）通知连接已建立。

void    NotifyDataRecv (void)
    通过回调（如果设置）通知已接收到一些数据。

void    NotifyDataSent (uint32_t size)
    通过回调（如果设置）通知某些数据已发送。

void    NotifyErrorClose (void)
    通过回调（如果设置）通知由于错误连接已关闭。

void    NotifyNewConnectionCreated (Ptr< Socket > socket, const Address &from)
    通过回调（如果设置）通知已创建新连接。

void    NotifyNormalClose (void)
    通过回调（如果设置）通知连接已关闭。

void    NotifySend (uint32_t spaceAvailable)
    通过回调（如果设置）通知某些数据已发送。