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