modules/access/rtp/sdp.h

   1 /**
   2  * @file sdp.h
   3  * @brief Session Description Protocol (SDP)
   4  * @ingroup sdp
   5  */
   6 /*****************************************************************************
   7  * Copyright © 2020 Rémi Denis-Courmont
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this library; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
  22  ****************************************************************************/
  23
  24 #ifndef VLC_SDP_H
  25 #define VLC_SDP_H
  26
  27 #include <stdbool.h>
  28
  29 /**
  30  * \defgroup sdp Session Description Protocol
  31  * \ingroup net
  32  * @{
  33  */
  34
  35 struct vlc_sdp;
  36 struct vlc_sdp_media;
  37 struct vlc_sdp_conn;
  38 struct vlc_sdp_attr;
  39
  40 /**
  41  * Parses an SDP session descriptor.
  42  *
  43  * \param str start address of the descriptor
  44  * \param length bytes length of the descriptor
  45  * \return a parsed SDP or NULL on error (@c errno is set)
  46  */
  47 struct vlc_sdp *vlc_sdp_parse(const char *str, size_t length);
  48
  49 /**
  50  * Destroys a parsed SDP session descriptor.
  51  */
  52 void vlc_sdp_free(struct vlc_sdp *sdp);
  53
  54 const struct vlc_sdp_attr *vlc_sdp_attr_first_by_name(
  55     struct vlc_sdp_attr *const *ap, const char *name);
  56
  57 /** SDP attribute */
  58 struct vlc_sdp_attr
  59 {
  60     struct vlc_sdp_attr *next; /*< Next attribute (or NULL) */
  61     const char *value; /*< Attribute value, or NULL if none */
  62     char name[]; /*< Attribute name */
  63 };
  64
  65 /** SDP connection address */
  66 struct vlc_sdp_conn
  67 {
  68     struct vlc_sdp_conn *next; /*< Next address (or NULL) */
  69     int family; /*< Address family, or AF_UNSPEC if not recognized */
  70     unsigned char ttl; /*< Multicast TTL */
  71     unsigned short addr_count; /*< Multicast address count */
  72     char addr[]; /*< Address name, usually an IP literal */
  73 };
  74
  75 /** SDP media */
  76 struct vlc_sdp_media
  77 {
  78     struct vlc_sdp_media *next; /*< Next media in the session (or NULL) */
  79     struct vlc_sdp *session; /*< Pointer to containing session */
  80     char *type; /*< Media type, e.g. "audio" or "video" */
  81     unsigned int port; /*< Media port number */
  82     unsigned int port_count; /*< Number of ports (usually 1) */
  83     char *proto; /*< Media protocol, e.g. "RTP/AVP" */
  84     char *format; /*< Protocol-specific format parameters */
  85     struct vlc_sdp_conn *conns; /*< List of media connection addresses */
  86     struct vlc_sdp_attr *attrs; /*< List of media attributes */
  87 };
  88
  89 /**
  90  * Gets a media attribute by name.
  91  *
  92  * \param media Session media descriptor.
  93  * \param name Session attribute name.
  94  *
  95  * \note This function does <b>not</b> look for session attributes, as this is
  96  * not always appropriate.
  97  * To fallback to session attributes, call vlc_sdp_attr_get() explicitly.
  98  *
  99  * \return the first attribute with the specified name or NULL if not found.
 100  */
 101 static inline
 102 const struct vlc_sdp_attr *vlc_sdp_media_attr_get(
 103     const struct vlc_sdp_media *media, const char *name)
 104 {
 105     return vlc_sdp_attr_first_by_name(&media->attrs, name);
 106 }
 107
 108 /**
 109  * Checks if a median attribute is present.
 110  *
 111  * \param media Media descriptor.
 112  * \param name Attribute name.
 113  *
 114  * \retval true if present
 115  * \retval false it absent
 116  */
 117 static inline
 118 bool vlc_sdp_media_attr_present(const struct vlc_sdp_media *media,
 119                                 const char *name)
 120 {
 121     return vlc_sdp_media_attr_get(media, name) != NULL;
 122 }
 123
 124 /**
 125  * Returns a media attribute value.
 126  *
 127  * \param media Media descriptor.
 128  * \param name Attribute name.
 129  *
 130  * \note This function cannot distinguish the cases of a missing attribute and
 131  * of an attribute without a value.
 132  * Use vlc_sdp_media_attr_present() to check for value-less attributes.
 133  *
 134  * \return Nul-terminated attribute value, or NULL if none.
 135  */
 136 static inline
 137 const char *vlc_sdp_media_attr_value(const struct vlc_sdp_media *media,
 138                                      const char *name)
 139 {
 140     const struct vlc_sdp_attr *a = vlc_sdp_media_attr_get(media, name);
 141     return (a != NULL) ? a->value : NULL;
 142 }
 143
 144 /** SDP session descriptor */
 145 struct vlc_sdp
 146 {
 147     char *name; /*< Session name */
 148     char *info; /*< Session description, or NULL if none */
 149     struct vlc_sdp_conn *conn; /*< Session connection address or NULL */
 150     struct vlc_sdp_attr *attrs; /*< List of session attributes */
 151     struct vlc_sdp_media *media; /*< List of session media */
 152 };
 153
 154 /**
 155  * Returns the media connection address list.
 156  */
 157 static inline
 158 const struct vlc_sdp_conn *vlc_sdp_media_conn(
 159     const struct vlc_sdp_media *media)
 160 {
 161     return (media->conns != NULL) ? media->conns : media->session->conn;
 162 }
 163
 164 /**
 165  * Gets a session attribute by name.
 166  *
 167  * \param sdp Session descriptor.
 168  * \param name Attribute name.
 169  *
 170  * \return the first attribute with the specified name or NULL if not found.
 171  */
 172 static inline
 173 const struct vlc_sdp_attr *vlc_sdp_attr_get(const struct vlc_sdp *sdp,
 174                                             const char *name)
 175 {
 176     return vlc_sdp_attr_first_by_name(&sdp->attrs, name);
 177 }
 178
 179 /**
 180  * Checks if a session attribute is present.
 181  *
 182  * \param sdp Session descriptor.
 183  * \param name Attribute name.
 184  *
 185  * \retval true if present
 186  * \retval false it absent
 187  */
 188 static inline
 189 bool vlc_sdp_attr_present(const struct vlc_sdp *sdp, const char *name)
 190 {
 191     return vlc_sdp_attr_get(sdp, name) != NULL;
 192 }
 193
 194 /**
 195  * Returns a session attribute value.
 196  *
 197  * \param sdp Session descriptor.
 198  * \param name Attribute name.
 199  *
 200  * \note This function cannot distinguish the cases of a missing attribute and
 201  * of an attribute without a value.
 202  * Use vlc_sdp_attr_present() to check for value-less attributes.
 203  *
 204  * \return Nul-terminated attribute value, or NULL if none.
 205  */
 206 static inline
 207 const char *vlc_sdp_attr_value(const struct vlc_sdp *sdp, const char *name)
 208 {
 209     const struct vlc_sdp_attr *a = vlc_sdp_attr_get(sdp, name);
 210     return (a != NULL) ? a->value : NULL;
 211 }
 212
 213 /** @} */
 214
 215 #endif