Changes between Version 2 and Version 3 of SIP_Message_Buffer_Event


Ignore:
Timestamp:
Jan 17, 2008 9:57:05 AM (16 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • SIP_Message_Buffer_Event

    v2 v3  
     1---- 
     2Table of Contents: 
     3 
     4[[PageOutline(2-3,,inline)]] 
     5---- 
     6 
    17= Message, Buffers, and Event = 
    28 
    3 SIP message (request or response) is represented by [http://www.pjsip.org/pjsip/docs/html/structpjsip__msg.htm pjsip_msg] structure, but application would rarely see this structure passed directly in the API. For incoming and outgoing messages, the message would be contained in a RX or TX data buffer, [http://www.pjsip.org/pjsip/docs/html/structpjsip__rx__data.htm pjsip_rx_data] and [http://www.pjsip.org/pjsip/docs/html/structpjsip__tx__data.htm pjsip_tx_data] respectively. When passing SIP messages among modules, PJSIP also normally does not pass the buffers directly, but rather encapsulate it as [http://www.pjsip.org/pjsip/docs/html/structpjsip__event.htm pjsip_event] structure.  
     9SIP message (request or response) is represented by [http://www.pjsip.org/pjsip/docs/html/structpjsip__msg.htm pjsip_msg] structure, but application would rarely see this structure passed directly in the API. For incoming and outgoing messages, the message would be contained in a RX or TX data buffer, [http://www.pjsip.org/pjsip/docs/html/structpjsip__rx__data.htm pjsip_rx_data] and [http://www.pjsip.org/pjsip/docs/html/structpjsip__tx__data.htm pjsip_tx_data] respectively. When passing SIP messages among modules, PJSIP also normally does not pass the buffer directly, but rather encapsulate it as [http://www.pjsip.org/pjsip/docs/html/structpjsip__event.htm pjsip_event] structure.  
     10 
     11Because of these multi-encapsulations, extracting a particular information from a particular structure can be daunting, especially if you haven't read the PJSIP Bible (the PJSIP Developer's Guide PDF, from [http://www.pjsip.org/docs.htm PJSIP Documentation] page). This article presents a short description about these structures to help you get started quickly. 
     12 
     13== SIP Message (pjsip_msg) == 
     14 
     15The [http://www.pjsip.org/pjsip/docs/html/structpjsip__msg.htm pjsip_msg] structure corresponds directly to SIP messaging elements as described by the SIP protocol specification, [http://www.ietf.org/rfc/rfc3261.txt RFC 3261]. It contains: 
     16 * SIP message type (request or response), 
     17 * SIP request line or status line, depending on the message type 
     18 * list of SIP header fields 
     19 * message body 
     20 
     21There is nothing else in [http://www.pjsip.org/pjsip/docs/html/structpjsip__msg.htm pjsip_msg]. 
     22 
     23SIP messaging elements are declared in [source:pjproject/trunk/pjsip/include/pjsip/sip_msg.h <pjsip/sip_msg.h>]. 
     24 
     25== Transmit and Receive Buffers == 
     26 
     27Incoming and outgoing messages are encapsulated in a RX or TX data buffer, [http://www.pjsip.org/pjsip/docs/html/structpjsip__rx__data.htm pjsip_rx_data] and [http://www.pjsip.org/pjsip/docs/html/structpjsip__tx__data.htm pjsip_tx_data] respectively. We need these buffers since there are more information to be conveyed in incoming and outgoing message than just a plain SIP message structure (and it would not make sense to put these information in the SIP message, since they are not messaging elements). 
     28 
     29The [http://www.pjsip.org/pjsip/docs/html/structpjsip__rx__data.htm pjsip_rx_data] contains these major parts: 
     30 * transport info (''tp_info'' field), describing the transport instance which own this buffer. 
     31 * information about the incoming packet (''pkt_info'' field), such as source address, arrival time, and the packet buffer, 
     32 * messaging info (''msg_info'' field), containing among other thing the raw message, the parsed [http://www.pjsip.org/pjsip/docs/html/structpjsip__msg.htm pjsip_msg], and shortcuts to important headers, and 
     33 * modules info (''endpt_info'' field), which will be filled by PJSIP modules as the buffer are processed by them. 
     34 
     35The [http://www.pjsip.org/pjsip/docs/html/structpjsip__tx__data.htm pjsip_tx_data] contains: 
     36 * memory pool to allocate memory for this buffer, 
     37 * the [http://www.pjsip.org/pjsip/docs/html/structpjsip__msg.htm pjsip_msg] itself, 
     38 * reference counter, 
     39 * and so on 
     40 
     41Transmit and receive buffers are declared in [source:pjproject/trunk/pjsip/include/pjsip/sip_transport.h  <pjsip/sip_transport.h>]. 
     42 
     43=== Memory Management of the RX/TX Buffer === 
     44 
     45Each RX and TX buffer has its own memory pool ({{{pj_pool_t}}}. It is important to understand how to use the memory pool in these buffers to avoid problems with memory (memory usage keeps growing, or crash because memory no longer valid). 
     46 
     47'''Memory pool in RX buffer''' 
     48 
     49The [http://www.pjsip.org/pjsip/docs/html/structpjsip__rx__data.htm pjsip_rx_data] is a temporary object, and it is only valid in the context of the callback. Once the callback returns, this structure will be reset (because of this, you '''cannot''' keep this structure, or pass this structure to another thread for asynchronous processing).  
     50 
     51The {{{pjsip_rx_data->tp_info.pool}}} points to the memory pool owned by the RX buffer. 
     52 
     53Characteristics of this pool: 
     54 - it's quite large (default value is 4000 bytes/PJSIP_POOL_RDATA_LEN, and it can expand), so it can be used to allocate large objects 
     55 - the pool will be recycled/reset as soon as the callback returns, so any memory allocated from this pool will automatically be released when the callback returns. 
     56 
     57Because of the characteristics above, the pool is useful to allocate temporary objects related to the incoming message, such as: 
     58 - to parse the SDP content of the message body. But beware that if you need to store the parsed result for further processing (for example, the invite session needs to store the offer in the incoming INVITE request), you will need to ''clone'' the result, since the pool will be reset upon returning from the callback, thus it will render the result invalid. 
     59 - to allocate other temporary objects that are only valid during the context of the callback 
     60 
     61 
     62 
     63'''Memory pool in TX buffer''' 
     64 
     65The TX buffer is reference counted. Any objects that need to keep a reference of the TX buffer need to call [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__TRANSPORT.htm#gedc51486a3217528198a6d40651949d5 pjsip_tx_data_add_ref()] to increment the reference counter, and once it has finished with the TX buffer it must call [http://www.pjsip.org/pjsip/docs/html/group__PJSIP__TRANSPORT.htm#gbeec4be34c0a472782b9224c2c7d08f1 pjsip_tx_data_dec_ref()] to decrement the reference counter (for example, the transaction needs to keep the TX buffer for retransmissions). The TX buffer will be destroyed when the reference counter has reached zero. 
     66 
     67Characteristics of this pool: 
     68 - it's quite large (default value is 4000 bytes/PJSIP_POOL_TDATA_LEN, and it can expand), so it can be used to allocate large objects 
     69 - the pool will be destroyed when the TX buffer is destroyed, so any memory allocated from this pool will automatically be released when the TX data is destroyed. 
     70 
     71Because of the characteristics above, the pool is useful to allocate objects that are valid for the duration of the message, such as: 
     72 - SIP headers to be put on the message 
     73 - SIP message body 
     74 
     75 
     76== Event == 
    477 
    578The [http://www.pjsip.org/pjsip/docs/html/structpjsip__event.htm pjsip_event] is PJSIP's way to represent any known SIP event types, such as: 
    … …  
    1083 - and so on 
    1184 
    12 For detailed information about SIP messaging and RX/TX buffer design in PJSIP, please read the PJSIP Developer's Guide PDF (also known as PJSIP Bible ;-)) in [http://www.pjsip.org/docs.htm PJSIP Documentation] page. 
     85The [http://www.pjsip.org/pjsip/docs/html/structpjsip__event.htm pjsip_event] usually is a temporary variable allocated from the stack, thus it's pointer MUST NOT be kept for the duration longer than the callback.  
     86 
     87PJSIP event is declared in [source:pjproject/trunk/pjsip/include/pjsip/sip_event.h  <pjsip/sip_event.h>]. More will be explained in the next section. 
    1388 
    1489----