Support for multipart message bodies

[bennylp]

This ticket implements support for multipart message bodies, with the following specification.

Multipart API

New APIs will be added to create, parse, and manipulate multipart message bodies. These APIs will reside in a new header file, <pjsip/sip_multipart.h>.

Parser Specification

Multipart message bodies in the incoming message will be parsed automatically. This is controlled by a new setting, PJSIP_AUTO_PARSE_MULTIPART, which default value is TRUE. If this setting is set to FALSE, the parser will revert to the old behavior, i.e. it will not automatically parse the multipart bodies in the incoming messages.

Note that the parser still will not parse the content of the multipart bodies. For example, consider the following example:

Content-Type: multipart/mixed;boundary=xxxxx

--xxxxx
Content-Type: application/sdp

v=0
o=- 3483093653 3483093653 IN IPv4 10.0.0.1
s=pjmedia

c=IN IP4 10.0.0.1
t=0 0

m=audio 4000 RTP/AVP 0
--xxxxx
Content-Type: text/plain

Hello please answer my call
--xxxxx--

With the above message, the parser recognizes that the message contains multipart bodies, so it will parse it into a multipart instance. The multipart instance will contain two body parts, application/sdp and text/plain. The parser however, will not parse the parts further (the parsing of the application/sdp content will be done by the invite session).

Multipart Handling in PJSIP Layer

These applies to the invite session (pjsip_inv_session), presence subscription session, event publication session, and call transfer (refer) handling.

Incoming messages

The session will recognize multipart message bodies in incoming messages, and be able to look for the appropriate part in the bodies.

Outgoing messages

There will be no change in outgoing message API. If higher layer components (e.g. PJSUA-LIB) want to send multipart body, it may alter the transmit buffer before sending the message.

Multipart Handling in PJSUA-LIB

The following will describe the following pattern that will be used in PJSUA-LIB to support multipart message bodies.

Incoming messages

There will be no change in the handling of incoming messages containing multipart bodies, as they will be processed by the underlying session (e.g. invite session).

If application wants to extract the multipart content from an incoming message, it can inspect the message from the rdata or event parameter of the appropriate callback, recognize the multipart content from the message body's content type, and use the multipart API to extract the parts.

Outgoing messages

New fields will be added to the pjsua_msg_data:

struct pjsua_msg_data
{
    ...

    /** Content type of the multipart body */
    pj_str_t  multipart_ctype;

    /** List of multipart parts */
    pjsip_multipart_part parts;
};

If application wants to send multipart contents, it constructs the parts it intends to send, put them in the parts list above, and set the multipart_ctype appropriately (e.g. to "multipart/mixed").