1/**@MODULEPAGE "tport" - Transport Module 2 3@section tport_meta Module Information 4 5The @b tport module contains a generic transport interface used by SIP, 6RTSP, and HTTP protocols. It is an abstraction layer between a protocol 7stack and a transport protocol implementation. The interface is implemented 8via transport objects. The tag parameters for transport objects are defined 9in <sofia-sip/tport_tag.h>. 10 11@CONTACT Pekka.Pessi@nokia.com 12 13@STATUS @SofiaSIP Core library 14 15@LICENSE LGPL 16 17@section tp_primary Master, Primary and Secondary Transport Objects 18 19A transport object can be used in three roles. Master transport object 20represents all available transport. It is used to store stack and root 21interface as well as common data such as SigComp state handler. The primary 22transport objects represent available transports. The secondary transports 23represent actual transport connections. 24 25A protocol stack first creates a @e master @e transport object and binds a 26number of primary transport objects (each representing a transport protocol 27such as UDP, TCP, TLS/TCP, SCTP, etc). The binding process creates a new 28primary transport object for each transport supported. If the protocol stack 29is used as a server, the binding process also creates the necessary server 30sockets and binds them to the specified server ports. 31 32Secondary transport objects are created for each transport-level 33connection. The @b tport module takes care of automatically creating them 34and discarding them when they are no more used. The secondary transport 35objects are required to transmit messages when a connection-oriented 36transport protocol is used. 37 38A secondary transport object can be created for two reasons. A server may 39accept a new connection from a client, or a client may connect to a 40server. When the connection belonging to a secondary transport has been 41established, the protocol stack can send or receive messages through it. 42 43@section tp_init Initializing Transports 44 45When the primary transport object is created with tport_tcreate(), the 46protocol stack must pass a #tport_stack_class_t structure containing 47function pointers to the new transport object. These function pointers 48are used to 49 50-# create new message objects used to store received messages 51-# pass received messages to the protocol stack, and 52-# report transport errors to the protocol stack. 53 54The transport protocols are bound to the primary transport objects with 55the method tport_tbind(). The protocol stack gives the desired server 56transport name (transport name is a structure containing a text-formatted 57socket address along with transport name) along with the list of 58transport protocols supported by the stack. The function tport_tbind() 59can be called multiple times, if, for example, the server port(s) used by 60transport protocol differ (for example, default TCP port for SIP is 5060, 61and default TLS port is 5061). 62 63@subsection tp_connect Connection-Oriented and Connection-Less Transports 64 65A secondary transport objects is created for each transport-level 66connection. The tport module takes care of automatically creating them, 67and discarding them when they are no more used. The secondary transport 68objects are required to transmit messages when a connection-oriented 69transport protocol is used. 70 71A secondary transport can be created for two reasons. A server may accept 72a new connection from a client, or a client may connect to a server. When 73the connection belonging to a secondary transport has been established, 74the protocol stack can send or receive messages through it. 75 76@par Connection-Oriented and Connection-Less Transports 77 78A transport can be connection-oriented (TCP, SCTP) or connectionless 79(UDP). A connection-oriented transport needs a connection to be 80established before messages can be sent. It can also send messages only 81to a single destination. For a connectionless transport, a destination 82address must always be given. 83 84A connectionless transport can be used to send messages to several 85distinct destinations. The destination address must be given to the 86kernel whenever a message is sent using connectionless transport. 87 88Note that UDP can be used in connection-oriented manner (client does not 89use sendto(), but connect() and then send()), if tport_set_params() is 90called with TPTAG_CONNECT(1) argument. 91 92@subsection tp_stream Stream and Datagram Transports 93 94A connection-oriented transport can also be stream-based (TCP, SCTP) or 95packet-based (UDP, SCTP). A stream-based transport protocol takes care of 96ordering the data within a stream, a data chunk sent earlier is always 97delivered before chunks sent after it. A packet-based transport delivers 98data chunks independent of each other and does not maintain the relative 99order, for instance, if a data chunk is lost by the network and then 100retransmitted, application can receive it later than a data chunk that 101was sent after lost one but did not need any retransmissions. 102 103@subsection tp_magic Transport Magic 104 105Transport magic is a cookie, a piece of data specified by stack that can 106be associated with a transport (e.g., a Via header). The protocol stack 107can change the type of transport magic by defining the macro 108#TP_MAGIC_T before including <sofia-sip/tport.h>. 109 110@section tp_op Transport Operations 111 112@subsection tp_send Sending Messages 113 114A message can be sent by the tport_tsend() method. The method can be 115called either from the primary or from the secondary transport. If a 116secondary transport is needed to send the message, it is created and 117connected automatically. 118 119The transport gets the data to be sent from the message object with 120msg_iovec() call. The transport tries to send all the data using one 121su_vsend() call. If the call would fail, for instance, because the send 122buffer is too short, the transport object would create a reference to the 123message and queue it in its own queue. 124 125@subsection tp_recv Receiving Messages 126 127When a primary connectionless transport object or a secondary transport 128object receives new data, it allocates a new message object. The message 129object is created using the factory function tpac_alloc() provided by the 130protocl stack. The incoming data is passed to the message object, data is 131parsed and when a message is complete, it is passed to the application 132using the tpac_recv() function provided when the transport was created. 133 134@subsection tp_refcnt Reference Counting 135 136In order to destroy unused connections, each secondary transport object 137needs to know if there is a reference to it from the stack. A protocol 138stack creates a reference to a transport when it receives an incoming 139request and needs to send the response using the same transport, or when 140it expects a reply from the server coming on the connection used to send 141the request. 142 143@note While the reference counting has been implemented in the tport 144module, the transport objects are not destroyed by timers by default as 145all the protocol stacks do @b not properly handle the reference counting. 146Timers are activated when the tag TPTAG_IDLE() is used. 147 148@subsection tp_pend Pending Requests 149 150The protocol stack can mark requests as @e pending using tport_pend() 151function. The tport_pend() function associates a request message with a 152callback and a handle to a client object. When a transport error occurs, 153it is reported to the client object using the associated callback 154function. 155 156When the stack receives a response to the request it has marked as 157pending, it calls tport_release(). The request can be still considered 158pending, if the response was a preliminary one. In this case, the @a 159still_pending argument is true. The function tport_release() is also 160called without response message, if the stack is no more interested in 161the response, for instance, after a timeout. 162 163@subsection tp_queue Send Queue 164 165Each stream-based transport also supports send queue. The queue can be 166used either to queue messages during congestion, or to maintain the 167relative ordering of responses. Usually, queue is used implicitly for the 168first purpose, e.g., if a transport is busy sending a message it queues 169further messages when tport_tsend() is called. 170 171Explicit queueing is needed when the protocol (like HTTP/1.1) requires 172that the relative order of responses is maintained. When the protocol 173stack receives a request, it queues an empty response message to the 174transport with tport_tqueue(). Such an empty response is marked as 175incomplete, not ready to send. When application responds to the request 176via tport_tqsend(), the transport object marks the message ready to send 177and, if there are no other queued responses before it, sends it. 178 179@section tp_debug Logging and Dumping Messages 180 181Seeing message contents and network events is extremely useful when 182debugging protocols. There are environment variables that are used to 183activate message logging within @b tport module. 184<dl compact> 185<dt>@b #TPORT_LOG 186 <dd>if set, tport module prints out the message contents 187 after parsing 188<dt>@b #TPORT_DUMP 189 <dd>contains dump file name - incoming data is written 190 dump file @e before parsing 191<dt>@b #TPORT_DEBUG 192 <dd>integer in range -1..9 controlling amount of 193 debugging printout from @b tport module. See also #tport_log. 194</dl> 195 */ 196 197