nua: Updated documentation for registration keepalives, and setting the various outbound options.

darcs-hash:20070209124446-7659e-702b97bbe97abb1e089c1e7675bd60b0b5d66bba.gz

libsofia-sip-ua/nua/nua_register.c

@@ -433,6 +433,11 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
  * the desired transport-layer keepalive interval for stream-based
  * transports like TLS and TCP.
  *
+ * As alternative to OPTIONS/STUN keepalives, the client can propose
+ * a more frequent registration refresh interval with
+ * NUTAG_M_FEATURES() (e.g. NUTAG_M_FEATURES("expires=120") given as 
+ * parameter to nua_register()).
+ * 
  * @sa #nua_r_register, nua_unregister(), #nua_r_unregister, 
  * #nua_i_register,
  * @RFC3261 section 10,

libsofia-sip-ua/nua/sofia-sip/nua_tag.h

@@ -1074,7 +1074,7 @@ SOFIAPUBVAR tag_typedef_t nutag_registrar_ref;
  *
  * The outbound option string can specify how the NAT traversal is handled.
  * The option tokens are as follows:
- * - "gruuize": try to generate a GRUU
+ * - "gruuize": try to generate a GRUU contact from REGISTER response
  * - "outbound": use SIP outbound extension (off by default)
  * - "validate": validate registration behind a NAT by sending OPTIONS to self
  * - "natify": try to traverse NAT
@@ -1084,6 +1084,10 @@ SOFIAPUBVAR tag_typedef_t nutag_registrar_ref;
  * An option token with "no-" or "not-" prefix turns the option off. For
  * example, if you want to try to traverse NATs but not to use OPTIONS
  * keepalive, use NUTAG_OUTBOUND("natify no-options-keepalive").
+ * 
+ * An empty string can be passed to let the stack choose the
+ * default values for outbound usage (in the 1.12.5 release, the
+ * defaults are: "gruuize no-outbound validate use-port options-keepalive").
  *
  * @note
  * Options string is used so that no new tags need to be added when the
@@ -1243,6 +1247,9 @@ SOFIAPUBVAR tag_typedef_t nutag_auth;
 SOFIAPUBVAR tag_typedef_t nutag_auth_ref;
 
 /** Keepalive interval in milliseconds.
+ *
+ * This setting applies to OPTIONS/STUN keepalives. See documentation 
+ * for nua_register() for more detailed information.
  *
  * @par Used with
  *    nua_register()   \n
@@ -1268,6 +1275,8 @@ SOFIAPUBVAR tag_typedef_t nutag_keepalive;
 SOFIAPUBVAR tag_typedef_t nutag_keepalive_ref;
 
 /** Transport-level keepalive interval for streams.
+ *
+ * See documentation for nua_register() for more detailed information.
  *
  * @par Used with
  *    nua_register()   \n