Skip to content

GitLab

Commit 570b1289 authored by Pekka Pessi's avatar Pekka Pessi
Browse files
Options

tport: updated tag documentation. 

darcs-hash:20061222155536-65a35-d893ed157f4a9de93d5db8d7175de4bb3afbfa32.gz
parent 94b16100
Hide whitespace changes
Inline Side-by-side
Showing with 176 additions and 31 deletions
libsofia-sip-ua/tport/Doxyfile
View file @ 570b1289
......@@ -7,7 +7,10 @@ INPUT = tport.docs sofia-sip .
TAGFILES += \
../docs/su.doxytags=../su \
../docs/msg.doxytags=../msg
../docs/msg.doxytags=../msg \
../docs/nth.doxytags=../nth \
../docs/nta.doxytags=../nta \
../docs/nua.doxytags=../nua \
GENERATE_TAGFILE = ../docs/tport.doxytags
......
libsofia-sip-ua/tport/sofia-sip/tport_tag.h
View file @ 570b1289
......@@ -51,28 +51,46 @@ TPORT_DLL extern tagi_t tport_tags[];
TPORT_DLL extern tag_typedef_t tptag_any;
TPORT_DLL extern tag_typedef_t tptag_ident;
/** Ident transport connection (true by default). */
/**Identify a transport interface.
*
* Use with tport_tbind(), tport_tsend(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nta_outgoing_tcreate(), nta_outgoing_mcreate(),
* nth_engine_create(), nth_client_tcreate(), or initial nth_site_create().
*/
#define TPTAG_IDENT(x) tptag_ident, tag_str_v((x))
TPORT_DLL extern tag_typedef_t tptag_ident_ref;
#define TPTAG_IDENT_REF(x) tptag_ident_ref, tag_str_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_reuse;
/** Allow reusing transport connection (true by default). */
/** Allow reusing transport connection (true by default).
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(),
* tport_tsend(), nua_create(), nta_agent_create(), nta_agent_add_tport(),
* nta_outgoing_tcreate(), nta_outgoing_mcreate(), nth_engine_create(),
* nth_client_tcreate(), or initial nth_site_create().
*/
#define TPTAG_REUSE(x) tptag_reuse, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_reuse_ref;
#define TPTAG_REUSE_REF(x) tptag_reuse_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_fresh;
/** Create new connection (but allow reusing new one). */
/** Create new connection (but allow other messages to reuse the new one).
*
* Use with tport_tsend(), nta_outgoing_tcreate(), nta_outgoing_mcreate(),
* or nth_client_tcreate().
*/
#define TPTAG_FRESH(x) tptag_fresh, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_fresh_ref;
#define TPTAG_FRESH_REF(x) tptag_fresh_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_server;
/** Bind server sockets (true by default, disable with TPTAG_SERVER(0)). */
/** Bind server sockets (true by default, disable with TPTAG_SERVER(0)).
*
* Use with tport_tbind().
*/
#define TPTAG_SERVER(x) tptag_server, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_server_ref;
......@@ -93,58 +111,99 @@ typedef enum tport_via {
} tport_pri_type_t;
TPORT_DLL extern tag_typedef_t tptag_public;
/** Use a transport reaching to public Internet. */
/** Use a transport reaching to public Internet.
*
* Use with tport_tbind(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nth_engine_create(), or initial nth_site_create().
*/
#define TPTAG_PUBLIC(x) tptag_public, tag_int_v((x))
TPORT_DLL extern tag_typedef_t tptag_public_ref;
#define TPTAG_PUBLIC_REF(x) tptag_public_ref, tag_int_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_mtu;
/** Specify MTU. */
/** Specify MTU.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(),
* tport_tsend(), nua_create(), nta_agent_create(), nta_agent_add_tport(),
* nta_outgoing_tcreate(), nta_outgoing_mcreate(), nth_engine_create(),
* nth_client_tcreate(), or initial nth_site_create().
*/
#define TPTAG_MTU(x) tptag_mtu, tag_usize_v((x))
TPORT_DLL extern tag_typedef_t tptag_mtu_ref;
#define TPTAG_MTU_REF(x) tptag_mtu_ref, tag_usize_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_connect;
/** Specify that tport must always use connections. */
/** Specify that tport must always use connections (even with UDP).
*
* @note Unimplemented (?).
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_CONNECT(x) tptag_connect, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_connect_ref;
#define TPTAG_CONNECT_REF(x) tptag_connect_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_queuesize;
/** Specify the number of messages that can be queued per connection. */
/** Specify the number of messages that can be queued per connection.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_QUEUESIZE(x) tptag_queuesize, tag_uint_v((x))
TPORT_DLL extern tag_typedef_t tptag_queuesize_ref;
#define TPTAG_QUEUESIZE_REF(x) tptag_queuesize_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_sdwn_error;
/** If true, half close of a connection by remote is considered as an error. */
/** If true, half close of a connection by remote is considered as an error.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_SDWN_ERROR(x) tptag_sdwn_error, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_sdwn_error_ref;
#define TPTAG_SDWN_ERROR_REF(x) tptag_sdwn_error_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_sdwn_after;
/** Half-close (shutdown(c, 1) after sending the message. */
/** Half-close (shutdown(c, 1)) after sending the message.
*
* Use with tport_tsend(), nta_outgoing_tcreate(), nta_outgoing_mcreate(),
* or nth_client_tcreate().
*/
#define TPTAG_SDWN_AFTER(x) tptag_sdwn_after, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_sdwn_after_ref;
#define TPTAG_SDWN_AFTER_REF(x) tptag_sdwn_after_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_close_after;
/** Close of a connection after sending the message. */
/** Close of a connection after sending the message.
*
* Use with tport_tsend(), nta_outgoing_tcreate(), nta_outgoing_mcreate(),
* or nth_client_tcreate().
*/
#define TPTAG_CLOSE_AFTER(x) tptag_close_after, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_close_after_ref;
#define TPTAG_CLOSE_AFTER_REF(x) tptag_close_after_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_idle;
/** How long transports may be idle (value in milliseconds).
/** How long transports may be idle (value in milliseconds).
*
* If 0, zap immediately,
* if UINT_MAX, leave them there (default value for now).
*
* @par Use With
* tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_IDLE(x) tptag_idle, tag_uint_v((x))
......@@ -156,6 +215,10 @@ TPORT_DLL extern tag_typedef_t tptag_timeout;
*
* If UINT_MAX, leave the incomplete messages there for ever.
* Default value for now is UINT_MAX.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_TIMEOUT(x) tptag_timeout, tag_uint_v((x))
......@@ -163,11 +226,15 @@ TPORT_DLL extern tag_typedef_t tptag_timeout_ref;
#define TPTAG_TIMEOUT_REF(x) tptag_timeout_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_sigcomp_lifetime;
/**Default SigComp lifetime.
/**Default SigComp lifetime in seconds.
*
* If UINT_MAX, keep SigComp compartments around for ever.
* If value is UINT_MAX, keep SigComp compartments around for ever.
*
* @note Experimental.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_SIGCOMP_LIFETIME(x) tptag_sigcomp_lifetime, tag_uint_v((x))
......@@ -176,7 +243,10 @@ TPORT_DLL extern tag_typedef_t tptag_sigcomp_lifetime_ref;
tptag_sigcomp_lifetime_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_compartment;
/** Pointer to SigComp compartment. */
/** Pointer to SigComp compartment.
*
* @note Not used.
*/
#define TPTAG_COMPARTMENT(x) tptag_compartment, tag_ptr_v((x))
TPORT_DLL extern tag_typedef_t tptag_compartment_ref;
......@@ -185,6 +255,9 @@ TPORT_DLL extern tag_typedef_t tptag_compartment_ref;
TPORT_DLL extern tag_typedef_t tptag_certificate;
/** Path to the public key certificate directory.
*
* Use with tport_tbind(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nth_engine_create(), or initial nth_site_create().
*/
#define TPTAG_CERTIFICATE(x) tptag_certificate, tag_str_v((x))
......@@ -193,43 +266,80 @@ TPORT_DLL extern tag_typedef_t tptag_certificate_ref;
TPORT_DLL extern tag_typedef_t tptag_tls_version;
/** Sets the TLS version (version 0 implies SSL2/SSL3).
*
* Use with tport_tbind(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nth_engine_create(), or initial nth_site_create().
*/
#define TPTAG_TLS_VERSION(x) tptag_tls_version, tag_uint_v((x))
TPORT_DLL extern tag_typedef_t tptag_tls_version_ref;
#define TPTAG_TLS_VERSION_REF(x) tptag_tls_version_ref, tag_uint_vr(&(x))
#if 0
TPORT_DLL extern tag_typedef_t tptag_trusted;
/** Mark transport as trusted. */
/** Mark transport as trusted.
*
* @note Not implemented.
*/
#define TPTAG_TRUSTED(x) tptag_trusted, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_trusted_ref;
#define TPTAG_TRUSTED_REF(x) tptag_trusted_ref, tag_bool_vr(&(x))
#endif
TPORT_DLL extern tag_typedef_t tptag_debug_drop;
/** Sets the drop propability for (0..1000) incoming/outgoing packets. */
/** Sets the drop propability for (0..1000) incoming/outgoing packets.
*
* This is a parameter suitable for debugging only.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_DEBUG_DROP(x) tptag_debug_drop, tag_uint_v((x))
TPORT_DLL extern tag_typedef_t tptag_debug_drop_ref;
#define TPTAG_DEBUG_DROP_REF(x) tptag_debug_drop_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_udp_rmem;
/** Sets the maximum receive buffer in bytes for primary UDP socket. */
/** Sets the maximum receive buffer in bytes for primary UDP socket.
*
* This is a parameter suitable for tuning.
*
* Use with tport_tbind(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nth_engine_create(), or initial nth_site_create().
*/
#define TPTAG_UDP_RMEM(x) tptag_udp_rmem, tag_uint_v((x))
TPORT_DLL extern tag_typedef_t tptag_udp_rmem_ref;
#define TPTAG_UDP_RMEM_REF(x) tptag_udp_rmem_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_udp_wmem;
/** Sets the maximum send buffer in bytes for primary UDP socket. */
/** Sets the maximum send buffer in bytes for primary UDP socket.
*
* This is a parameter suitable for tuning.
*
* Use with tport_tbind(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nth_engine_create(), or initial nth_site_create().
*/
#define TPTAG_UDP_WMEM(x) tptag_udp_wmem, tag_uint_v((x))
TPORT_DLL extern tag_typedef_t tptag_udp_wmem_ref;
#define TPTAG_UDP_WMEM_REF(x) tptag_udp_wmem_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_thrpsize;
/** Determines the number of threads in the pool receiving, uncompressing,
/**Determines the number of threads in the pool.
*
* The thread pools can have multiple threads receiving, uncompressing,
* parsing, compressing, and sending messages.
*
* This is a parameter suitable for tuning.
*
* @note Thread pools are currently broken.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_THRPSIZE(x) tptag_thrpsize, tag_uint_v((x))
......@@ -237,7 +347,13 @@ TPORT_DLL extern tag_typedef_t tptag_thrpsize_ref;
#define TPTAG_THRPSIZE_REF(x) tptag_thrpsize_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_thrprqsize;
/** Length of per-thread receive queue (as messages)
/** Length of per-thread receive queue (as messages).
*
* This is a parameter suitable for tuning.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_THRPRQSIZE(x) tptag_thrprqsize, tag_uint_v((x))
......@@ -245,21 +361,35 @@ TPORT_DLL extern tag_typedef_t tptag_thrprqsize_ref;
#define TPTAG_THRPRQSIZE_REF(x) tptag_thrprqsize_ref, tag_uint_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_http_connect;
/** Specify that tport can use HTTP connect method. */
/** Specify that tport can use HTTP connect method.
*
* Use with tport_tbind(), nua_create(), nta_agent_create(),
* nta_agent_add_tport(), nth_engine_create(), or initial nth_site_create().
*/
#define TPTAG_HTTP_CONNECT(x) tptag_http_connect, tag_str_v((x))
TPORT_DLL extern tag_typedef_t tptag_http_connect_ref;
#define TPTAG_HTTP_CONNECT_REF(x) tptag_http_connect_ref, tag_str_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_stun_server;
/** Enable STUN server. */
/** Enable STUN server.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_STUN_SERVER(x) tptag_stun_server, tag_bool_v((x))
TPORT_DLL extern tag_typedef_t tptag_stun_server_ref;
#define TPTAG_STUN_SERVER_REF(x) tptag_stun_server_ref, tag_bool_vr(&(x))
TPORT_DLL extern tag_typedef_t tptag_tos;
/** Sets the IP TOS for the socket. */
/** Sets the IP TOS for the socket.
*
* Use with tport_tcreate(), tport_tbind(), tport_set_params(), nua_create(),
* nta_agent_create(), nta_agent_add_tport(), nth_engine_create(), or
* initial nth_site_create().
*/
#define TPTAG_TOS(x) tptag_tos, tag_int_v((x))
TPORT_DLL extern tag_typedef_t tptag_tos_ref;
......
libsofia-sip-ua/tport/tport.c
View file @ 570b1289
......@@ -427,7 +427,12 @@ msg_t *tport_destroy_alloc(tp_stack_t *stack, int flags,
/** Name for "any" transport. @internal */
static char const tpn_any[] = "*";
/** Create the master transport. */
/** Create the master transport.
*
* @TAGS
* TPTAG_LOG(), TPTAG_DUMP(), tags used with tport_set_params(), especially
* TPTAG_QUEUESIZE().
*/
tport_t *tport_tcreate(tp_stack_t *stack,
tp_stack_class_t const *tpac,
su_root_t *root,
......@@ -1128,6 +1133,12 @@ int tport_get_params(tport_t const *self,
*
* @param self pointer to a transport object
* @param tag,value,... list of tags
*
* @TAGS
* TPTAG_MTU(), TPTAG_QUEUESIZE(), TPTAG_IDLE(), TPTAG_TIMEOUT(),
* TPTAG_DEBUG_DROP(), TPTAG_THRPSIZE(), TPTAG_THRPRQSIZE(),
* TPTAG_SIGCOMP_LIFETIME(), TPTAG_CONNECT(), TPTAG_SDWN_ERROR(),
* TPTAG_REUSE(), TPTAG_STUN_SERVER(), and TPTAG_TOS().
*/
int tport_set_params(tport_t *self,
tag_type_t tag, tag_value_t value, ...)
......@@ -1138,8 +1149,6 @@ int tport_set_params(tport_t *self,
int connect, sdwn_error, reusable, stun_server;
struct sigcomp_compartment *cc = NONE;
if (self == NULL)
return su_seterrno(EINVAL);
......@@ -1164,7 +1173,6 @@ int tport_set_params(tport_t *self,
TPTAG_CONNECT_REF(connect),
TPTAG_SDWN_ERROR_REF(sdwn_error),
TPTAG_REUSE_REF(reusable),
TPTAG_COMPARTMENT_REF(cc),
TPTAG_STUN_SERVER_REF(stun_server),
TPTAG_TOS_REF(tpp->tpp_tos),
TAG_END());
......@@ -1324,6 +1332,11 @@ int tport_bind_set(tport_master_t *mr,
* @param tpn desired transport address
* @param transports list of protocol names supported by stack
* @param tag,value,... tagged argument list
*
* @TAGS
* TPTAG_SERVER(), TPTAG_PUBLIC(), TPTAG_IDENT(), TPTAG_HTTP_CONNECT(),
* TPTAG_CERTIFICATE(), TPTAG_TLS_VERSION(), and tags used with
* tport_set_params(), especially TPTAG_QUEUESIZE().
*/
int tport_tbind(tport_t *self,
tp_name_t const *tpn,
......@@ -2940,6 +2953,7 @@ int tport_recv_error_report(tport_t *self)
*
* @TAGS
* TPTAG_MTU(), TPTAG_REUSE(), TPTAG_CLOSE_AFTER(), TPTAG_SDWN_AFTER(),
* TPTAG_FRESH(), TPTAG_COMPARTMENT().
*/
tport_t *tport_tsend(tport_t *self,
msg_t *msg,
......@@ -4526,5 +4540,3 @@ char *tport_hostport(char buf[], isize_t bufsize,
return buf;
}
/* ---------------------------------------------------------------------- */
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment