stream/freesdp/common.h

   1 /*
   2   This file is part of FreeSDP.
   3   Copyright (C) 2001,2002,2003 Federico Montesino Pouzols <fedemp@altern.org>
   4
   5   FreeSDP is free software; you can redistribute it and/or modify it
   6   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
  20 /**
  21  * @file common.h
  22  * @ingroup common
  23  * @short Public header common for both parsing and formatting modules.
  24  **/
  25
  26 #ifndef FSDP_COMMON_H
  27 #define FSDP_COMMON_H
  28
  29 /* Macros to avoid name mangling when compiling with a C++ compiler */
  30 #ifdef __cplusplus
  31 #  define BEGIN_C_DECLS extern "C" {
  32 #  define END_C_DECLS   }
  33 #else /* !__cplusplus */
  34 #  define BEGIN_C_DECLS
  35 #  define END_C_DECLS
  36 #endif /* __cplusplus */
  37
  38 #include <sys/time.h>
  39 #include <time.h>
  40
  41 BEGIN_C_DECLS
  42 /**
  43  * @defgroup common FreeSDP Common Facilities
  44  *
  45  * Data types and routines common for both parsing and formatting
  46  * modules.
  47  **/
  48 /** @addtogroup common */
  49 /*@{*/
  50 /**
  51  * @enum fsdp_error_t freesdp/common.h
  52  * @short Error codes in the FreeSDP library.
  53  *
  54  * There is a FSDPE_MISSING_XXXX for each mandatory line, as
  55  * FSDPE_MISSING_OWNER. This kind of error is reported when a
  56  * mandatory description line, such as the owner line, is not found
  57  * where it should be in the SDP description. There are also several
  58  * error codes like FSDPE_INVALID_XXXX. These are returned when there
  59  * is a recognized line in the parsed description that violates the
  60  * SDP syntax or gives wrong parameters, for instance "c=foo bar",
  61  * which would cause a FSDPE_INVALID_CONNECTION error code to be
  62  * returned.
  63  **/
  64 typedef enum
  65 {
  66   FSDPE_OK = 0,
  67   FSDPE_ILLEGAL_CHARACTER,       /**< Misplaced '\r', '\n' or '\0' */
  68   FSDPE_MISSING_VERSION,         /**< The first line is not like
  69                                     v=... */
  70   FSDPE_INVALID_VERSION,         /**< Parse error in version line,
  71                                     perhaps, the version specified in
  72                                     v=... is not valid for FreeSDP */
  73   FSDPE_MISSING_OWNER,           /**< No owner line found in its
  74                                     place */
  75   FSDPE_INVALID_OWNER,           /**< Parse error in owner line */
  76   FSDPE_MISSING_NAME,            /**< No session name found in its
  77                                     place */
  78   FSDPE_EMPTY_NAME,              /**< Empty session name line */
  79
  80   FSDPE_INVALID_CONNECTION,      /**< Syntax error in connection
  81                                     line */
  82
  83   FSDPE_INVALID_CONNECTION_ADDRTYPE, /**< Unrecognized address type in
  84                                         connection line */
  85   FSDPE_INVALID_CONNECTION_NETTYPE,  /**< Unrecognized network type in
  86                                         connection line */
  87   FSDPE_INVALID_BANDWIDTH,           /**< Parse error in bandwidth
  88                                         line */
  89   FSDPE_MISSING_TIME,            /**< No time period has been given
  90                                     for the session */
  91   FSDPE_INVALID_TIME,            /**< Parse error in time line */
  92   FSDPE_INVALID_REPEAT,          /**< Parse error in repeat time
  93                                     line */
  94   FSDPE_INVALID_TIMEZONE,        /**< Parse error in timezone line */
  95   FSDPE_INVALID_ENCRYPTION_METHOD, /**< Unknown encryption method */
  96   FSDPE_INVALID_ATTRIBUTE,       /**< Syntax error in an attribute
  97                                     line */
  98
  99   FSDPE_INVALID_ATTRIBUTE_RTPMAP,/**< Parse error in a=rtpmap:... line */
 100   FSDPE_INVALID_SESSION_TYPE,    /**< An unknown session type has been
 101                                     specified in a `type:'
 102                                     session-level attribute */
 103
 104   FSDPE_INVALID_MEDIA,           /**< Parse error in media line */
 105   FSDPE_UNKNOWN_MEDIA_TYPE,      /**< Unknown media type in media
 106                                     line */
 107
 108   FSDPE_UNKNOWN_MEDIA_TRANSPORT, /**< A media transport has been
 109                                     specified that is unknown */
 110
 111   FSDPE_OVERFILLED,              /**< extra unknown lines are at the
 112                                     end of the description */
 113   FSDPE_INVALID_LINE,            /**< a line unknown to FreeSDP has been
 114                                     found */
 115   FSDPE_MISSING_CONNECTION_INFO, /**< No connection information has
 116                                      been provided for the whole
 117                                      session nor one or more media */
 118   FSDPE_INVALID_INDEX,
 119   /*  FSDPE_MAXSIZE, description does not fit requested maximun size */
 120   FSDPE_INTERNAL_ERROR,
 121
 122   FSDPE_INVALID_PARAMETER,       /**< Some parameter of the called
 123                                        FreeSDP routine has been given an
 124                                        invalid value. This includes
 125                                        cases such as NULL pointers. */
 126   FSDPE_BUFFER_OVERFLOW
 127 } fsdp_error_t;
 128
 129 /**
 130  * @short Type of network
 131  *
 132  * Initially, SDP defines "Internet". New network types may be
 133  * registered with IANA. However, the number of types is expected to
 134  * be small and rarely extended. In addition, every new network type
 135  * requires at least one new address type.
 136  **/
 137 typedef enum
 138 {
 139   FSDP_NETWORK_TYPE_UNDEFINED,                 /**< Not provided */
 140   FSDP_NETWORK_TYPE_INET                       /**< Internet */
 141 } fsdp_network_type_t;
 142
 143 /**
 144  * @short Type of address
 145  *
 146  * Initially, IPv4 and IPv6 are defined for the network type
 147  * Internet. New address types may be registered with IANA.
 148  **/
 149 typedef enum
 150 {
 151   FSDP_ADDRESS_TYPE_UNDEFINED,                 /**< Not provided */
 152   FSDP_ADDRESS_TYPE_IPV4,                     /**< IP version 4 */
 153   FSDP_ADDRESS_TYPE_IPV6                      /**< IP version 6 */
 154 } fsdp_address_type_t;
 155
 156 /**
 157  * @short Type of bandwith modifiers
 158  *
 159  * Bandwidth modifiers specify the meaning of the bandwidth
 160  * value. Initially "Conference Total" and "Application Specific" are
 161  * defined. Both use kilobits as bandwidth unit. "Conference Total"
 162  * specifies that the bandwidth value is a proposed upper limit to the
 163  * session bandwidth. "Application Specific" specifies thath the
 164  * bandwidth value is the application concept of maximum bandwidth.
 165  **/
 166 typedef enum
 167 {
 168   FSDP_BW_MOD_TYPE_UNDEFINED,            /**< Not provided */
 169   FSDP_BW_MOD_TYPE_UNKNOWN,              /**< Unknown bandwidth
 170                                                   modifier (FreeSDP
 171                                                   ignores it) */
 172   FSDP_BW_MOD_TYPE_CONFERENCE_TOTAL,     /**< "CT - Conference Total" */
 173   FSDP_BW_MOD_TYPE_APPLICATION_SPECIFIC, /**< "AS - Application specific" */
 174   FSDP_BW_MOD_TYPE_RTCP_SENDERS,         /**< "RS - RTCP bandwidth for
 175                                             senders */
 176   FSDP_BW_MOD_TYPE_RTCP_RECEIVERS,       /**< "RR - RTCP bandwidth for
 177                                             receivers */
 178 } fsdp_bw_modifier_type_t;
 179
 180 /**
 181  * @short encryption method
 182  *
 183  * The encryption method specifies the way to get the encryption key.
 184  **/
 185 typedef enum
 186 {
 187   FSDP_ENCRYPTION_METHOD_UNDEFINED,    /**< Not provided */
 188   FSDP_ENCRYPTION_METHOD_CLEAR,        /**< The key field is the
 189                                                  untransformed key */
 190   FSDP_ENCRYPTION_METHOD_BASE64,       /**< The key is base64
 191                                           encoded */
 192   FSDP_ENCRYPTION_METHOD_URI,          /**< The key value provided is
 193                                           a URI pointing to the actual
 194                                           key */
 195   FSDP_ENCRYPTION_METHOD_PROMPT        /**< The key is not provided
 196                                           but should be got prompting
 197                                           the user */
 198 } fsdp_encryption_method_t;
 199
 200 /**
 201  * @short Advised reception/transmission mode
 202  *
 203  * Depending on wheter sendrecv, recvonly, sendonly or inactive
 204  * attribute is given, the tools used to participate in the session
 205  * should be started in the corresponding transmission
 206  * mode. FSDP_SENDRECV_SENDRECV is the default for sessions which are
 207  * not of the conference type broadcast or H332.
 208  **/
 209 typedef enum
 210 {
 211   FSDP_SENDRECV_UNDEFINED,                    /**< Not specified */
 212   FSDP_SENDRECV_SENDRECV,                     /**< Send and receive */
 213   FSDP_SENDRECV_RECVONLY,                     /**< Receive only */
 214   FSDP_SENDRECV_SENDONLY,                     /**< Send only */
 215   FSDP_SENDRECV_INACTIVE                      /**< Do not send nor receive */
 216 } fsdp_sendrecv_mode_t;
 217
 218 /**
 219  * @short Values for `orient' media attribute.
 220  *
 221  * Normally used with whiteboard media, this attribute specifies the
 222  * orientation of the whiteboard.
 223  **/
 224 typedef enum
 225 {
 226   FSDP_ORIENT_UNDEFINED,                     /**< Not specified */
 227   FSDP_ORIENT_PORTRAIT,                      /**< Portrait */
 228   FSDP_ORIENT_LANDSCAPE,                     /**< Landscape */
 229   FSDP_ORIENT_SEASCAPE                       /**< Upside down landscape */
 230 } fsdp_orient_t;
 231
 232 /**
 233  * @short Type of the conference
 234  *
 235  * The following types are initially defined: broadcast, meeting,
 236  * moderated, test and H332.
 237  **/
 238 typedef enum
 239 {
 240   FSDP_SESSION_TYPE_UNDEFINED,                 /**< Not specified */
 241   FSDP_SESSION_TYPE_BROADCAST,                 /**< Broadcast session */
 242   FSDP_SESSION_TYPE_MEETING,                   /**< Meeting session */
 243   FSDP_SESSION_TYPE_MODERATED,                 /**< Moderated session */
 244   FSDP_SESSION_TYPE_TEST,                      /**< Test (do not display) */
 245   FSDP_SESSION_TYPE_H332                       /**< H332 session */
 246 } fsdp_session_type_t;
 247
 248 /**
 249  * @short Media type
 250  *
 251  * The following types are defined initially: audio, video,
 252  * application, data and control.
 253  **/
 254 typedef enum
 255 {
 256   FSDP_MEDIA_UNDEFINED,            /**< Not specified */
 257   FSDP_MEDIA_VIDEO,                /**< Video */
 258   FSDP_MEDIA_AUDIO,                /**< Audio */
 259   FSDP_MEDIA_APPLICATION,          /**< Application, such as whiteboard */
 260   FSDP_MEDIA_DATA,                 /**< bulk data */
 261   FSDP_MEDIA_CONTROL               /**< Control channel */
 262 } fsdp_media_t;
 263
 264 /**
 265  * @short Transport protocol
 266  *
 267  * The transport protocol used depends on the address type. Initially,
 268  * RTP over UDP Audio/Video Profile, and UDP are defined.
 269  *
 270  **/
 271 typedef enum
 272 {
 273   FSDP_TP_UNDEFINED,              /**< Not specified */
 274   FSDP_TP_RTP_AVP,                /**< RTP Audio/Video Profile */
 275   FSDP_TP_UDP,                    /**< UDP */
 276   FSDP_TP_TCP,                    /**< TCP */
 277   FSDP_TP_UDPTL,                  /**< ITU-T T.38*/
 278   FSDP_TP_VAT,                    /**< old vat protocol (historic)*/
 279   FSDP_TP_OLD_RTP,                /**< old rtp protocols (historic)*/
 280   FSDP_TP_H320                    /**< TODO: add to the parser */
 281 } fsdp_transport_protocol_t;
 282
 283 /**
 284  * Session-level attributes whose value is specified as a character
 285  * string in FreeSDP. These values are usually given to
 286  * fsdp_get_strn_att() in order to get the corresponding value.
 287  *
 288  **/
 289 typedef enum
 290 {
 291   FSDP_SESSION_STR_ATT_CATEGORY,
 292   FSDP_SESSION_STR_ATT_KEYWORDS,
 293   FSDP_SESSION_STR_ATT_TOOL,
 294   FSDP_SESSION_STR_ATT_CHARSET,
 295 } fsdp_session_str_att_t;
 296
 297 /**
 298  * @short FreeSDP SDP description media object.
 299  *
 300  * Object for media specific information in SDP descriptions. Each SDP
 301  * description may include any number of media section. A
 302  * fsdp_media_description_t object encapsulates the information in a
 303  * media section, such as video, audio or whiteboard.
 304  **/
 305 typedef struct fsdp_media_description_t_s fsdp_media_description_t;
 306
 307 /**
 308  * @short FreeSDP SDP session description object.
 309  *
 310  * Contains all the information extracted from a textual SDP
 311  * description, including all the media announcements.
 312  **/
 313 typedef struct fsdp_description_t_s fsdp_description_t;
 314
 315 /**
 316  * Allocates memory and initializes values for a new
 317  * fsdp_description_t object. If you call this routine, do not forget
 318  * about <code>fsdp_description_delete()</code>
 319  *
 320  * @return new fsdp_description_t object
 321  **/
 322 fsdp_description_t *fsdp_description_new (void);
 323
 324 /**
 325  * Destroys a fsdp_description_t object.
 326  *
 327  * @param dsc pointer to the fsdp_description_t object to delete.
 328  **/
 329 void fsdp_description_delete (fsdp_description_t * dsc);
 330
 331 /**
 332  * Calling this function over a description is equivalent to calling
 333  * fsdp_description_delete and then fsdp_description_delete. This
 334  * function is however more suitable and efficient for description
 335  * processing loops.
 336  *
 337  * @param dsc pointer to the fsdp_description_t object to
 338  * renew/recycle.
 339  **/
 340 void fsdp_description_recycle (fsdp_description_t * dsc);
 341
 342 /**
 343  *  * Returns a string correspondent to the error number.
 344  *   *
 345  *    * @param err_no error number.
 346  *     **/
 347 const char *fsdp_strerror (fsdp_error_t err_no);
 348
 349        /*@}*//* closes addtogroup common */
 350
 351 END_C_DECLS
 352 #endif /* FSDP_COMMON_H */