diff --git a/docs/html/classuvgrtp_1_1media__stream.html b/docs/html/classuvgrtp_1_1media__stream.html index 64cc389..c689352 100644 --- a/docs/html/classuvgrtp_1_1media__stream.html +++ b/docs/html/classuvgrtp_1_1media__stream.html @@ -96,6 +96,7 @@ rtp_error_t push_frame  Poll a frame for a specified time from the media stream object. More...
  rtp_error_t install_receive_hook (void *arg, void(*hook)(void *, uvgrtp::frame::rtp_frame *)) + Asynchronous way of getting frames. More...
  rtp_error_t configure_ctx (int flag, ssize_t value)  Configure the media stream, see RTP_CTX_CONFIGURATION_FLAGS for more details. More...
@@ -198,10 +199,25 @@ rtp_error_t push_frame
-

Alternative to pull_frame(). The provided hook is called when a frame is received.

-

"arg" is optional argument that is passed to hook when it is called. It may be nullptr

-

NOTE: Hook should not be used to process the frame but it should be a place where the frame handout happens from uvgRTP to application

-

Return RTP_OK on success Return RTP_INVALID_VALUE if "hook" is nullptr

+ +

Asynchronous way of getting frames.

+

Receive hook is an alternative to polling frames using uvgrtp::media_stream::pull_frame(). Instead of application asking from uvgRTP if there are any new frames available, uvgRTP will notify the application when a frame has been received

+

The hook should not be used for media processing as it will block the receiver from reading more frames. Instead, it should only be used as an interface between uvgRTP and the calling application where the frame hand-off happens.

+
Parameters
+ + + +
argOptional argument that is passed to the hook when it is called, can be set to nullptr
hookFunction pointer to the receive hook that uvgRTP should call
+
+
+
Returns
RTP error code
+
Return values
+ + + +
RTP_OKOn success
RTP_INVALID_VALUEIf hook is nullptr
+
+
diff --git a/docs/html/index.html b/docs/html/index.html index bb53316..ebd3701 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 9d5d24b..2f4821b 100644 --- a/docs/html/media__stream_8hh_source.html +++ b/docs/html/media__stream_8hh_source.html @@ -136,95 +136,95 @@ $(function() {
104 
119  uvgrtp::frame::rtp_frame *pull_frame(size_t timeout);
120 
-
130  rtp_error_t install_receive_hook(void *arg, void (*hook)(void *, uvgrtp::frame::rtp_frame *));
-
131 
-
133  /* If system call dispatcher is enabled and calling application has special requirements
-
134  * for the deallocation of a frame, it may install a deallocation hook which is called
-
135  * when SCD has processed the frame
-
136  *
-
137  * Return RTP_OK on success
-
138  * Return RTP_INVALID_VALUE if "hook" is nullptr */
-
139  rtp_error_t install_deallocation_hook(void (*hook)(void *));
+
139  rtp_error_t install_receive_hook(void *arg, void (*hook)(void *, uvgrtp::frame::rtp_frame *));
140 
-
141  /* If needed, a notification hook can be installed to uvgRTP that can be used as
-
142  * an information side channel to the internal state of the library.
-
143  *
-
144  * When uvgRTP encouters a situation it doesn't know how to react to,
-
145  * it calls the notify hook with certain notify reason number (src/util.hh).
-
146  * Upon receiving a notification, application may ignore it or act on it somehow
-
147  *
-
148  * Currently only one notification type is supported and only receiver uses notifications
-
149  *
-
150  * "arg" is optional argument that is passed to hook when it is called. It may be nullptr
-
151  *
-
152  * Return RTP_OK on success
-
153  * Return RTP_INVALID_VALUE if "hook" is nullptr */
-
154  rtp_error_t install_notify_hook(void *arg, void (*hook)(void *, int));
-
156 
-
167  rtp_error_t configure_ctx(int flag, ssize_t value);
-
168 
-
170  /* Setter and getter for media-specific config that can be used f.ex with Opus */
-
171  void set_media_config(void *config);
-
172  void *get_media_config();
-
173 
-
174  /* Get unique key of the media stream
-
175  * Used by session to index media streams */
-
176  uint32_t get_key();
-
178 
-
191  uvgrtp::rtcp *get_rtcp();
-
192 
-
193  private:
-
194  /* Initialize the connection by initializing the socket
-
195  * and binding ourselves to specified interface and creating
-
196  * an outgoing address */
-
197  rtp_error_t init_connection();
-
198 
-
199  uint32_t key_;
-
200 
-
201  uvgrtp::srtp *srtp_;
-
202  uvgrtp::srtcp *srtcp_;
-
203  uvgrtp::socket *socket_;
-
204  uvgrtp::rtp *rtp_;
-
205  uvgrtp::rtcp *rtcp_;
-
206 
-
207  sockaddr_in addr_out_;
-
208  std::string addr_;
-
209  std::string laddr_;
-
210  int src_port_;
-
211  int dst_port_;
-
212  rtp_format_t fmt_;
-
213  int flags_;
-
214 
-
215  /* Media context config (SCD etc.) */
-
216  rtp_ctx_conf_t ctx_config_;
-
217 
-
218  /* Media config f.ex. for Opus */
-
219  void *media_config_;
-
220 
-
221  /* Has the media stream been initialized */
-
222  bool initialized_;
+
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  /* Primary handler keys for the RTP packet dispatcher */
-
225  uint32_t rtp_handler_key_;
-
226  uint32_t zrtp_handler_key_;
-
227 
-
228  /* RTP packet dispatcher for the receiver */
-
229  uvgrtp::pkt_dispatcher *pkt_dispatcher_;
-
230  std::thread *dispatcher_thread_;
-
231 
-
232  /* Media object associated with this media stream. */
-
233  uvgrtp::formats::media *media_;
-
234 
-
235  /* Thread that keeps the holepunched connection open for unidirectional streams */
-
236  uvgrtp::holepuncher *holepuncher_;
-
237  };
-
238 };
-
239 
-
240 namespace uvg_rtp = uvgrtp;
+
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_;
+
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;
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::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 *))
+
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::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.
diff --git a/include/media_stream.hh b/include/media_stream.hh index 8b895d4..81612c4 100644 --- a/include/media_stream.hh +++ b/include/media_stream.hh @@ -118,15 +118,24 @@ namespace uvgrtp { * Return pointer to RTP frame on success */ uvgrtp::frame::rtp_frame *pull_frame(size_t timeout); - /** Alternative to pull_frame(). The provided hook is called when a frame is received. + /** + * \brief Asynchronous way of getting frames * - * "arg" is optional argument that is passed to hook when it is called. It may be nullptr + * \details Receive hook is an alternative to polling frames using uvgrtp::media_stream::pull_frame(). + * Instead of application asking from uvgRTP if there are any new frames available, uvgRTP will notify + * the application when a frame has been received * - * NOTE: Hook should not be used to process the frame but it should be a place where the - * frame handout happens from uvgRTP to application + * The hook should not be used for media processing as it will block the receiver from + * reading more frames. Instead, it should only be used as an interface between uvgRTP and + * the calling application where the frame hand-off happens. * - * Return RTP_OK on success - * Return RTP_INVALID_VALUE if "hook" is nullptr */ + * \param arg Optional argument that is passed to the hook when it is called, can be set to nullptr + * \param hook Function pointer to the receive hook that uvgRTP should call + * + * \return RTP error code + * + * \retval RTP_OK On success + * \retval RTP_INVALID_VALUE If hook is nullptr */ rtp_error_t install_receive_hook(void *arg, void (*hook)(void *, uvgrtp::frame::rtp_frame *)); /// \cond DO_NOT_DOCUMENT