PJNATH1.12文档翻译：STUN会话
[ STUN: 为 NAT 做的会话穿越工具 ]

STUN session
[ STUN: Session Traversal Utilities for NAT ]

详细描述

这是一個用来管理一個客户端或服务器端STUN 会话的与传输层无关（transport-independent）的对象。它拥有以下特性：

• •. 与传输层无关 （transport independent）:
  这個对象没有自己的套接字，只是提供一些函数和回调函数来发送和接收数据包。这样的话，这個对象可被不同的传输层协议（transport types）（例如UDP、TCP、TLS等等）使用，另外也能更好地与那些已经采用自己的手段来发送及接收数据包的程序整合起来。

• •. 认证管理：
  这個对象在会话的整个生命期中都管理着STUN 认证。对于客户端会话，一旦它被赋予某個用来向服务器认证自身的凭证，它就會自动将认证信息（MESSAGE-INTEGRITY）添加到请求中，并且对回复进行认证。它还會处理长期的（long-term）认证挑战（authentication challenges），包括处理一次性密钥（nonce）的过期、自动重试请求。对于服务器會话，它可被配置为自动对新来的请求进行认证。

• •. 静态或动态凭证：
  程序可指定静态或者动态的凭证来给STUN 會话使用。静态凭证指的就是用户名和密码的固定组合（并且在这個會话期间不能改变）；而动态凭证指的是，會提供回调函数，它们會在每次需要认证的时候询问程序要使用哪個用户名/密码。

• •. 客户端事务管理：
  外发的（outgoing）请求可能为咯可靠性而使用一個STUN 事务（transaction）来发送，而这個对象會在内部（包括重传）管理这個事务。当回复到达（或事务超时）时，程序會被告知此次请求的结果。当这個请求过程被认证要求挑战时，此对象會使用新的认证信息来重试，并且程序會被告知此次请求的最终结果。

• •. 服务器端事务管理：
  程序可以要求这個对象将针对外来的请求的回复进行缓存，在这种情况下，这個对象會在每次收到请求时检查缓存的回复。一旦某個定时器超时，这個缓存的回复就會被删除。

使用STUN 會话

按照以下步骤来使用STUN 會话：

• •. 创建对象配置信息：
  pj_stun_config 包含着用来创建STUN 會话的配置信息，例如用来注册内部定时器的定时器堆以及各种各样的STUN 超时值。妳可以通过调用 pj_stun_config_init() 来对这個数据结构进行初始化。

• •. 创建STUN 會话：
  调用 pj_stun_session_create() 。除咯其它东西以外，这個函数需要 pj_stun_config 和 pj_stun_session_cb 结构的实例，后者储存的是一些回调函数，它们被用来发送数据包以及向程序通知外来的STUN 请求、回复、通知信息、其它事件。

• •. 配置凭证：
  如果會话需要认证，则使用 pj_stun_session_set_credential() 来配置凭证。

• •. 配置其它设置信息：
  提供咯多個API 来配置STUN 會话的行为（例如：设置SOFTWARE 属性值、控制日志行为、微调加锁行为……）。请参考API 手册以了解更多信息。

• •. 创建外发的STUN 请求或提示（indications）：
  使用 pj_stun_session_create_req() 或 pj_stun_session_create_ind() 来创建STUN 消息。这将會创建一個包含一個空的STUN 请求或提示的传输数据缓存。然后，妳一般會将一些与这個请求或提示相关的STUN 属性添加进去，但是需要注意，某些默认的属性（比如说 SOFTWARE属性和与认证相关的属性）會在稍后发送消息的时候由會话来添加。现在可以发送这個消息咯。

• •. 向外发送消息：
  使用 pj_stun_session_send_msg() 来向外发送STUN 消息（包括STUN 请求、提示和回复）。这個函数包含一些选项：是否要重传请求（针对不可靠的传输方式），或者当我们是在发送回复的时候是否要将回复缓存起来。这個函数反过来會调用 pj_stun_session_cb 中的 on_send_msg() 回调函数来要求程序发送这個数据包。

• •. 处理外来数据包：
  每当程序接收到 STUN 数据包时，调用 pj_stun_session_on_rx_pkt() 。这個函数會将数据包解码，并且根据消息的内容来处理数据包，一般情况下會导致 pj_stun_session_cb 中的某個回调函数被调用，以向程序通知这個事件。

• •. 处理外来请求：
  外来请求是通过中 pj_stun_session_cb 的 on_rx_request 回调函数来通知程序的。如果对这個會话启用咯认证的话，则程序只會在这個外来请求被成功认证的情况下才收到回调函数通知（如果认证失败，则會話會自动以401 错误进行回复，而回调函数不會被调用）。这個时候，程序必须为这個请求创建一個回复，并且发送出去。

• •. 创建和发送回复：
  使用 pj_stun_session_create_res() 来创建STUN 回复。这将會创建一個传输数据缓存，其中包含一個空的STUN 回复。然后，妳一般會将一些与这個回复相关的STUN 属性添加进去，但是需要注意，某些默认的属性（比如说 SOFTWARE属性和与认证相关的属性）會在稍后发送消息的时候由會话来添加。现在，这個消息可以发送咯。使用 pj_stun_session_send_msg() （前面已经说过）来发送这個回复。

• •. 发送回复的快捷方法：
  提供咯 pj_stun_session_respond() 函数，它是一种快捷地创建及发送简单的STUN 回复的方式，例如发送错误信息回复。

• •. 销毁會話：
  一旦會话使用完毕，就可以使用 pj_stun_session_destroy() 来销毁會话。