diff options
author | Benny Prijono <bennylp@teluu.com> | 2006-06-23 15:04:54 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2006-06-23 15:04:54 +0000 |
commit | e90d549a310e36299d349eef746e966f9172273f (patch) | |
tree | 9b2af4dc963aa5dba236417f7253c47a8f1e001f /pjsip/include | |
parent | daf2b65313488296bb1a563d6189a0e6774304af (diff) |
Renamed pjsip_transport_unregister() to pjsip_transport_destroy(), also initial implementation of TCP transport
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@550 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include')
-rw-r--r-- | pjsip/include/pjsip/sip_transport.h | 117 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_transport_tcp.h | 62 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_transport_udp.h | 2 |
3 files changed, 166 insertions, 15 deletions
diff --git a/pjsip/include/pjsip/sip_transport.h b/pjsip/include/pjsip/sip_transport.h index 2adcea01..e09583db 100644 --- a/pjsip/include/pjsip/sip_transport.h +++ b/pjsip/include/pjsip/sip_transport.h @@ -492,7 +492,8 @@ struct pjsip_transport pj_pool_t *pool; /**< Pool used by transport. */ pj_atomic_t *ref_cnt; /**< Reference counter. */ pj_lock_t *lock; /**< Lock object. */ - int tracing; /**< Tracing enabled? */ + pj_bool_t tracing; /**< Tracing enabled? */ + pj_bool_t is_shutdown; /**< Being shutdown? */ /** Key for indexing this transport in hash table. */ struct { @@ -549,7 +550,28 @@ struct pjsip_transport pj_ssize_t sent_bytes)); /** - * Destroy this transport. + * Instruct the transport to initiate graceful shutdown procedure. + * After all objects release their reference to this transport, + * the transport will be deleted. + * + * Note that application MUST use #pjsip_transport_shutdown() instead. + * + * @param transport The transport. + * + * @return PJ_SUCCESS on success. + */ + pj_status_t (*do_shutdown)(pjsip_transport *transport); + + /** + * Forcefully destroy this transport regardless whether there are + * objects that currently use this transport. This function should only + * be called by transport manager or other internal objects (such as the + * transport itself) who know what they're doing. Application should use + * #pjsip_transport_shutdown() instead. + * + * @param transport The transport. + * + * @return PJ_SUCCESS on success. */ pj_status_t (*destroy)(pjsip_transport *transport); @@ -560,32 +582,93 @@ struct pjsip_transport /** - * Register a transport. + * Register a transport instance to the transport manager. This function + * is normally called by the transport instance when it is created + * by application. + * + * @param mgr The transport manager. + * @param tp The new transport to be registered. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_transport_register( pjsip_tpmgr *mgr, pjsip_transport *tp ); /** - * Unregister transport. This will eventually call the transport to - * destroy itself. + * Start graceful shutdown procedure for this transport. After graceful + * shutdown has been initiated, no new reference can be obtained for + * the transport. However, existing objects that currently uses the + * transport may still use this transport to send and receive packets. + * + * After all objects release their reference to this transport, + * the transport will be destroyed immediately. + * + * @param tp The transport. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pjsip_transport_shutdown(pjsip_transport *tp); + +/** + * Destroy a transport when there is no object currently uses the transport. + * This function is normally called internally by transport manager or the + * transport itself. Application should use #pjsip_transport_shutdown() + * instead. + * + * @param tp The transport instance. + * + * @return PJ_SUCCESS on success or the appropriate error code. + * Some of possible errors are PJSIP_EBUSY if the + * transport's reference counter is not zero. */ -PJ_DECL(pj_status_t) pjsip_transport_unregister( pjsip_tpmgr *mgr, - pjsip_transport *tp); +PJ_DECL(pj_status_t) pjsip_transport_destroy( pjsip_transport *tp); /** - * Add ref. + * Add reference counter to the specified transport. Any objects that wishes + * to keep the reference of the transport MUST increment the transport's + * reference counter to prevent it from being destroyed. + * + * @param tp The transport instance. + * + * @return PJ_SUCCESS on success or the appropriate error code. */ PJ_DECL(pj_status_t) pjsip_transport_add_ref( pjsip_transport *tp ); /** - * Dec ref. + * Decrement reference counter of the specified transport. When an object no + * longer want to keep the reference to the transport, it must decrement the + * reference counter. When the reference counter of the transport reaches + * zero, the transport manager will start the idle timer to destroy the + * transport if no objects acquire the reference counter during the idle + * interval. + * + * @param tp The transport instance. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_transport_dec_ref( pjsip_transport *tp ); /** - * Call for incoming message. + * This function is called by transport instances to report an incoming + * packet to the transport manager. The transport manager then would try to + * parse all SIP messages in the packet, and for each parsed SIP message, it + * would report the message to the SIP endpoint (#pjsip_endpoint). + * + * @param mgr The transport manager instance. + * @param rdata The receive data buffer containing the packet. The + * transport MUST fully initialize tp_info and pkt_info + * member of the rdata. + * + * @return The number of bytes successfully processed from the + * packet. If the transport is datagram oriented, the + * value will be equal to the size of the packet. For + * stream oriented transport (e.g. TCP, TLS), the value + * returned may be less than the packet size, if + * partial message is received. The transport then MUST + * keep the remainder part and report it again to + * this function once more data/packet is received. */ PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr, pjsip_rx_data *rdata); @@ -597,14 +680,20 @@ PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr, * *****************************************************************************/ - -/** - * Transport factory. +/* + * Forward declaration for transport factory (since it is referenced by + * the transport factory itself). */ typedef struct pjsip_tpfactory pjsip_tpfactory; + /** - * Transport factory. + * A transport factory is normally used for connection oriented transports + * (such as TCP or TLS) to create instances of transports. It registers + * a new transport type to the transport manager, and the transport manager + * would ask the factory to create a transport instance when it received + * command from application to send a SIP message using the specified + * transport type. */ struct pjsip_tpfactory { diff --git a/pjsip/include/pjsip/sip_transport_tcp.h b/pjsip/include/pjsip/sip_transport_tcp.h new file mode 100644 index 00000000..317d7772 --- /dev/null +++ b/pjsip/include/pjsip/sip_transport_tcp.h @@ -0,0 +1,62 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_TRANSPORT_TCP_H__ +#define __PJSIP_TRANSPORT_TCP_H__ + +/** + * @file sip_transport_tcp.h + * @brief SIP TCP Transport. + */ + +#include <pjsip/sip_transport.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_TRANSPORT_TCP TCP Transport + * @ingroup PJSIP_TRANSPORT + * @brief API to create and register TCP transport. + * @{ + * The functions below are used to create TCP transport and register + * the transport to the framework. + */ + +/** + * Create, register, and start TCP transport. + * + * @param endpt The SIP endpoint. + * @param local Local address to bind. + * @param async_cnt Number of simultaneous async operations. + * + * @return PJ_SUCCESS when the transport has been successfully + * started and registered to transport manager, or + * the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_tcp_transport_start(pjsip_endpoint *endpt, + const pj_sockaddr_in *local, + unsigned async_cnt); + + +PJ_END_DECL + +/** + * @} + */ + +#endif /* __PJSIP_TRANSPORT_TCP_H__ */ diff --git a/pjsip/include/pjsip/sip_transport_udp.h b/pjsip/include/pjsip/sip_transport_udp.h index 7cf8f553..77e76657 100644 --- a/pjsip/include/pjsip/sip_transport_udp.h +++ b/pjsip/include/pjsip/sip_transport_udp.h @@ -29,7 +29,7 @@ PJ_BEGIN_DECL /** - * @defgroup PJSIP_TRANSPORT_UDP UDP transport + * @defgroup PJSIP_TRANSPORT_UDP UDP Transport * @ingroup PJSIP_TRANSPORT * @brief API to create and register UDP transport. * @{ |