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 } JBParameters;
00060 
00061 typedef struct _JitterControl
00062 {
00063         int jitt_comp;   /* the user jitt_comp in miliseconds*/
00064         int jitt_comp_ts; /* the jitt_comp converted in rtp time (same unit as timestamp) */
00065         int adapt_jitt_comp_ts;
00066         float slide;
00067         float jitter;
00068         int count;
00069         int olddiff;
00070         float inter_jitter;     /* interarrival jitter as defined in the RFC */
00071         int corrective_step;
00072         int corrective_slide;
00073         bool_t adaptive;
00074         bool_t enabled;
00075 } JitterControl;
00076 
00077 typedef struct _WaitPoint
00078 {
00079         ortp_mutex_t lock;
00080         ortp_cond_t  cond;
00081         uint32_t time;
00082         bool_t wakeup;
00083 } WaitPoint;
00084 
00085 typedef struct _RtpTransport
00086 {
00087         void *data;
00088         ortp_socket_t (*t_getsocket)(struct _RtpTransport *t);
00089         int  (*t_sendto)(struct _RtpTransport *t, mblk_t *msg , int flags, const struct sockaddr *to, socklen_t tolen);
00090         int  (*t_recvfrom)(struct _RtpTransport *t, mblk_t *msg, int flags, struct sockaddr *from, socklen_t *fromlen);
00091         struct _RtpSession *session;//<back pointer to the owning session, set by oRTP
00092 }  RtpTransport;
00093 
00094 
00095         
00096 typedef struct _RtpStream
00097 {
00098         ortp_socket_t socket;
00099         struct _RtpTransport *tr; 
00100         int sockfamily;
00101         int max_rq_size;
00102         int time_jump;
00103         uint32_t ts_jump;
00104         queue_t rq;
00105         queue_t tev_rq;
00106         mblk_t *cached_mp;
00107         int loc_port;
00108 #ifdef ORTP_INET6
00109         struct sockaddr_storage rem_addr;
00110 #else
00111         struct sockaddr_in rem_addr;
00112 #endif
00113         int rem_addrlen;
00114         JitterControl jittctl;
00115         uint32_t snd_time_offset;/*the scheduler time when the application send its first timestamp*/   
00116         uint32_t snd_ts_offset; /* the first application timestamp sent by the application */
00117         uint32_t snd_rand_offset;       /* a random number added to the user offset to make the stream timestamp*/
00118         uint32_t snd_last_ts;   /* the last stream timestamp sended */
00119         uint32_t rcv_time_offset; /*the scheduler time when the application ask for its first timestamp*/
00120         uint32_t rcv_ts_offset;  /* the first stream timestamp */
00121         uint32_t rcv_query_ts_offset;   /* the first user timestamp asked by the application */
00122         uint32_t rcv_diff_ts;   /* difference between the first user timestamp and first stream timestamp */
00123         uint32_t hwrcv_diff_ts;
00124         uint32_t rcv_last_ts;   /* the last stream timestamp got by the application */
00125         uint32_t rcv_last_app_ts; /* the last application timestamp asked by the application */ 
00126         uint32_t rcv_last_ret_ts; /* the timestamp of the last sample returned (only for continuous audio)*/
00127         uint32_t hwrcv_extseq; /* last received on socket extended sequence number */
00128         uint32_t hwrcv_seq_at_last_SR;
00129         uint32_t hwrcv_since_last_SR;
00130         uint32_t last_rcv_SR_ts;     /* NTP timestamp (middle 32 bits) of last received SR */
00131         struct timeval last_rcv_SR_time;   /* time at which last SR was received  */
00132         uint16_t snd_seq; /* send sequence number */
00133         uint32_t last_rtcp_report_snt_r;        /* the time of the last rtcp report sent, in recv timestamp unit */
00134         uint32_t last_rtcp_report_snt_s;        /* the time of the last rtcp report sent, in send timestamp unit */
00135         uint32_t rtcp_report_snt_interval; /* the interval in timestamp unit between rtcp report sent */
00136         uint32_t last_rtcp_packet_count; /*the sender's octet count in the last sent RTCP SR*/
00137         unsigned int sent_bytes; /* used for bandwidth estimation */
00138         struct timeval send_bw_start; /* used for bandwidth estimation */
00139         unsigned int recv_bytes; /* used for bandwidth estimation */
00140         struct timeval recv_bw_start; /* used for bandwidth estimation */
00141         rtp_stats_t stats;
00142         int recv_errno;
00143         int send_errno;
00144 }RtpStream;
00145 
00146 typedef struct _RtcpStream
00147 {
00148         ortp_socket_t socket;
00149         int sockfamily;
00150         struct _RtpTransport *tr; 
00151 
00152         mblk_t *cached_mp;
00153 #ifdef ORTP_INET6
00154         struct sockaddr_storage rem_addr;
00155 #else
00156         struct sockaddr_in rem_addr;
00157 #endif
00158         int rem_addrlen;
00159         bool_t enabled; /*tells whether we can send RTCP packets */
00160 } RtcpStream;
00161 
00162 typedef struct _RtpSession RtpSession;
00163 
00164 
00173 struct _RtpSession
00174 {
00175         RtpSession *next;       /* next RtpSession, when the session are enqueued by the scheduler */
00176         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*/
00177         struct {
00178           RtpProfile *profile;
00179           int pt;
00180           int ssrc;
00181           WaitPoint wp;
00182           int telephone_events_pt;      /* the payload type used for telephony events */
00183         } snd,rcv;
00184         int hw_recv_pt; /* recv payload type before jitter buffer */
00185         int recv_buf_size;
00186         RtpSignalTable on_ssrc_changed;
00187         RtpSignalTable on_payload_type_changed;
00188         RtpSignalTable on_telephone_event_packet;
00189         RtpSignalTable on_telephone_event;
00190         RtpSignalTable on_timestamp_jump;
00191         RtpSignalTable on_network_error;
00192         RtpSignalTable on_rtcp_bye;
00193         struct _OList *signal_tables;
00194         struct _OList *eventqs;
00195         RtpStream rtp;
00196         RtcpStream rtcp;
00197         RtpSessionMode mode;
00198         struct _RtpScheduler *sched;
00199         uint32_t flags;
00200         int dscp;
00201         int multicast_ttl;
00202         int multicast_loopback;
00203         void * user_data;
00204         /* FIXME: Should be a table for all session participants. */
00205         struct timeval last_recv_time; /* Time of receiving the RTP/RTCP packet. */
00206 
00207         /* telephony events extension */
00208         mblk_t *current_tev;            /* the pending telephony events */
00209         mblk_t *sd;
00210         queue_t contributing_sources;
00211         bool_t symmetric_rtp;
00212         bool_t permissive; /*use the permissive algorithm*/
00213         bool_t use_connect; /* use connect() on the socket */
00214 };
00215         
00216 
00217 
00218 
00219 #ifdef __cplusplus
00220 extern "C"
00221 {
00222 #endif
00223 
00224 /* public API */
00225 RtpSession *rtp_session_new(int mode);
00226 void rtp_session_set_scheduling_mode(RtpSession *session, int yesno);
00227 void rtp_session_set_blocking_mode(RtpSession *session, int yesno);
00228 void rtp_session_set_profile(RtpSession *session, RtpProfile *profile);
00229 void rtp_session_set_send_profile(RtpSession *session,RtpProfile *profile);
00230 void rtp_session_set_recv_profile(RtpSession *session,RtpProfile *profile);
00231 RtpProfile *rtp_session_get_profile(RtpSession *session);
00232 RtpProfile *rtp_session_get_send_profile(RtpSession *session);
00233 RtpProfile *rtp_session_get_recv_profile(RtpSession *session);
00234 int rtp_session_signal_connect(RtpSession *session,const char *signal_name, RtpCallback cb, unsigned long user_data);
00235 int rtp_session_signal_disconnect_by_callback(RtpSession *session,const char *signal_name, RtpCallback cb);
00236 void rtp_session_set_ssrc(RtpSession *session, uint32_t ssrc);
00237 void rtp_session_set_seq_number(RtpSession *session, uint16_t seq);
00238 uint16_t rtp_session_get_seq_number(RtpSession *session);
00239 
00240 void rtp_session_enable_jitter_buffer(RtpSession *session , bool_t enabled);
00241 bool_t rtp_session_jitter_buffer_enabled(const RtpSession *session);
00242 void rtp_session_set_jitter_buffer_params(RtpSession *session, const JBParameters *par);
00243 void rtp_session_get_jitter_buffer_params(RtpSession *session, JBParameters *par);
00244 
00245 /*deprecated jitter control functions*/
00246 void rtp_session_set_jitter_compensation(RtpSession *session, int milisec);
00247 void rtp_session_enable_adaptive_jitter_compensation(RtpSession *session, bool_t val);
00248 bool_t rtp_session_adaptive_jitter_compensation_enabled(RtpSession *session);
00249 
00250 void rtp_session_set_time_jump_limit(RtpSession *session, int miliseconds);
00251 int rtp_session_set_local_addr(RtpSession *session,const char *addr, int port);
00252 int rtp_session_get_local_port(const RtpSession *session);
00253 int rtp_session_set_remote_addr(RtpSession *session,const char *addr, int port);
00254 /* alternatively to the set_remote_addr() and set_local_addr(), an application can give
00255 a valid socket (potentially connect()ed )to be used by the RtpSession */
00256 void rtp_session_set_sockets(RtpSession *session, int rtpfd, int rtcpfd);
00257 void rtp_session_set_transports(RtpSession *session, RtpTransport *rtptr, RtpTransport *rtcptr);
00258 
00259 /*those methods are provided for people who wants to send non-RTP messages using the RTP/RTCP sockets */
00260 ortp_socket_t rtp_session_get_rtp_socket(const RtpSession *session);
00261 ortp_socket_t rtp_session_get_rtcp_socket(const RtpSession *session);
00262 
00263 
00264 /* QOS / DSCP */
00265 int rtp_session_set_dscp(RtpSession *session, int dscp);
00266 int rtp_session_get_dscp(const RtpSession *session);
00267 
00268 
00269 /* Multicast methods */
00270 int rtp_session_set_multicast_ttl(RtpSession *session, int ttl);
00271 int rtp_session_get_multicast_ttl(RtpSession *session);
00272 
00273 int rtp_session_set_multicast_loopback(RtpSession *session, int yesno);
00274 int rtp_session_get_multicast_loopback(RtpSession *session);
00275 
00276 
00277 
00278 int rtp_session_set_send_payload_type(RtpSession *session, int paytype);
00279 int rtp_session_get_send_payload_type(const RtpSession *session);
00280 
00281 int rtp_session_get_recv_payload_type(const RtpSession *session);
00282 int rtp_session_set_recv_payload_type(RtpSession *session, int pt);
00283 
00284 int rtp_session_set_payload_type(RtpSession *session, int pt);
00285 
00286 void rtp_session_set_symmetric_rtp (RtpSession * session, bool_t yesno);
00287 
00288 void rtp_session_set_connected_mode(RtpSession *session, bool_t yesno);
00289 
00290 void rtp_session_enable_rtcp(RtpSession *session, bool_t yesno);
00291 
00292 /*low level recv and send functions */
00293 mblk_t * rtp_session_recvm_with_ts (RtpSession * session, uint32_t user_ts);
00294 mblk_t * rtp_session_create_packet(RtpSession *session,int header_size, const uint8_t *payload, int payload_size);
00295 mblk_t * rtp_session_create_packet_with_data(RtpSession *session, uint8_t *payload, int payload_size, void (*freefn)(void*));
00296 mblk_t * rtp_session_create_packet_in_place(RtpSession *session,uint8_t *buffer, int size, void (*freefn)(void*) );
00297 int rtp_session_sendm_with_ts (RtpSession * session, mblk_t *mp, uint32_t userts);
00298 /* high level recv and send functions */
00299 int rtp_session_recv_with_ts(RtpSession *session, uint8_t *buffer, int len, uint32_t ts, int *have_more);
00300 int rtp_session_send_with_ts(RtpSession *session, const uint8_t *buffer, int len, uint32_t userts);
00301 
00302 /* event API*/
00303 void rtp_session_register_event_queue(RtpSession *session, OrtpEvQueue *q);
00304 void rtp_session_unregister_event_queue(RtpSession *session, OrtpEvQueue *q);
00305 
00306 
00307 /* IP bandwidth usage estimation functions, returning bits/s*/
00308 float rtp_session_compute_send_bandwidth(RtpSession *session);
00309 float rtp_session_compute_recv_bandwidth(RtpSession *session);
00310 
00311 void rtp_session_send_rtcp_APP(RtpSession *session, uint8_t subtype, const char *name, const uint8_t *data, int datalen);
00312 
00313 uint32_t rtp_session_get_current_send_ts(RtpSession *session);
00314 uint32_t rtp_session_get_current_recv_ts(RtpSession *session);
00315 void rtp_session_flush_sockets(RtpSession *session);
00316 void rtp_session_release_sockets(RtpSession *session);
00317 void rtp_session_resync(RtpSession *session);
00318 void rtp_session_reset(RtpSession *session);
00319 void rtp_session_destroy(RtpSession *session);
00320 
00321 const rtp_stats_t * rtp_session_get_stats(const RtpSession *session);
00322 void rtp_session_reset_stats(RtpSession *session);
00323 
00324 void rtp_session_set_data(RtpSession *session, void *data);
00325 void *rtp_session_get_data(const RtpSession *session);
00326 
00327 void rtp_session_set_recv_buf_size(RtpSession *session, int bufsize);
00328 
00329 /* in use with the scheduler to convert a timestamp in scheduler time unit (ms) */
00330 uint32_t rtp_session_ts_to_time(RtpSession *session,uint32_t timestamp);
00331 uint32_t rtp_session_time_to_ts(RtpSession *session, int millisecs);
00332 /* this function aims at simulating senders with "imprecise" clocks, resulting in 
00333 rtp packets sent with timestamp uncorrelated with the system clock .
00334 This is only availlable to sessions working with the oRTP scheduler */
00335 void rtp_session_make_time_distorsion(RtpSession *session, int milisec);
00336 
00337 /*RTCP functions */
00338 void rtp_session_set_source_description(RtpSession *session, const char *cname,
00339         const char *name, const char *email, const char *phone, 
00340     const char *loc, const char *tool, const char *note);
00341 void rtp_session_add_contributing_source(RtpSession *session, uint32_t csrc, 
00342     const char *cname, const char *name, const char *email, const char *phone, 
00343     const char *loc, const char *tool, const char *note);
00344 void rtp_session_remove_contributing_sources(RtpSession *session, uint32_t csrc);
00345 mblk_t* rtp_session_create_rtcp_sdes_packet(RtpSession *session);
00346 
00347 void rtp_session_get_last_recv_time(RtpSession *session, struct timeval *tv);
00348 int rtp_session_bye(RtpSession *session, const char *reason);
00349 
00350 int rtp_session_get_last_send_error_code(RtpSession *session);
00351 void rtp_session_clear_send_error_code(RtpSession *session);
00352 int rtp_session_get_last_recv_error_code(RtpSession *session);
00353 void rtp_session_clear_recv_error_code(RtpSession *session);
00354 
00355 /*private */
00356 void rtp_session_init(RtpSession *session, int mode);
00357 #define rtp_session_set_flag(session,flag) (session)->flags|=(flag)
00358 #define rtp_session_unset_flag(session,flag) (session)->flags&=~(flag)
00359 void rtp_session_uninit(RtpSession *session);
00360 
00361 #ifdef __cplusplus
00362 }
00363 #endif
00364 
00365 #endif

Generated on Sat Dec 15 01:40:24 2007 for oRTP by  doxygen 1.5.4