Related to preview (re #1340): handle problems with starting or stopping preview during a call

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@3758 74dad513-b988-da41-8d7b-12977e46ad98

3 files changed, 52 insertions, 2 deletions

diff --git a/pjmedia/include/pjmedia-videodev/videodev.h b/pjmedia/include/pjmedia-videodev/videodev.h
index 30a9750b..0c3d4c82 100644
--- a/pjmedia/include/pjmedia-videodev/videodev.h
+++ b/pjmedia/include/pjmedia-videodev/videodev.h
@@ -220,7 +220,13 @@ typedef struct pjmedia_vid_dev_info
      */
     pjmedia_dir dir;
 
-    /** Specify whether the device supports callback */
+    /**
+     * Specify whether the device supports callback. Devices that implement
+     * "active interface" will actively call the callbacks to give or ask for
+     * video frames. If the device doesn't support callback, application
+     * must actively request or give video frames from/to the device by using
+     * pjmedia_vid_dev_stream_get_frame()/pjmedia_vid_dev_stream_put_frame().
+     */
     pj_bool_t has_callback;
 
     /** Device capabilities, as bitmask combination of #pjmedia_vid_dev_cap */
@@ -641,6 +647,16 @@ PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_start(
 					    pjmedia_vid_dev_stream *strm);
 
 /**
+ * Query whether the stream has been started.
+ *
+ * @param strm	    The video stream
+ *
+ * @return	    PJ_TRUE if the video stream has been started.
+ */
+PJ_DECL(pj_bool_t) pjmedia_vid_dev_stream_is_running(pjmedia_vid_dev_stream *strm);
+
+
+/**
  * Get the event publisher object for the video stream. Caller typically use
  * the returned object to subscribe or unsubscribe events from the video
  * stream.
@@ -652,11 +668,33 @@ PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_start(
 PJ_DECL(pjmedia_event_publisher*)
 pjmedia_vid_dev_stream_get_event_publisher(pjmedia_vid_dev_stream *strm);
 
-/* Get/put frame API for passive stream */
+
+/**
+ * Request one frame from the stream. Application needs to call this function
+ * periodically only if the stream doesn't support "active interface", i.e.
+ * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
+ *
+ * @param strm      The video stream.
+ * @param frame	    The video frame to be filled by the device.
+ *
+ * @return          PJ_SUCCESS on successful operation or the appropriate
+ *                  error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_frame(
 					    pjmedia_vid_dev_stream *strm,
                                             pjmedia_frame *frame);
 
+/**
+ * Put one frame to the stream. Application needs to call this function
+ * periodically only if the stream doesn't support "active interface", i.e.
+ * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
+ *
+ * @param strm      The video stream.
+ * @param frame	    The video frame to put to the device.
+ *
+ * @return          PJ_SUCCESS on successful operation or the appropriate
+ *                  error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_put_frame(
 					    pjmedia_vid_dev_stream *strm,
                                             const pjmedia_frame *frame);
diff --git a/pjmedia/include/pjmedia-videodev/videodev_imp.h b/pjmedia/include/pjmedia-videodev/videodev_imp.h
index 90dcc580..8ddfd968 100644
--- a/pjmedia/include/pjmedia-videodev/videodev_imp.h
+++ b/pjmedia/include/pjmedia-videodev/videodev_imp.h
@@ -181,6 +181,9 @@ struct pjmedia_vid_dev_stream
     struct {
 	/** Driver index */
 	unsigned drv_idx;
+
+	/** Has it been started? */
+	pj_bool_t is_running;
     } sys;
 
     /** Operations */
diff --git a/pjmedia/include/pjmedia/vid_port.h b/pjmedia/include/pjmedia/vid_port.h
index b7fa5666..66c31c84 100644
--- a/pjmedia/include/pjmedia/vid_port.h
+++ b/pjmedia/include/pjmedia/vid_port.h
@@ -213,6 +213,15 @@ pjmedia_vid_port_get_connected_port(pjmedia_vid_port *vid_port);
 PJ_DECL(pj_status_t) pjmedia_vid_port_start(pjmedia_vid_port *vid_port);
 
 /**
+ * Query whether the video port has been started.
+ *
+ * @param vid_port	The video port.
+ *
+ * @return		PJ_TRUE if the video port has been started.
+ */
+PJ_DECL(pj_bool_t) pjmedia_vid_port_is_running(pjmedia_vid_port *vid_port);
+
+/**
  * Stop the video port.
  *
  * @param vid_port	The video port.