From 53f8afbdb2854e3c89b510e259fff83f6f3da3da Mon Sep 17 00:00:00 2001 From: Aaro Altonen Date: Tue, 23 Feb 2021 14:19:32 +0200 Subject: [PATCH] Document push_frame() --- docs/examples/rawvideo.cc | 36 --- .../classuvgrtp_1_1media__stream-members.html | 6 +- docs/html/classuvgrtp_1_1media__stream.html | 235 ++++++++++++++++-- docs/html/index.html | 2 +- docs/html/media__stream_8hh_source.html | 194 ++++++++------- docs/html/search/all_5.js | 2 +- docs/html/search/functions_4.js | 2 +- docs/html/util_8hh.html | 4 +- include/media_stream.hh | 121 +++++++-- 9 files changed, 431 insertions(+), 171 deletions(-) delete mode 100644 docs/examples/rawvideo.cc diff --git a/docs/examples/rawvideo.cc b/docs/examples/rawvideo.cc deleted file mode 100644 index 94f0219..0000000 --- a/docs/examples/rawvideo.cc +++ /dev/null @@ -1,36 +0,0 @@ -#include -#include - -void hook(void *arg, uvgrtp::frame::rtp_frame *frame) -{ - LOG_INFO("Raw video scan line(s) received"); - uvgrtp::frame::dealloc_frame(frame); -} - -int main(void) -{ - /* To use the library, one must create a global RTP context object */ - uvgrtp::context ctx; - - /* Each new IP address requires a separate RTP session */ - uvgrtp::session *sess = ctx.create_session("127.0.0.1"); - uvgrtp::media_stream *rwv = sess->create_stream(8888, 8888, RTP_FORMAT_RAW_VIDEO, RTP_NO_FLAGS); - - /* install receive hook for asynchronous frame reception */ - rwv->install_receive_hook(nullptr, hook); - - /* specify pixel format of input/output data */ - rwv->configure_ctx(RCC_FMT_SUBTYPE, uvgrtp::formats::RWV_FMT_YUV420); - - for (;;) { - uint8_t data[36]; - - rwv->push_frame((uint8_t *)data, sizeof(data), RTP_NO_FLAGS); - /* TODO: what kind of data is given to push_frame()? */ - } - - /* Session must be destroyed manually */ - ctx.destroy_session(sess); - - return 0; -} diff --git a/docs/html/classuvgrtp_1_1media__stream-members.html b/docs/html/classuvgrtp_1_1media__stream-members.html index 34e194e..bdba6f3 100644 --- a/docs/html/classuvgrtp_1_1media__stream-members.html +++ b/docs/html/classuvgrtp_1_1media__stream-members.html @@ -79,9 +79,9 @@ $(function() { pull_frame()uvgrtp::media_stream pull_frame(size_t timeout)uvgrtp::media_stream push_frame(uint8_t *data, size_t data_len, int flags)uvgrtp::media_stream - push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags) (defined in uvgrtp::media_stream)uvgrtp::media_stream - push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, int flags) (defined in uvgrtp::media_stream)uvgrtp::media_stream - push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags) (defined in uvgrtp::media_stream)uvgrtp::media_stream + push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, int flags)uvgrtp::media_stream + push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags)uvgrtp::media_stream + push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags)uvgrtp::media_stream
diff --git a/docs/html/classuvgrtp_1_1media__stream.html b/docs/html/classuvgrtp_1_1media__stream.html index c689352..b1b2ac5 100644 --- a/docs/html/classuvgrtp_1_1media__stream.html +++ b/docs/html/classuvgrtp_1_1media__stream.html @@ -79,15 +79,16 @@ Public Member Functions rtp_error_t add_srtp_ctx (uint8_t *key, uint8_t *salt)   rtp_error_t push_frame (uint8_t *data, size_t data_len, int flags) + Send data to remote participant with a custom timestamp. More...
  - -rtp_error_t push_frame (uint8_t *data, size_t data_len, uint32_t ts, int flags) -  - -rtp_error_t push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, int flags) +rtp_error_t push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, int flags) + Send data to remote participant with a custom timestamp. More...
  - -rtp_error_t push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags) +rtp_error_t push_frame (uint8_t *data, size_t data_len, uint32_t ts, int flags) + Send data to remote participant with a custom timestamp. More...
+  +rtp_error_t push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags) + Send data to remote participant with a custom timestamp. More...
  uvgrtp::frame::rtp_frame * pull_frame ()  Poll a frame indefinetily from the media stream object. More...
@@ -266,10 +267,133 @@ rtp_error_t push_frame

You can specify for how long should pull_frame() block by giving "timeout" parameter that denotes how long pull_frame() will wait for an incoming frame in milliseconds

Return pointer to RTP frame on success

+ + + +

◆ push_frame() [1/4]

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
rtp_error_t uvgrtp::media_stream::push_frame (std::unique_ptr< uint8_t[]> data,
size_t data_len,
int flags 
)
+
+ +

Send data to remote participant with a custom timestamp.

+

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, or to any other size defined by the application using RCC_MTU_SIZE

+

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

+
Parameters
+ + + + + +
dataSmart pointer to data the that should be sent
data_lenLength of data
ts32-bit timestamp value for the data
flagsOptional flags, see RTP_FLAGS for more details
+
+
+
Returns
RTP error code
+
Return values
+ + + + + + +
RTP_OKOn success
RTP_INVALID_VALUEIf one of the parameters are invalid
RTP_MEMORY_ERRORIf the data chunk is too large to be processed
RTP_SEND_ERRORIf uvgRTP failed to send the data to remote
RTP_GENERIC_ERRORIf an unspecified error occurred
+
+
+ +
+
+ +

◆ push_frame() [2/4]

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
rtp_error_t uvgrtp::media_stream::push_frame (std::unique_ptr< uint8_t[]> data,
size_t data_len,
uint32_t ts,
int flags 
)
+
+ +

Send data to remote participant with a custom timestamp.

+

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, or to any other size defined by the application using RCC_MTU_SIZE

+

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

+

If application so wishes, it may override uvgRTP's own timestamp calculations and provide timestamping information for the stream itself. This requires that the application provides a sensible value for the ts parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have been called.

+
Parameters
+ + + + + +
dataSmart pointer to data the that should be sent
data_lenLength of data
ts32-bit timestamp value for the data
flagsOptional flags, see RTP_FLAGS for more details
+
+
+
Returns
RTP error code
+
Return values
+ + + + + + +
RTP_OKOn success
RTP_INVALID_VALUEIf one of the parameters are invalid
RTP_MEMORY_ERRORIf the data chunk is too large to be processed
RTP_SEND_ERRORIf uvgRTP failed to send the data to remote
RTP_GENERIC_ERRORIf an unspecified error occurred
+
+
+
-

◆ push_frame()

+

◆ push_frame() [3/4]

@@ -299,12 +423,95 @@ rtp_error_t push_frame
-

Split "data" into 1500 byte chunks and send them to remote

-

NOTE: If SCD has been enabled, calling this version of push_frame() requires either that the caller has given a deallocation callback to SCD OR that "flags" contains flags "RTP_COPY"

-

NOTE: Each push_frame() sends one discrete frame of data. If the input frame is fragmented, calling application should call push_frame() with RTP_MORE and RTP_SLICE flags to prevent uvgRTP from flushing the frame queue after push_frame().

-

push_frame(..., RTP_MORE | RTP_SLICE); // more data coming in, do not flush queue push_frame(..., RTP_MORE | RTP_SLICE); // more data coming in, do not flush queue push_frame(..., RTP_SLICE); // no more data coming in, flush queue

-

If user wishes to manage RTP timestamps himself, he may pass "ts" to push_frame() which forces uvgRTP to use that timestamp for all RTP packets of "data".

-

Return RTP_OK success Return RTP_INVALID_VALUE if one of the parameters are invalid Return RTP_MEMORY_ERROR if the data chunk is too large to be processed Return RTP_SEND_ERROR if uvgRTP failed to send the data to remote Return RTP_GENERIC_ERROR for any other error condition

+ +

Send data to remote participant with a custom timestamp.

+

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, or to any other size defined by the application using RCC_MTU_SIZE

+

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

+
Parameters
+ + + + + +
dataPointer to data the that should be sent
data_lenLength of data
ts32-bit timestamp value for the data
flagsOptional flags, see RTP_FLAGS for more details
+
+
+
Returns
RTP error code
+
Return values
+ + + + + + +
RTP_OKOn success
RTP_INVALID_VALUEIf one of the parameters are invalid
RTP_MEMORY_ERRORIf the data chunk is too large to be processed
RTP_SEND_ERRORIf uvgRTP failed to send the data to remote
RTP_GENERIC_ERRORIf an unspecified error occurred
+
+
+ +
+
+ +

◆ push_frame() [4/4]

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
rtp_error_t uvgrtp::media_stream::push_frame (uint8_t * data,
size_t data_len,
uint32_t ts,
int flags 
)
+
+ +

Send data to remote participant with a custom timestamp.

+

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, or to any other size defined by the application using RCC_MTU_SIZE

+

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

+

If application so wishes, it may override uvgRTP's own timestamp calculations and provide timestamping information for the stream itself. This requires that the application provides a sensible value for the ts parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have been called.

+
Parameters
+ + + + + +
dataPointer to data the that should be sent
data_lenLength of data
ts32-bit timestamp value for the data
flagsOptional flags, see RTP_FLAGS for more details
+
+
+
Returns
RTP error code
+
Return values
+ + + + + + +
RTP_OKOn success
RTP_INVALID_VALUEIf one of the parameters are invalid
RTP_MEMORY_ERRORIf the data chunk is too large to be processed
RTP_SEND_ERRORIf uvgRTP failed to send the data to remote
RTP_GENERIC_ERRORIf an unspecified error occurred
+
+
diff --git a/docs/html/index.html b/docs/html/index.html index ebd3701..072f412 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -68,7 +68,7 @@ $(function() {

To use uvgRTP, you must first create a uvgrtp::context object

Then you need to allocate a uvgrtp::session object from the context object by calling uvgrtp::context::create_session()

Finally, you need to allocate a uvgrtp::media_stream object from the allocated session object by calling uvgrtp::session::create_stream()

-

This object is used for both sending and receiving, see documentation for uvgrtp::media_stream::push_frame(), uvgrtp::media_stream::pull_frame() and uvgrtp::media_stream::install_receive_hook() for more details.

+

This object is used for both sending and receiving, see documentation for uvgrtp::media_stream::push_frame(), uvgrtp::media_stream::pull_frame() and uvgrtp::media_stream::install_receive_hook() for more details.

diff --git a/docs/html/media__stream_8hh_source.html b/docs/html/media__stream_8hh_source.html index 2f4821b..200438d 100644 --- a/docs/html/media__stream_8hh_source.html +++ b/docs/html/media__stream_8hh_source.html @@ -127,105 +127,111 @@ $(function() {
58  * Return RTP_NOT_SUPPORTED if user-managed SRTP was not specified in create_stream() */
59  rtp_error_t add_srtp_ctx(uint8_t *key, uint8_t *salt);
60 
-
84  rtp_error_t push_frame(uint8_t *data, size_t data_len, int flags);
-
85  rtp_error_t push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags);
-
86  rtp_error_t push_frame(std::unique_ptr<uint8_t[]> data, size_t data_len, int flags);
-
87  rtp_error_t push_frame(std::unique_ptr<uint8_t[]> data, size_t data_len, uint32_t ts, int flags);
-
88 
-
103  uvgrtp::frame::rtp_frame *pull_frame();
-
104 
-
119  uvgrtp::frame::rtp_frame *pull_frame(size_t timeout);
-
120 
-
139  rtp_error_t install_receive_hook(void *arg, void (*hook)(void *, uvgrtp::frame::rtp_frame *));
-
140 
-
142  /* If system call dispatcher is enabled and calling application has special requirements
-
143  * for the deallocation of a frame, it may install a deallocation hook which is called
-
144  * when SCD has processed the frame
-
145  *
-
146  * Return RTP_OK on success
-
147  * Return RTP_INVALID_VALUE if "hook" is nullptr */
-
148  rtp_error_t install_deallocation_hook(void (*hook)(void *));
-
149 
-
150  /* If needed, a notification hook can be installed to uvgRTP that can be used as
-
151  * an information side channel to the internal state of the library.
-
152  *
-
153  * When uvgRTP encouters a situation it doesn't know how to react to,
-
154  * it calls the notify hook with certain notify reason number (src/util.hh).
-
155  * Upon receiving a notification, application may ignore it or act on it somehow
-
156  *
-
157  * Currently only one notification type is supported and only receiver uses notifications
-
158  *
-
159  * "arg" is optional argument that is passed to hook when it is called. It may be nullptr
-
160  *
-
161  * Return RTP_OK on success
-
162  * Return RTP_INVALID_VALUE if "hook" is nullptr */
-
163  rtp_error_t install_notify_hook(void *arg, void (*hook)(void *, int));
-
165 
-
176  rtp_error_t configure_ctx(int flag, ssize_t value);
-
177 
-
179  /* Setter and getter for media-specific config that can be used f.ex with Opus */
-
180  void set_media_config(void *config);
-
181  void *get_media_config();
-
182 
-
183  /* Get unique key of the media stream
-
184  * Used by session to index media streams */
-
185  uint32_t get_key();
-
187 
-
200  uvgrtp::rtcp *get_rtcp();
-
201 
-
202  private:
-
203  /* Initialize the connection by initializing the socket
-
204  * and binding ourselves to specified interface and creating
-
205  * an outgoing address */
-
206  rtp_error_t init_connection();
-
207 
-
208  uint32_t key_;
-
209 
-
210  uvgrtp::srtp *srtp_;
-
211  uvgrtp::srtcp *srtcp_;
-
212  uvgrtp::socket *socket_;
-
213  uvgrtp::rtp *rtp_;
-
214  uvgrtp::rtcp *rtcp_;
-
215 
-
216  sockaddr_in addr_out_;
-
217  std::string addr_;
-
218  std::string laddr_;
-
219  int src_port_;
-
220  int dst_port_;
-
221  rtp_format_t fmt_;
-
222  int flags_;
-
223 
-
224  /* Media context config (SCD etc.) */
-
225  rtp_ctx_conf_t ctx_config_;
-
226 
-
227  /* Media config f.ex. for Opus */
-
228  void *media_config_;
+
83  rtp_error_t push_frame(uint8_t *data, size_t data_len, int flags);
+
84 
+
107  rtp_error_t push_frame(std::unique_ptr<uint8_t[]> data, size_t data_len, int flags);
+
108 
+
137  rtp_error_t push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags);
+
138 
+
167  rtp_error_t push_frame(std::unique_ptr<uint8_t[]> data, size_t data_len, uint32_t ts, int flags);
+
168 
+
183  uvgrtp::frame::rtp_frame *pull_frame();
+
184 
+
199  uvgrtp::frame::rtp_frame *pull_frame(size_t timeout);
+
200 
+
219  rtp_error_t install_receive_hook(void *arg, void (*hook)(void *, uvgrtp::frame::rtp_frame *));
+
220 
+
222  /* If system call dispatcher is enabled and calling application has special requirements
+
223  * for the deallocation of a frame, it may install a deallocation hook which is called
+
224  * when SCD has processed the frame
+
225  *
+
226  * Return RTP_OK on success
+
227  * Return RTP_INVALID_VALUE if "hook" is nullptr */
+
228  rtp_error_t install_deallocation_hook(void (*hook)(void *));
229 
-
230  /* Has the media stream been initialized */
-
231  bool initialized_;
-
232 
-
233  /* Primary handler keys for the RTP packet dispatcher */
-
234  uint32_t rtp_handler_key_;
-
235  uint32_t zrtp_handler_key_;
-
236 
-
237  /* RTP packet dispatcher for the receiver */
-
238  uvgrtp::pkt_dispatcher *pkt_dispatcher_;
-
239  std::thread *dispatcher_thread_;
-
240 
-
241  /* Media object associated with this media stream. */
-
242  uvgrtp::formats::media *media_;
-
243 
-
244  /* Thread that keeps the holepunched connection open for unidirectional streams */
-
245  uvgrtp::holepuncher *holepuncher_;
-
246  };
-
247 };
-
248 
-
249 namespace uvg_rtp = uvgrtp;
+
230  /* If needed, a notification hook can be installed to uvgRTP that can be used as
+
231  * an information side channel to the internal state of the library.
+
232  *
+
233  * When uvgRTP encouters a situation it doesn't know how to react to,
+
234  * it calls the notify hook with certain notify reason number (src/util.hh).
+
235  * Upon receiving a notification, application may ignore it or act on it somehow
+
236  *
+
237  * Currently only one notification type is supported and only receiver uses notifications
+
238  *
+
239  * "arg" is optional argument that is passed to hook when it is called. It may be nullptr
+
240  *
+
241  * Return RTP_OK on success
+
242  * Return RTP_INVALID_VALUE if "hook" is nullptr */
+
243  rtp_error_t install_notify_hook(void *arg, void (*hook)(void *, int));
+
245 
+
256  rtp_error_t configure_ctx(int flag, ssize_t value);
+
257 
+
259  /* Setter and getter for media-specific config that can be used f.ex with Opus */
+
260  void set_media_config(void *config);
+
261  void *get_media_config();
+
262 
+
263  /* Get unique key of the media stream
+
264  * Used by session to index media streams */
+
265  uint32_t get_key();
+
267 
+
280  uvgrtp::rtcp *get_rtcp();
+
281 
+
282  private:
+
283  /* Initialize the connection by initializing the socket
+
284  * and binding ourselves to specified interface and creating
+
285  * an outgoing address */
+
286  rtp_error_t init_connection();
+
287 
+
288  uint32_t key_;
+
289 
+
290  uvgrtp::srtp *srtp_;
+
291  uvgrtp::srtcp *srtcp_;
+
292  uvgrtp::socket *socket_;
+
293  uvgrtp::rtp *rtp_;
+
294  uvgrtp::rtcp *rtcp_;
+
295 
+
296  sockaddr_in addr_out_;
+
297  std::string addr_;
+
298  std::string laddr_;
+
299  int src_port_;
+
300  int dst_port_;
+
301  rtp_format_t fmt_;
+
302  int flags_;
+
303 
+
304  /* Media context config (SCD etc.) */
+
305  rtp_ctx_conf_t ctx_config_;
+
306 
+
307  /* Media config f.ex. for Opus */
+
308  void *media_config_;
+
309 
+
310  /* Has the media stream been initialized */
+
311  bool initialized_;
+
312 
+
313  /* Primary handler keys for the RTP packet dispatcher */
+
314  uint32_t rtp_handler_key_;
+
315  uint32_t zrtp_handler_key_;
+
316 
+
317  /* RTP packet dispatcher for the receiver */
+
318  uvgrtp::pkt_dispatcher *pkt_dispatcher_;
+
319  std::thread *dispatcher_thread_;
+
320 
+
321  /* Media object associated with this media stream. */
+
322  uvgrtp::formats::media *media_;
+
323 
+
324  /* Thread that keeps the holepunched connection open for unidirectional streams */
+
325  uvgrtp::holepuncher *holepuncher_;
+
326  };
+
327 };
+
328 
+
329 namespace uvg_rtp = uvgrtp;
uvgrtp::media_stream
Definition: media_stream.hh:18
uvgrtp::media_stream::get_rtcp
uvgrtp::rtcp * get_rtcp()
Get pointer to the RTCP object of the media stream.
+
uvgrtp::media_stream::push_frame
rtp_error_t push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags)
Send data to remote participant with a custom timestamp.
uvgrtp::media_stream::pull_frame
uvgrtp::frame::rtp_frame * pull_frame(size_t timeout)
Poll a frame for a specified time from the media stream object.
uvgrtp::media_stream::install_receive_hook
rtp_error_t install_receive_hook(void *arg, void(*hook)(void *, uvgrtp::frame::rtp_frame *))
Asynchronous way of getting frames.
-
uvgrtp::media_stream::push_frame
rtp_error_t push_frame(uint8_t *data, size_t data_len, int flags)
+
uvgrtp::media_stream::push_frame
rtp_error_t push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags)
Send data to remote participant with a custom timestamp.
+
uvgrtp::media_stream::push_frame
rtp_error_t push_frame(uint8_t *data, size_t data_len, int flags)
Send data to remote participant with a custom timestamp.
+
uvgrtp::media_stream::push_frame
rtp_error_t push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, int flags)
Send data to remote participant with a custom timestamp.
uvgrtp::media_stream::configure_ctx
rtp_error_t configure_ctx(int flag, ssize_t value)
Configure the media stream, see RTP_CTX_CONFIGURATION_FLAGS for more details.
uvgrtp::media_stream::pull_frame
uvgrtp::frame::rtp_frame * pull_frame()
Poll a frame indefinetily from the media stream object.
uvgrtp::rtcp
Definition: rtcp.hh:74
diff --git a/docs/html/search/all_5.js b/docs/html/search/all_5.js index 5ff41d1..be8bb54 100644 --- a/docs/html/search/all_5.js +++ b/docs/html/search/all_5.js @@ -1,5 +1,5 @@ var searchData= [ ['pull_5fframe_9',['pull_frame',['../classuvgrtp_1_1media__stream.html#ae2fe9e8d9b67e25f103a78a25417149f',1,'uvgrtp::media_stream::pull_frame()'],['../classuvgrtp_1_1media__stream.html#a441263e19be4383223884fde8838f736',1,'uvgrtp::media_stream::pull_frame(size_t timeout)']]], - ['push_5fframe_10',['push_frame',['../classuvgrtp_1_1media__stream.html#ab2b7507d5b2c76bef74c9bceec07ba18',1,'uvgrtp::media_stream']]] + ['push_5fframe_10',['push_frame',['../classuvgrtp_1_1media__stream.html#ab2b7507d5b2c76bef74c9bceec07ba18',1,'uvgrtp::media_stream::push_frame(uint8_t *data, size_t data_len, int flags)'],['../classuvgrtp_1_1media__stream.html#ab2e79cf2f90f81a90ae9c22e0c1fb01e',1,'uvgrtp::media_stream::push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, int flags)'],['../classuvgrtp_1_1media__stream.html#a18975c5463df0664f1fd8ab495248dcc',1,'uvgrtp::media_stream::push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags)'],['../classuvgrtp_1_1media__stream.html#a85fed1e02b97326d3b794551f0677e2b',1,'uvgrtp::media_stream::push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags)']]] ]; diff --git a/docs/html/search/functions_4.js b/docs/html/search/functions_4.js index 6d8583c..756e325 100644 --- a/docs/html/search/functions_4.js +++ b/docs/html/search/functions_4.js @@ -1,5 +1,5 @@ var searchData= [ ['pull_5fframe_75',['pull_frame',['../classuvgrtp_1_1media__stream.html#ae2fe9e8d9b67e25f103a78a25417149f',1,'uvgrtp::media_stream::pull_frame()'],['../classuvgrtp_1_1media__stream.html#a441263e19be4383223884fde8838f736',1,'uvgrtp::media_stream::pull_frame(size_t timeout)']]], - ['push_5fframe_76',['push_frame',['../classuvgrtp_1_1media__stream.html#ab2b7507d5b2c76bef74c9bceec07ba18',1,'uvgrtp::media_stream']]] + ['push_5fframe_76',['push_frame',['../classuvgrtp_1_1media__stream.html#ab2b7507d5b2c76bef74c9bceec07ba18',1,'uvgrtp::media_stream::push_frame(uint8_t *data, size_t data_len, int flags)'],['../classuvgrtp_1_1media__stream.html#ab2e79cf2f90f81a90ae9c22e0c1fb01e',1,'uvgrtp::media_stream::push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, int flags)'],['../classuvgrtp_1_1media__stream.html#a18975c5463df0664f1fd8ab495248dcc',1,'uvgrtp::media_stream::push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags)'],['../classuvgrtp_1_1media__stream.html#a85fed1e02b97326d3b794551f0677e2b',1,'uvgrtp::media_stream::push_frame(std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int flags)']]] ]; diff --git a/docs/html/util_8hh.html b/docs/html/util_8hh.html index 0b0b0f4..8129951 100644 --- a/docs/html/util_8hh.html +++ b/docs/html/util_8hh.html @@ -157,7 +157,7 @@ Enumerations   RTP_COPY = 1 << 1
} - These flags are given to uvgrtp::media_stream::push_frame() and they can be OR'ed together. More...
+ These flags are given to uvgrtp::media_stream::push_frame() and they can be OR'ed together. More...
  enum  RTP_CTX_ENABLE_FLAGS {
  RCE_NO_FLAGS = 0 << 0 @@ -372,7 +372,7 @@ Enumerations
-

These flags are given to uvgrtp::media_stream::push_frame() and they can be OR'ed together.

+

These flags are given to uvgrtp::media_stream::push_frame() and they can be OR'ed together.

diff --git a/include/media_stream.hh b/include/media_stream.hh index 81612c4..6d5cb53 100644 --- a/include/media_stream.hh +++ b/include/media_stream.hh @@ -58,32 +58,115 @@ namespace uvgrtp { * Return RTP_NOT_SUPPORTED if user-managed SRTP was not specified in create_stream() */ rtp_error_t add_srtp_ctx(uint8_t *key, uint8_t *salt); - /** Split "data" into 1500 byte chunks and send them to remote + /** + * \brief Send data to remote participant with a custom timestamp * - * NOTE: If SCD has been enabled, calling this version of push_frame() - * requires either that the caller has given a deallocation callback to - * SCD OR that "flags" contains flags "RTP_COPY" + * \details If so specified either by the selected media format and/or given + * ::RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, + * or to any other size defined by the application using ::RCC_MTU_SIZE * - * NOTE: Each push_frame() sends one discrete frame of data. If the input frame - * is fragmented, calling application should call push_frame() with RTP_MORE - * and RTP_SLICE flags to prevent uvgRTP from flushing the frame queue after - * push_frame(). + * The frame is automatically reconstructed by the receiver if all fragments have been + * received successfully. * - * push_frame(..., RTP_MORE | RTP_SLICE); // more data coming in, do not flush queue - * push_frame(..., RTP_MORE | RTP_SLICE); // more data coming in, do not flush queue - * push_frame(..., RTP_SLICE); // no more data coming in, flush queue + * \param data Pointer to data the that should be sent + * \param data_len Length of data + * \param ts 32-bit timestamp value for the data + * \param flags Optional flags, see ::RTP_FLAGS for more details * - * If user wishes to manage RTP timestamps himself, he may pass "ts" to push_frame() - * which forces uvgRTP to use that timestamp for all RTP packets of "data". + * \return RTP error code * - * Return RTP_OK success - * Return RTP_INVALID_VALUE if one of the parameters are invalid - * Return RTP_MEMORY_ERROR if the data chunk is too large to be processed - * Return RTP_SEND_ERROR if uvgRTP failed to send the data to remote - * Return RTP_GENERIC_ERROR for any other error condition */ + * \retval RTP_OK On success + * \retval RTP_INVALID_VALUE If one of the parameters are invalid + * \retval RTP_MEMORY_ERROR If the data chunk is too large to be processed + * \retval RTP_SEND_ERROR If uvgRTP failed to send the data to remote + * \retval RTP_GENERIC_ERROR If an unspecified error occurred + */ rtp_error_t push_frame(uint8_t *data, size_t data_len, int flags); - rtp_error_t push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags); + + /** + * \brief Send data to remote participant with a custom timestamp + * + * \details If so specified either by the selected media format and/or given + * ::RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, + * or to any other size defined by the application using ::RCC_MTU_SIZE + * + * The frame is automatically reconstructed by the receiver if all fragments have been + * received successfully. + * + * \param data Smart pointer to data the that should be sent + * \param data_len Length of data + * \param ts 32-bit timestamp value for the data + * \param flags Optional flags, see ::RTP_FLAGS for more details + * + * \return RTP error code + * + * \retval RTP_OK On success + * \retval RTP_INVALID_VALUE If one of the parameters are invalid + * \retval RTP_MEMORY_ERROR If the data chunk is too large to be processed + * \retval RTP_SEND_ERROR If uvgRTP failed to send the data to remote + * \retval RTP_GENERIC_ERROR If an unspecified error occurred + */ rtp_error_t push_frame(std::unique_ptr data, size_t data_len, int flags); + + /** + * \brief Send data to remote participant with a custom timestamp + * + * \details If so specified either by the selected media format and/or given + * ::RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, + * or to any other size defined by the application using ::RCC_MTU_SIZE + * + * The frame is automatically reconstructed by the receiver if all fragments have been + * received successfully. + * + * If application so wishes, it may override uvgRTP's own timestamp + * calculations and provide timestamping information for the stream itself. + * This requires that the application provides a sensible value for the ts + * parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have + * been called. + * + * \param data Pointer to data the that should be sent + * \param data_len Length of data + * \param ts 32-bit timestamp value for the data + * \param flags Optional flags, see ::RTP_FLAGS for more details + * + * \return RTP error code + * + * \retval RTP_OK On success + * \retval RTP_INVALID_VALUE If one of the parameters are invalid + * \retval RTP_MEMORY_ERROR If the data chunk is too large to be processed + * \retval RTP_SEND_ERROR If uvgRTP failed to send the data to remote + * \retval RTP_GENERIC_ERROR If an unspecified error occurred + */ + rtp_error_t push_frame(uint8_t *data, size_t data_len, uint32_t ts, int flags); + + /** + * \brief Send data to remote participant with a custom timestamp + * + * \details If so specified either by the selected media format and/or given + * ::RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1500 bytes, + * or to any other size defined by the application using ::RCC_MTU_SIZE + * + * The frame is automatically reconstructed by the receiver if all fragments have been + * received successfully. + * + * If application so wishes, it may override uvgRTP's own timestamp + * calculations and provide timestamping information for the stream itself. + * This requires that the application provides a sensible value for the ts + * parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have + * been called. + * + * \param data Smart pointer to data the that should be sent + * \param data_len Length of data + * \param ts 32-bit timestamp value for the data + * \param flags Optional flags, see ::RTP_FLAGS for more details + * + * \return RTP error code + * + * \retval RTP_OK On success + * \retval RTP_INVALID_VALUE If one of the parameters are invalid + * \retval RTP_MEMORY_ERROR If the data chunk is too large to be processed + * \retval RTP_SEND_ERROR If uvgRTP failed to send the data to remote + * \retval RTP_GENERIC_ERROR If an unspecified error occurred */ rtp_error_t push_frame(std::unique_ptr data, size_t data_len, uint32_t ts, int flags); /**
Enumerator
RTP_NO_FLAGS 

No flags