res/pjproject/pjsip/include/pjsip/sip_multipart.h

   1 /* $Id$ */
   2 /*
   3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18  */
  19 #ifndef __PJSIP_SIP_MULTIPART_H__
  20 #define __PJSIP_SIP_MULTIPART_H__
  21
  22 /**
  23  * @file pjsip/sip_multipart.h
  24  * @brief Multipart support.
  25  */
  26
  27 #include <pjsip/sip_msg.h>
  28
  29 PJ_BEGIN_DECL
  30
  31 /**
  32  * @defgroup PJSIP_MULTIPART Multipart message bodies.
  33  * @ingroup PJSIP_MSG
  34  * @brief Support for multipart message bodies.
  35  * @{
  36  */
  37
  38 /**
  39  * This structure describes the individual body part inside a multipart
  40  * message body. It mainly contains the message body itself and optional
  41  * headers.
  42  */
  43 typedef struct pjsip_multipart_part
  44 {
  45     /**
  46      * Standard list element.
  47      */
  48     PJ_DECL_LIST_MEMBER(struct pjsip_multipart_part);
  49
  50     /**
  51      * Optional message headers.
  52      */
  53     pjsip_hdr               hdr;
  54
  55     /**
  56      * Pointer to the message body.
  57      */
  58     pjsip_msg_body         *body;
  59
  60 } pjsip_multipart_part;
  61
  62 /**
  63  * Create an empty multipart body.
  64  *
  65  * @param pool          Memory pool to allocate memory from.
  66  * @param ctype         Optional MIME media type of the multipart
  67  *                      bodies. If not specified, "multipart/mixed"
  68  *                      will be used.
  69  * @param boundary      Optional string to be set as part boundary.
  70  *                      The boundary string excludes the leading
  71  *                      hyphens. If this parameter is NULL or empty,
  72  *                      a random boundary will be generated.
  73  *
  74  * @return              Multipart body instance with no part.
  75  */
  76 PJ_DECL(pjsip_msg_body*) pjsip_multipart_create(pj_pool_t *pool,
  77                                                 const pjsip_media_type *ctype,
  78                                                 const pj_str_t *boundary);
  79
  80 /**
  81  * Create an empty multipart part.
  82  *
  83  * @param pool          The memory pool.
  84  *
  85  * @return              The multipart part.
  86  */
  87 PJ_DECL(pjsip_multipart_part*) pjsip_multipart_create_part(pj_pool_t *pool);
  88
  89
  90 /**
  91  * Perform a deep clone to a multipart part.
  92  *
  93  * @param pool          The memory pool.
  94  * @param part          The part to be duplicated.
  95  *
  96  * @return              Copy of the multipart part.
  97  */
  98 PJ_DECL(pjsip_multipart_part*)
  99 pjsip_multipart_clone_part(pj_pool_t *pool,
 100                            const pjsip_multipart_part *part);
 101
 102 /**
 103  * Add a part into multipart bodies.
 104  *
 105  * @param pool          The memory pool.
 106  * @param mp            The multipart bodies.
 107  * @param part          The part to be added into the bodies.
 108  *
 109  * @return              PJ_SUCCESS on success.
 110  */
 111 PJ_DECL(pj_status_t) pjsip_multipart_add_part(pj_pool_t *pool,
 112                                               pjsip_msg_body *mp,
 113                                               pjsip_multipart_part *part);
 114
 115 /**
 116  * Get the first part of multipart bodies.
 117  *
 118  * @param mp            The multipart bodies.
 119  *
 120  * @return              The first part, or NULL if the multipart
 121  *                      bodies currently doesn't hold any elements.
 122  */
 123 PJ_DECL(pjsip_multipart_part*)
 124 pjsip_multipart_get_first_part(const pjsip_msg_body *mp);
 125
 126 /**
 127  * Get the next part after the specified part.
 128  *
 129  * @param mp            The multipart bodies.
 130  * @param part          The part.
 131  *
 132  * @return              The next part, or NULL if there is no other part after
 133  *                      the part.
 134  */
 135 PJ_DECL(pjsip_multipart_part*)
 136 pjsip_multipart_get_next_part(const pjsip_msg_body *mp,
 137                               pjsip_multipart_part *part);
 138
 139 /**
 140  * Find a body inside multipart bodies which has the specified content type.
 141  *
 142  * @param mp            The multipart body.
 143  * @param content_type  Content type to find.
 144  * @param start         If specified, the search will begin at
 145  *                      start->next. Otherwise it will begin at
 146  *                      the first part in the multipart bodies.
 147  *
 148  * @return              The first part with the specified content type
 149  *                      if found, or NULL.
 150  */
 151 PJ_DECL(pjsip_multipart_part*)
 152 pjsip_multipart_find_part( const pjsip_msg_body *mp,
 153                            const pjsip_media_type *content_type,
 154                            const pjsip_multipart_part *start);
 155
 156 /**
 157  * Parse multipart message.
 158  *
 159  * @param pool          Memory pool.
 160  * @param buf           Input buffer.
 161  * @param len           The buffer length.
 162  * @param ctype         Content type of the multipart body.
 163  * @param options       Parsing options, must be zero for now.
 164  *
 165  * @return              Multipart message body.
 166  */
 167 PJ_DECL(pjsip_msg_body*) pjsip_multipart_parse(pj_pool_t *pool,
 168                                                char *buf, pj_size_t len,
 169                                                const pjsip_media_type *ctype,
 170                                                unsigned options);
 171
 172 /**
 173  * @}  PJSIP_MULTIPART
 174  */
 175
 176
 177 PJ_END_DECL
 178
 179 #endif  /* __PJSIP_SIP_MULTIPART_H__ */