oRTP  0.20.0
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         void  (*t_close)(struct _RtpTransport *transport, void *userData);
00096 }  RtpTransport;
00097 
00098 typedef struct _OrtpNetworkSimulatorParams{
00099         int enabled;
00100         float max_bandwidth; /*IP bandwidth, in bit/s*/
00101         float loss_rate;
00102 }OrtpNetworkSimulatorParams;
00103 
00104 typedef struct _OrtpNetworkSimulatorCtx{
00105         OrtpNetworkSimulatorParams params;
00106         int bit_budget;
00107         int qsize;
00108         queue_t q;
00109         struct timeval last_check;
00110 }OrtpNetworkSimulatorCtx;
00111 
00112 typedef struct _RtpStream
00113 {
00114         ortp_socket_t socket;
00115         struct _RtpTransport *tr; 
00116         int sockfamily;
00117         int max_rq_size;
00118         int time_jump;
00119         uint32_t ts_jump;
00120         queue_t rq;
00121         queue_t tev_rq;
00122         mblk_t *cached_mp;
00123         int loc_port;
00124 #ifdef ORTP_INET6
00125         struct sockaddr_storage rem_addr;
00126 #else
00127         struct sockaddr_in rem_addr;
00128 #endif
00129         int rem_addrlen;
00130         void *QoSHandle;
00131         unsigned long QoSFlowID;
00132         JitterControl jittctl;
00133         uint32_t snd_time_offset;/*the scheduler time when the application send its first timestamp*/   
00134         uint32_t snd_ts_offset; /* the first application timestamp sent by the application */
00135         uint32_t snd_rand_offset;       /* a random number added to the user offset to make the stream timestamp*/
00136         uint32_t snd_last_ts;   /* the last stream timestamp sended */
00137         uint32_t rcv_time_offset; /*the scheduler time when the application ask for its first timestamp*/
00138         uint32_t rcv_ts_offset;  /* the first stream timestamp */
00139         uint32_t rcv_query_ts_offset;   /* the first user timestamp asked by the application */
00140         uint32_t rcv_last_ts;   /* the last stream timestamp got by the application */
00141         uint32_t rcv_last_app_ts; /* the last application timestamp asked by the application */ 
00142         uint32_t rcv_last_ret_ts; /* the timestamp of the last sample returned (only for continuous audio)*/
00143         uint32_t hwrcv_extseq; /* last received on socket extended sequence number */
00144         uint32_t hwrcv_seq_at_last_SR;
00145         uint32_t hwrcv_since_last_SR;
00146         uint32_t last_rcv_SR_ts;     /* NTP timestamp (middle 32 bits) of last received SR */
00147         struct timeval last_rcv_SR_time;   /* time at which last SR was received  */
00148         uint16_t snd_seq; /* send sequence number */
00149         uint32_t last_rtcp_packet_count; /*the sender's octet count in the last sent RTCP SR*/
00150         uint32_t sent_payload_bytes; /*used for RTCP sender reports*/
00151         unsigned int sent_bytes; /* used for bandwidth estimation */
00152         struct timeval send_bw_start; /* used for bandwidth estimation */
00153         unsigned int recv_bytes; /* used for bandwidth estimation */
00154         struct timeval recv_bw_start; /* used for bandwidth estimation */
00155         rtp_stats_t stats;
00156         int recv_errno;
00157         int send_errno;
00158         int snd_socket_size;
00159         int rcv_socket_size;
00160         int ssrc_changed_thres;
00161         jitter_stats_t jitter_stats;
00162 }RtpStream;
00163 
00164 typedef struct _RtcpStream
00165 {
00166         ortp_socket_t socket;
00167         int sockfamily;
00168         struct _RtpTransport *tr; 
00169         mblk_t *cached_mp;
00170 #ifdef ORTP_INET6
00171         struct sockaddr_storage rem_addr;
00172 #else
00173         struct sockaddr_in rem_addr;
00174 #endif
00175         int rem_addrlen;
00176         int interval;
00177         uint32_t last_rtcp_report_snt_r;        /* the time of the last rtcp report sent, in recv timestamp unit */
00178         uint32_t last_rtcp_report_snt_s;        /* the time of the last rtcp report sent, in send timestamp unit */
00179         uint32_t rtcp_report_snt_interval_r; /* the interval in timestamp unit for receive path between rtcp report sent */
00180         uint32_t rtcp_report_snt_interval_s; /* the interval in timestamp unit for send path between rtcp report sent */
00181         bool_t enabled; /*tells whether we can send RTCP packets */
00182 } RtcpStream;
00183 
00184 typedef struct _RtpSession RtpSession;
00185 
00186 
00195 struct _RtpSession
00196 {
00197         RtpSession *next;       /* next RtpSession, when the session are enqueued by the scheduler */
00198         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*/
00199         struct {
00200                 RtpProfile *profile;
00201                 int pt;
00202                 unsigned int ssrc;
00203                 WaitPoint wp;
00204                 int telephone_events_pt;        /* the payload type used for telephony events */
00205         } snd,rcv;
00206         unsigned int inc_ssrc_candidate;
00207         int inc_same_ssrc_count;
00208         int hw_recv_pt; /* recv payload type before jitter buffer */
00209         int recv_buf_size;
00210         RtpSignalTable on_ssrc_changed;
00211         RtpSignalTable on_payload_type_changed;
00212         RtpSignalTable on_telephone_event_packet;
00213         RtpSignalTable on_telephone_event;
00214         RtpSignalTable on_timestamp_jump;
00215         RtpSignalTable on_network_error;
00216         RtpSignalTable on_rtcp_bye;
00217         struct _OList *signal_tables;
00218         struct _OList *eventqs;
00219         msgb_allocator_t allocator;
00220         RtpStream rtp;
00221         RtcpStream rtcp;
00222         RtpSessionMode mode;
00223         struct _RtpScheduler *sched;
00224         uint32_t flags;
00225         int dscp;
00226         int multicast_ttl;
00227         int multicast_loopback;
00228         void * user_data;
00229         /* FIXME: Should be a table for all session participants. */
00230         struct timeval last_recv_time; /* Time of receiving the RTP/RTCP packet. */
00231         mblk_t *pending;
00232         /* telephony events extension */
00233         mblk_t *current_tev;            /* the pending telephony events */
00234         mblk_t *sd;
00235         queue_t contributing_sources;
00236         unsigned int lost_packets_test_vector;
00237         unsigned int interarrival_jitter_test_vector;
00238         unsigned int delay_test_vector;
00239         float rtt;/*last round trip delay calculated*/
00240         OrtpNetworkSimulatorCtx *net_sim_ctx;
00241         bool_t symmetric_rtp;
00242         bool_t permissive; /*use the permissive algorithm*/
00243         bool_t use_connect; /* use connect() on the socket */
00244         bool_t ssrc_set;
00245 };
00246         
00247 
00248 
00249 
00250 #ifdef __cplusplus
00251 extern "C"
00252 {
00253 #endif
00254 
00255 /* public API */
00256 RtpSession *rtp_session_new(int mode);
00257 void rtp_session_set_scheduling_mode(RtpSession *session, int yesno);
00258 void rtp_session_set_blocking_mode(RtpSession *session, int yesno);
00259 void rtp_session_set_profile(RtpSession *session, RtpProfile *profile);
00260 void rtp_session_set_send_profile(RtpSession *session,RtpProfile *profile);
00261 void rtp_session_set_recv_profile(RtpSession *session,RtpProfile *profile);
00262 RtpProfile *rtp_session_get_profile(RtpSession *session);
00263 RtpProfile *rtp_session_get_send_profile(RtpSession *session);
00264 RtpProfile *rtp_session_get_recv_profile(RtpSession *session);
00265 int rtp_session_signal_connect(RtpSession *session,const char *signal_name, RtpCallback cb, unsigned long user_data);
00266 int rtp_session_signal_disconnect_by_callback(RtpSession *session,const char *signal_name, RtpCallback cb);
00267 void rtp_session_set_ssrc(RtpSession *session, uint32_t ssrc);
00268 uint32_t rtp_session_get_send_ssrc(RtpSession* session);
00269 void rtp_session_set_seq_number(RtpSession *session, uint16_t seq);
00270 uint16_t rtp_session_get_seq_number(RtpSession *session);
00271 
00272 void rtp_session_enable_jitter_buffer(RtpSession *session , bool_t enabled);
00273 bool_t rtp_session_jitter_buffer_enabled(const RtpSession *session);
00274 void rtp_session_set_jitter_buffer_params(RtpSession *session, const JBParameters *par);
00275 void rtp_session_get_jitter_buffer_params(RtpSession *session, JBParameters *par);
00276 
00277 /*deprecated jitter control functions*/
00278 void rtp_session_set_jitter_compensation(RtpSession *session, int milisec);
00279 void rtp_session_enable_adaptive_jitter_compensation(RtpSession *session, bool_t val);
00280 bool_t rtp_session_adaptive_jitter_compensation_enabled(RtpSession *session);
00281 
00282 void rtp_session_set_time_jump_limit(RtpSession *session, int miliseconds);
00283 int rtp_session_set_local_addr(RtpSession *session,const char *addr, int port);
00284 int rtp_session_get_local_port(const RtpSession *session);
00285 
00286 int
00287 rtp_session_set_remote_addr_full (RtpSession * session, const char * addr, int rtp_port, int rtcp_port);
00288 /*same as previous function, old name:*/
00289 int rtp_session_set_remote_addr_and_port (RtpSession * session, const char * addr, int rtp_port, int rtcp_port);
00290 int rtp_session_set_remote_addr(RtpSession *session,const char *addr, int port);
00291 /* alternatively to the set_remote_addr() and set_local_addr(), an application can give
00292 a valid socket (potentially connect()ed )to be used by the RtpSession */
00293 void rtp_session_set_sockets(RtpSession *session, int rtpfd, int rtcpfd);
00294 void rtp_session_set_transports(RtpSession *session, RtpTransport *rtptr, RtpTransport *rtcptr);
00295 
00296 /*those methods are provided for people who wants to send non-RTP messages using the RTP/RTCP sockets */
00297 ortp_socket_t rtp_session_get_rtp_socket(const RtpSession *session);
00298 ortp_socket_t rtp_session_get_rtcp_socket(const RtpSession *session);
00299 
00300 
00301 /* QOS / DSCP */
00302 int rtp_session_set_dscp(RtpSession *session, int dscp);
00303 int rtp_session_get_dscp(const RtpSession *session);
00304 
00305 
00306 /* Multicast methods */
00307 int rtp_session_set_multicast_ttl(RtpSession *session, int ttl);
00308 int rtp_session_get_multicast_ttl(RtpSession *session);
00309 
00310 int rtp_session_set_multicast_loopback(RtpSession *session, int yesno);
00311 int rtp_session_get_multicast_loopback(RtpSession *session);
00312 
00313 
00314 
00315 int rtp_session_set_send_payload_type(RtpSession *session, int paytype);
00316 int rtp_session_get_send_payload_type(const RtpSession *session);
00317 
00318 int rtp_session_get_recv_payload_type(const RtpSession *session);
00319 int rtp_session_set_recv_payload_type(RtpSession *session, int pt);
00320 
00321 int rtp_session_set_payload_type(RtpSession *session, int pt);
00322 
00323 void rtp_session_set_symmetric_rtp (RtpSession * session, bool_t yesno);
00324 
00325 void rtp_session_set_connected_mode(RtpSession *session, bool_t yesno);
00326 
00327 void rtp_session_enable_rtcp(RtpSession *session, bool_t yesno);
00328 
00329 void rtp_session_set_rtcp_report_interval(RtpSession *session, int value_ms);
00330 
00331 void rtp_session_set_ssrc_changed_threshold(RtpSession *session, int numpackets);
00332 
00333 /*low level recv and send functions */
00334 mblk_t * rtp_session_recvm_with_ts (RtpSession * session, uint32_t user_ts);
00335 mblk_t * rtp_session_create_packet(RtpSession *session,int header_size, const uint8_t *payload, int payload_size);
00336 mblk_t * rtp_session_create_packet_with_data(RtpSession *session, uint8_t *payload, int payload_size, void (*freefn)(void*));
00337 mblk_t * rtp_session_create_packet_in_place(RtpSession *session,uint8_t *buffer, int size, void (*freefn)(void*) );
00338 int rtp_session_sendm_with_ts (RtpSession * session, mblk_t *mp, uint32_t userts);
00339 /* high level recv and send functions */
00340 int rtp_session_recv_with_ts(RtpSession *session, uint8_t *buffer, int len, uint32_t ts, int *have_more);
00341 int rtp_session_send_with_ts(RtpSession *session, const uint8_t *buffer, int len, uint32_t userts);
00342 
00343 /* event API*/
00344 void rtp_session_register_event_queue(RtpSession *session, OrtpEvQueue *q);
00345 void rtp_session_unregister_event_queue(RtpSession *session, OrtpEvQueue *q);
00346 
00347 
00348 /* IP bandwidth usage estimation functions, returning bits/s*/
00349 float rtp_session_compute_send_bandwidth(RtpSession *session);
00350 float rtp_session_compute_recv_bandwidth(RtpSession *session);
00351 
00352 void rtp_session_send_rtcp_APP(RtpSession *session, uint8_t subtype, const char *name, const uint8_t *data, int datalen);
00353 
00354 uint32_t rtp_session_get_current_send_ts(RtpSession *session);
00355 uint32_t rtp_session_get_current_recv_ts(RtpSession *session);
00356 void rtp_session_flush_sockets(RtpSession *session);
00357 void rtp_session_release_sockets(RtpSession *session);
00358 void rtp_session_resync(RtpSession *session);
00359 void rtp_session_reset(RtpSession *session);
00360 void rtp_session_destroy(RtpSession *session);
00361 
00362 const rtp_stats_t * rtp_session_get_stats(const RtpSession *session);
00363 const jitter_stats_t * rtp_session_get_jitter_stats( const RtpSession *session );
00364 void rtp_session_reset_stats(RtpSession *session);
00365 
00366 void rtp_session_set_data(RtpSession *session, void *data);
00367 void *rtp_session_get_data(const RtpSession *session);
00368 
00369 void rtp_session_set_recv_buf_size(RtpSession *session, int bufsize);
00370 void rtp_session_set_rtp_socket_send_buffer_size(RtpSession * session, unsigned int size);
00371 void rtp_session_set_rtp_socket_recv_buffer_size(RtpSession * session, unsigned int size);
00372 
00373 /* in use with the scheduler to convert a timestamp in scheduler time unit (ms) */
00374 uint32_t rtp_session_ts_to_time(RtpSession *session,uint32_t timestamp);
00375 uint32_t rtp_session_time_to_ts(RtpSession *session, int millisecs);
00376 /* this function aims at simulating senders with "imprecise" clocks, resulting in 
00377 rtp packets sent with timestamp uncorrelated with the system clock .
00378 This is only availlable to sessions working with the oRTP scheduler */
00379 void rtp_session_make_time_distorsion(RtpSession *session, int milisec);
00380 
00381 /*RTCP functions */
00382 void rtp_session_set_source_description(RtpSession *session, const char *cname,
00383         const char *name, const char *email, const char *phone, 
00384     const char *loc, const char *tool, const char *note);
00385 void rtp_session_add_contributing_source(RtpSession *session, uint32_t csrc, 
00386     const char *cname, const char *name, const char *email, const char *phone, 
00387     const char *loc, const char *tool, const char *note);
00388 void rtp_session_remove_contributing_sources(RtpSession *session, uint32_t csrc);
00389 mblk_t* rtp_session_create_rtcp_sdes_packet(RtpSession *session);
00390 
00391 void rtp_session_get_last_recv_time(RtpSession *session, struct timeval *tv);
00392 int rtp_session_bye(RtpSession *session, const char *reason);
00393 
00394 int rtp_session_get_last_send_error_code(RtpSession *session);
00395 void rtp_session_clear_send_error_code(RtpSession *session);
00396 int rtp_session_get_last_recv_error_code(RtpSession *session);
00397 void rtp_session_clear_recv_error_code(RtpSession *session);
00398 
00399 
00400 float rtp_session_get_round_trip_propagation(RtpSession *session);
00401 
00402 
00403 void rtp_session_enable_network_simulation(RtpSession *session, const OrtpNetworkSimulatorParams *params);
00404 void rtp_session_rtcp_set_lost_packet_value( RtpSession *session, const unsigned int value );
00405 void rtp_session_rtcp_set_jitter_value(RtpSession *session, const unsigned int value );
00406 void rtp_session_rtcp_set_delay_value(RtpSession *session, const unsigned int value );
00407 mblk_t * rtp_session_pick_with_cseq (RtpSession * session, const uint16_t sequence_number);
00408 /*private */
00409 void rtp_session_init(RtpSession *session, int mode);
00410 #define rtp_session_set_flag(session,flag) (session)->flags|=(flag)
00411 #define rtp_session_unset_flag(session,flag) (session)->flags&=~(flag)
00412 void rtp_session_uninit(RtpSession *session);
00413 
00414 #ifdef __cplusplus
00415 }
00416 #endif
00417 
00418 #endif