oRTP: include/ortp/rtpsession.h Source File

- Main Page
- Data Structures
- Files

# include/ortp/rtpsession.h

Go to the documentation of this file.

    00001  /*
    00002   The oRTP library is an RTP (Realtime Transport Protocol - rfc3550) stack.
    00003   Copyright (C) 2001  Simon MORLAT simon.morlat@linphone.org
    00004
    00005   This library is free software; you can redistribute it and/or
    00006   modify it under the terms of the GNU Lesser General Public
    00007   License as published by the Free Software Foundation; either
    00008   version 2.1 of the License, or (at your option) any later version.
    00009
    00010   This library is distributed in the hope that it will be useful,
    00011   but WITHOUT ANY WARRANTY; without even the implied warranty of
    00012   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    00013   Lesser General Public License for more details.
    00014
    00015   You should have received a copy of the GNU Lesser General Public
    00016   License along with this library; if not, write to the Free Software
    00017   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    00018 */
    00019
    00030 #ifndef RTPSESSION_H
    00031 #define RTPSESSION_H
    00032
    00033
    00034 #include <ortp/port.h>
    00035 #include <ortp/rtp.h>
    00036 #include <ortp/payloadtype.h>
    00037 #include <ortp/sessionset.h>
    00038 #include <ortp/rtcp.h>
    00039 #include <ortp/str_utils.h>
    00040 #include <ortp/rtpsignaltable.h>
    00041 #include <ortp/event.h>
    00042
    00043
    00044
    00045 typedef enum {
    00046         RTP_SESSION_RECVONLY,
    00047         RTP_SESSION_SENDONLY,
    00048         RTP_SESSION_SENDRECV
    00049 } RtpSessionMode;
    00050
    00051
    00054 typedef struct _JBParameters{
    00055         int min_size;
    00056         int nom_size;
    00057         int max_size;
    00058         bool_t adaptive;
    00059         bool_t pad[3];
    00060         int max_packets;
    00061 } JBParameters;
    00062
    00063 typedef struct _JitterControl
    00064 {
    00065         int count;
    00066         int jitt_comp;   /* the user jitt_comp in miliseconds*/
    00067         int jitt_comp_ts; /* the jitt_comp converted in rtp time (same unit as timestamp) */
    00068         int adapt_jitt_comp_ts;
    00069         int64_t slide;
    00070         int64_t prev_slide;
    00071         float jitter;
    00072         int olddiff;
    00073         float inter_jitter;     /* interarrival jitter as defined in the RFC */
    00074         int corrective_step;
    00075         int corrective_slide;
    00076         bool_t adaptive;
    00077         bool_t enabled;
    00078 } JitterControl;
    00079
    00080 typedef struct _WaitPoint
    00081 {
    00082         ortp_mutex_t lock;
    00083         ortp_cond_t  cond;
    00084         uint32_t time;
    00085         bool_t wakeup;
    00086 } WaitPoint;
    00087
    00088 typedef struct _RtpTransport
    00089 {
    00090         void *data;
    00091         ortp_socket_t (*t_getsocket)(struct _RtpTransport *t);
    00092         int  (*t_sendto)(struct _RtpTransport *t, mblk_t *msg , int flags, const struct sockaddr *to, socklen_t tolen);
    00093         int  (*t_recvfrom)(struct _RtpTransport *t, mblk_t *msg, int flags, struct sockaddr *from, socklen_t *fromlen);
    00094         struct _RtpSession *session;//<back pointer to the owning session, set by oRTP
    00095 }  RtpTransport;
    00096
    00097
    00098
    00099 typedef struct _RtpStream
    00100 {
    00101         ortp_socket_t socket;
    00102         struct _RtpTransport *tr;
    00103         int sockfamily;
    00104         int max_rq_size;
    00105         int time_jump;
    00106         uint32_t ts_jump;
    00107         queue_t rq;
    00108         queue_t tev_rq;
    00109         mblk_t *cached_mp;
    00110         int loc_port;
    00111 #ifdef ORTP_INET6
    00112         struct sockaddr_storage rem_addr;
    00113 #else
    00114         struct sockaddr_in rem_addr;
    00115 #endif
    00116         int rem_addrlen;
    00117         JitterControl jittctl;
    00118         uint32_t snd_time_offset;/*the scheduler time when the application send its first timestamp*/
    00119         uint32_t snd_ts_offset; /* the first application timestamp sent by the application */
    00120         uint32_t snd_rand_offset;       /* a random number added to the user offset to make the stream timestamp*/
    00121         uint32_t snd_last_ts;   /* the last stream timestamp sended */
    00122         uint32_t rcv_time_offset; /*the scheduler time when the application ask for its first timestamp*/
    00123         uint32_t rcv_ts_offset;  /* the first stream timestamp */
    00124         uint32_t rcv_query_ts_offset;   /* the first user timestamp asked by the application */
    00125         uint32_t rcv_last_ts;   /* the last stream timestamp got by the application */
    00126         uint32_t rcv_last_app_ts; /* the last application timestamp asked by the application */
    00127         uint32_t rcv_last_ret_ts; /* the timestamp of the last sample returned (only for continuous audio)*/
    00128         uint32_t hwrcv_extseq; /* last received on socket extended sequence number */
    00129         uint32_t hwrcv_seq_at_last_SR;
    00130         uint32_t hwrcv_since_last_SR;
    00131         uint32_t last_rcv_SR_ts;     /* NTP timestamp (middle 32 bits) of last received SR */
    00132         struct timeval last_rcv_SR_time;   /* time at which last SR was received  */
    00133         uint16_t snd_seq; /* send sequence number */
    00134         uint32_t last_rtcp_report_snt_r;        /* the time of the last rtcp report sent, in recv timestamp unit */
    00135         uint32_t last_rtcp_report_snt_s;        /* the time of the last rtcp report sent, in send timestamp unit */
    00136         uint32_t rtcp_report_snt_interval; /* the interval in timestamp unit between rtcp report sent */
    00137         uint32_t last_rtcp_packet_count; /*the sender's octet count in the last sent RTCP SR*/
    00138         uint32_t sent_payload_bytes; /*used for RTCP sender reports*/
    00139         unsigned int sent_bytes; /* used for bandwidth estimation */
    00140         struct timeval send_bw_start; /* used for bandwidth estimation */
    00141         unsigned int recv_bytes; /* used for bandwidth estimation */
    00142         struct timeval recv_bw_start; /* used for bandwidth estimation */
    00143         rtp_stats_t stats;
    00144         int recv_errno;
    00145         int send_errno;
    00146         int snd_socket_size;
    00147         int rcv_socket_size;
    00148 }RtpStream;
    00149
    00150 typedef struct _RtcpStream
    00151 {
    00152         ortp_socket_t socket;
    00153         int sockfamily;
    00154         struct _RtpTransport *tr;
    00155
    00156         mblk_t *cached_mp;
    00157 #ifdef ORTP_INET6
    00158         struct sockaddr_storage rem_addr;
    00159 #else
    00160         struct sockaddr_in rem_addr;
    00161 #endif
    00162         int rem_addrlen;
    00163         bool_t enabled; /*tells whether we can send RTCP packets */
    00164 } RtcpStream;
    00165
    00166 typedef struct _RtpSession RtpSession;
    00167
    00168
    00177 struct _RtpSession
    00178 {
    00179         RtpSession *next;       /* next RtpSession, when the session are enqueued by the scheduler */
    00180         int mask_pos;   /* the position in the scheduler mask of RtpSession : do not move this field: it is part of the ABI since the session_set macros use it*/
    00181         struct {
    00182           RtpProfile *profile;
    00183           int pt;
    00184           unsigned int ssrc;
    00185           WaitPoint wp;
    00186           int telephone_events_pt;      /* the payload type used for telephony events */
    00187         } snd,rcv;
    00188         unsigned int inc_ssrc_candidate;
    00189         int inc_same_ssrc_count;
    00190         int hw_recv_pt; /* recv payload type before jitter buffer */
    00191         int recv_buf_size;
    00192         RtpSignalTable on_ssrc_changed;
    00193         RtpSignalTable on_payload_type_changed;
    00194         RtpSignalTable on_telephone_event_packet;
    00195         RtpSignalTable on_telephone_event;
    00196         RtpSignalTable on_timestamp_jump;
    00197         RtpSignalTable on_network_error;
    00198         RtpSignalTable on_rtcp_bye;
    00199         struct _OList *signal_tables;
    00200         struct _OList *eventqs;
    00201         msgb_allocator_t allocator;
    00202         RtpStream rtp;
    00203         RtcpStream rtcp;
    00204         RtpSessionMode mode;
    00205         struct _RtpScheduler *sched;
    00206         uint32_t flags;
    00207         int dscp;
    00208         int multicast_ttl;
    00209         int multicast_loopback;
    00210         void * user_data;
    00211         /* FIXME: Should be a table for all session participants. */
    00212         struct timeval last_recv_time; /* Time of receiving the RTP/RTCP packet. */
    00213         mblk_t *pending;
    00214         /* telephony events extension */
    00215         mblk_t *current_tev;            /* the pending telephony events */
    00216         mblk_t *sd;
    00217         queue_t contributing_sources;
    00218         bool_t symmetric_rtp;
    00219         bool_t permissive; /*use the permissive algorithm*/
    00220         bool_t use_connect; /* use connect() on the socket */
    00221         bool_t ssrc_set;
    00222 };
    00223
    00224
    00225
    00226
    00227 #ifdef __cplusplus
    00228 extern "C"
    00229 {
    00230 #endif
    00231
    00232 /* public API */
    00233 RtpSession *rtp_session_new(int mode);
    00234 void rtp_session_set_scheduling_mode(RtpSession *session, int yesno);
    00235 void rtp_session_set_blocking_mode(RtpSession *session, int yesno);
    00236 void rtp_session_set_profile(RtpSession *session, RtpProfile *profile);
    00237 void rtp_session_set_send_profile(RtpSession *session,RtpProfile *profile);
    00238 void rtp_session_set_recv_profile(RtpSession *session,RtpProfile *profile);
    00239 RtpProfile *rtp_session_get_profile(RtpSession *session);
    00240 RtpProfile *rtp_session_get_send_profile(RtpSession *session);
    00241 RtpProfile *rtp_session_get_recv_profile(RtpSession *session);
    00242 int rtp_session_signal_connect(RtpSession *session,const char *signal_name, RtpCallback cb, unsigned long user_data);
    00243 int rtp_session_signal_disconnect_by_callback(RtpSession *session,const char *signal_name, RtpCallback cb);
    00244 void rtp_session_set_ssrc(RtpSession *session, uint32_t ssrc);
    00245 void rtp_session_set_seq_number(RtpSession *session, uint16_t seq);
    00246 uint16_t rtp_session_get_seq_number(RtpSession *session);
    00247
    00248 void rtp_session_enable_jitter_buffer(RtpSession *session , bool_t enabled);
    00249 bool_t rtp_session_jitter_buffer_enabled(const RtpSession *session);
    00250 void rtp_session_set_jitter_buffer_params(RtpSession *session, const JBParameters *par);
    00251 void rtp_session_get_jitter_buffer_params(RtpSession *session, JBParameters *par);
    00252
    00253 /*deprecated jitter control functions*/
    00254 void rtp_session_set_jitter_compensation(RtpSession *session, int milisec);
    00255 void rtp_session_enable_adaptive_jitter_compensation(RtpSession *session, bool_t val);
    00256 bool_t rtp_session_adaptive_jitter_compensation_enabled(RtpSession *session);
    00257
    00258 void rtp_session_set_time_jump_limit(RtpSession *session, int miliseconds);
    00259 int rtp_session_set_local_addr(RtpSession *session,const char *addr, int port);
    00260 int rtp_session_get_local_port(const RtpSession *session);
    00261
    00262 int
    00263 rtp_session_set_remote_addr_full (RtpSession * session, const char * addr, int rtp_port, int rtcp_port);
    00264 /*same as previous function, old name:*/
    00265 int rtp_session_set_remote_addr_and_port (RtpSession * session, const char * addr, int rtp_port, int rtcp_port);
    00266 int rtp_session_set_remote_addr(RtpSession *session,const char *addr, int port);
    00267 /* alternatively to the set_remote_addr() and set_local_addr(), an application can give
    00268 a valid socket (potentially connect()ed )to be used by the RtpSession */
    00269 void rtp_session_set_sockets(RtpSession *session, int rtpfd, int rtcpfd);
    00270 void rtp_session_set_transports(RtpSession *session, RtpTransport *rtptr, RtpTransport *rtcptr);
    00271
    00272 /*those methods are provided for people who wants to send non-RTP messages using the RTP/RTCP sockets */
    00273 ortp_socket_t rtp_session_get_rtp_socket(const RtpSession *session);
    00274 ortp_socket_t rtp_session_get_rtcp_socket(const RtpSession *session);
    00275
    00276
    00277 /* QOS / DSCP */
    00278 int rtp_session_set_dscp(RtpSession *session, int dscp);
    00279 int rtp_session_get_dscp(const RtpSession *session);
    00280
    00281
    00282 /* Multicast methods */
    00283 int rtp_session_set_multicast_ttl(RtpSession *session, int ttl);
    00284 int rtp_session_get_multicast_ttl(RtpSession *session);
    00285
    00286 int rtp_session_set_multicast_loopback(RtpSession *session, int yesno);
    00287 int rtp_session_get_multicast_loopback(RtpSession *session);
    00288
    00289
    00290
    00291 int rtp_session_set_send_payload_type(RtpSession *session, int paytype);
    00292 int rtp_session_get_send_payload_type(const RtpSession *session);
    00293
    00294 int rtp_session_get_recv_payload_type(const RtpSession *session);
    00295 int rtp_session_set_recv_payload_type(RtpSession *session, int pt);
    00296
    00297 int rtp_session_set_payload_type(RtpSession *session, int pt);
    00298
    00299 void rtp_session_set_symmetric_rtp (RtpSession * session, bool_t yesno);
    00300
    00301 void rtp_session_set_connected_mode(RtpSession *session, bool_t yesno);
    00302
    00303 void rtp_session_enable_rtcp(RtpSession *session, bool_t yesno);
    00304
    00305 /*low level recv and send functions */
    00306 mblk_t * rtp_session_recvm_with_ts (RtpSession * session, uint32_t user_ts);
    00307 mblk_t * rtp_session_create_packet(RtpSession *session,int header_size, const uint8_t *payload, int payload_size);
    00308 mblk_t * rtp_session_create_packet_with_data(RtpSession *session, uint8_t *payload, int payload_size, void (*freefn)(void*));
    00309 mblk_t * rtp_session_create_packet_in_place(RtpSession *session,uint8_t *buffer, int size, void (*freefn)(void*) );
    00310 int rtp_session_sendm_with_ts (RtpSession * session, mblk_t *mp, uint32_t userts);
    00311 /* high level recv and send functions */
    00312 int rtp_session_recv_with_ts(RtpSession *session, uint8_t *buffer, int len, uint32_t ts, int *have_more);
    00313 int rtp_session_send_with_ts(RtpSession *session, const uint8_t *buffer, int len, uint32_t userts);
    00314
    00315 /* event API*/
    00316 void rtp_session_register_event_queue(RtpSession *session, OrtpEvQueue *q);
    00317 void rtp_session_unregister_event_queue(RtpSession *session, OrtpEvQueue *q);
    00318
    00319
    00320 /* IP bandwidth usage estimation functions, returning bits/s*/
    00321 float rtp_session_compute_send_bandwidth(RtpSession *session);
    00322 float rtp_session_compute_recv_bandwidth(RtpSession *session);
    00323
    00324 void rtp_session_send_rtcp_APP(RtpSession *session, uint8_t subtype, const char *name, const uint8_t *data, int datalen);
    00325
    00326 uint32_t rtp_session_get_current_send_ts(RtpSession *session);
    00327 uint32_t rtp_session_get_current_recv_ts(RtpSession *session);
    00328 void rtp_session_flush_sockets(RtpSession *session);
    00329 void rtp_session_release_sockets(RtpSession *session);
    00330 void rtp_session_resync(RtpSession *session);
    00331 void rtp_session_reset(RtpSession *session);
    00332 void rtp_session_destroy(RtpSession *session);
    00333
    00334 const rtp_stats_t * rtp_session_get_stats(const RtpSession *session);
    00335 void rtp_session_reset_stats(RtpSession *session);
    00336
    00337 void rtp_session_set_data(RtpSession *session, void *data);
    00338 void *rtp_session_get_data(const RtpSession *session);
    00339
    00340 void rtp_session_set_recv_buf_size(RtpSession *session, int bufsize);
    00341 void rtp_session_set_rtp_socket_send_buffer_size(RtpSession * session, unsigned int size);
    00342 void rtp_session_set_rtp_socket_recv_buffer_size(RtpSession * session, unsigned int size);
    00343
    00344 /* in use with the scheduler to convert a timestamp in scheduler time unit (ms) */
    00345 uint32_t rtp_session_ts_to_time(RtpSession *session,uint32_t timestamp);
    00346 uint32_t rtp_session_time_to_ts(RtpSession *session, int millisecs);
    00347 /* this function aims at simulating senders with "imprecise" clocks, resulting in
    00348 rtp packets sent with timestamp uncorrelated with the system clock .
    00349 This is only availlable to sessions working with the oRTP scheduler */
    00350 void rtp_session_make_time_distorsion(RtpSession *session, int milisec);
    00351
    00352 /*RTCP functions */
    00353 void rtp_session_set_source_description(RtpSession *session, const char *cname,
    00354         const char *name, const char *email, const char *phone,
    00355     const char *loc, const char *tool, const char *note);
    00356 void rtp_session_add_contributing_source(RtpSession *session, uint32_t csrc,
    00357     const char *cname, const char *name, const char *email, const char *phone,
    00358     const char *loc, const char *tool, const char *note);
    00359 void rtp_session_remove_contributing_sources(RtpSession *session, uint32_t csrc);
    00360 mblk_t* rtp_session_create_rtcp_sdes_packet(RtpSession *session);
    00361
    00362 void rtp_session_get_last_recv_time(RtpSession *session, struct timeval *tv);
    00363 int rtp_session_bye(RtpSession *session, const char *reason);
    00364
    00365 int rtp_session_get_last_send_error_code(RtpSession *session);
    00366 void rtp_session_clear_send_error_code(RtpSession *session);
    00367 int rtp_session_get_last_recv_error_code(RtpSession *session);
    00368 void rtp_session_clear_recv_error_code(RtpSession *session);
    00369
    00370 /*private */
    00371 void rtp_session_init(RtpSession *session, int mode);
    00372 #define rtp_session_set_flag(session,flag) (session)->flags|=(flag)
    00373 #define rtp_session_unset_flag(session,flag) (session)->flags&=~(flag)
    00374 void rtp_session_uninit(RtpSession *session);
    00375
    00376 #ifdef __cplusplus
    00377 }
    00378 #endif
    00379
    00380 #endif