1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
/* $Id$ */
/*
* Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __PJMEDIA_STREAM_H__
#define __PJMEDIA_STREAM_H__
/**
* @file stream.h
* @brief Media Stream.
*/
#include <pjmedia/sound.h>
#include <pjmedia/codec.h>
#include <pjmedia/endpoint.h>
#include <pjmedia/port.h>
#include <pjmedia/rtcp.h>
#include <pj/sock.h>
PJ_BEGIN_DECL
/**
* @defgroup PJMED_STRM Media Stream
* @ingroup PJMEDIA
* @{
*
* A media stream is a bidirectional multimedia communication between two
* endpoints. It corresponds to a media description (m= line) in SDP.
*
* A media stream consists of two unidirectional channels:
* - encoding channel, which transmits unidirectional media to remote, and
* - decoding channel, which receives unidirectional media from remote.
*
* Application normally does not need to create the stream directly; it
* creates media session instead. The media session will create the media
* streams as necessary, according to the media descriptors that present
* in local and remote SDP.
*/
/**
* Opaque declaration for media channel.
* Media channel is unidirectional flow of media from sender to
* receiver.
*/
typedef struct pjmedia_channel pjmedia_channel;
/**
* This structure describes media stream information. Each media stream
* corresponds to one "m=" line in SDP session descriptor, and it has
* its own RTP/RTCP socket pair.
*/
struct pjmedia_stream_info
{
pjmedia_type type; /**< Media type (audio, video) */
pjmedia_dir dir; /**< Media direction. */
pjmedia_sock_info sock_info; /**< Media transport (RTP/RTCP sockets) */
pj_sockaddr_in rem_addr; /**< Remote RTP address */
pjmedia_codec_info fmt; /**< Incoming codec format info. */
pjmedia_codec_param *param; /**< Optional codec param. */
unsigned tx_pt; /**< Outgoing codec paylaod type. */
int tx_event_pt;/**< Outgoing pt for telephone-events. */
int rx_event_pt;/**< Incoming pt for telephone-events. */
pj_uint32_t ssrc; /**< RTP SSRC. */
int jb_init; /**< Jitter buffer init delay in msec.
(-1 for default). */
int jb_min_pre; /**< Jitter buffer minimum prefetch
delay in msec (-1 for default). */
int jb_max_pre; /**< Jitter buffer maximum prefetch
delay in msec (-1 for default). */
int jb_max; /**< Jitter buffer max delay in msec. */
};
/**
* @see pjmedia_stream_info.
*/
typedef struct pjmedia_stream_info pjmedia_stream_info;
/**
* Opaque declaration for media stream.
*/
typedef struct pjmedia_stream pjmedia_stream;
/**
* Create a media stream based on the specified parameter. After the stream
* has been created, application normally would want to get the media port
* interface of the streams, by calling pjmedia_stream_get_port(). The
* media port interface exports put_frame() and get_frame() function, used
* to transmit and receive media frames from the stream.
*
* Without application calling put_frame() and get_frame(), there will be
* no media frames transmitted or received by the stream.
*
* @param endpt Media endpoint.
* @param pool Pool to allocate memory for the stream. A large
* number of memory may be needed because jitter
* buffer needs to preallocate some storage.
* @param info Stream information.
* @param user_data Arbitrary user data (for future callback feature).
* @param p_stream Pointer to receive the media stream.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_create(pjmedia_endpt *endpt,
pj_pool_t *pool,
const pjmedia_stream_info *info,
void *user_data,
pjmedia_stream **p_stream);
/**
* Destroy the media stream.
*
* @param stream The media stream.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_destroy(pjmedia_stream *stream);
/**
* Get the media port interface of the stream. The media port interface
* declares put_frame() and get_frame() function, which is the only
* way for application to transmit and receive media frames from the
* stream.
*
* @param stream The media stream.
* @param p_port Pointer to receive the port interface.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_get_port(pjmedia_stream *stream,
pjmedia_port **p_port );
/**
* Start the media stream. This will start the appropriate channels
* in the media stream, depending on the media direction that was set
* when the stream was created.
*
* @param stream The media stream.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_start(pjmedia_stream *stream);
/**
* Get the stream statistics.
*
* @param stream The media stream.
* @param stat Media stream statistics.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_get_stat( const pjmedia_stream *stream,
pjmedia_rtcp_stat *stat);
/**
* Pause the individual channel in the stream.
*
* @param stream The media channel.
* @param dir Which direction to pause.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_pause( pjmedia_stream *stream,
pjmedia_dir dir);
/**
* Resume the individual channel in the stream.
*
* @param stream The media channel.
* @param dir Which direction to resume.
*
* @return PJ_SUCCESS on success;
*/
PJ_DECL(pj_status_t) pjmedia_stream_resume(pjmedia_stream *stream,
pjmedia_dir dir);
/**
* Transmit DTMF to this stream. The DTMF will be transmitted uisng
* RTP telephone-events as described in RFC 2833. This operation is
* only valid for audio stream.
*
* @param stream The media stream.
* @param ascii_digit String containing digits to be sent to remote.
* Currently the maximum number of digits are 32.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_stream_dial_dtmf(pjmedia_stream *stream,
const pj_str_t *ascii_digit);
/**
* Check if the stream has incoming DTMF digits in the incoming DTMF
* queue. Incoming DTMF digits received via RFC 2833 mechanism are
* saved in the incoming digits queue.
*
* @param stream The media stream.
*
* @return Non-zero (PJ_TRUE) if the stream has received DTMF
* digits in the .
*/
PJ_DECL(pj_bool_t) pjmedia_stream_check_dtmf(pjmedia_stream *stream);
/**
* Retrieve the incoming DTMF digits from the stream. Note that the digits
* buffer will not be NULL terminated.
*
* @param stream The media stream.
* @param ascii_digits Buffer to receive the digits. The length of this
* buffer is indicated in the "size" argument.
* @param size On input, contains the maximum digits to be copied
* to the buffer.
* On output, it contains the actual digits that has
* been copied to the buffer.
*
* @return Non-zero (PJ_TRUE) if the stream has received DTMF
* digits in the .
*/
PJ_DECL(pj_status_t) pjmedia_stream_get_dtmf( pjmedia_stream *stream,
char *ascii_digits,
unsigned *size);
/**
* @}
*/
PJ_END_DECL
#endif /* __PJMEDIA_STREAM_H__ */
|
