session: Document the farsight-telephony-event-started/stopped messages

Also use the specific registered types where appropriate

2 files changed, 47 insertions, 0 deletions

diff --git a/farstream/fs-session.c b/farstream/fs-session.c
index 36faf983..e22a8e1e 100644
--- a/farstream/fs-session.c
+++ b/farstream/fs-session.c
@@ -66,6 +66,32 @@
  * #FsSession:codecs-without-config should be enough.
  * </para>
  * </refsect2>
+ * <refsect2><title>The "<literal>farstream-telephony-event-started</literal>"
+ *  message</title>
+ * |[
+ * "session"          #FsSession          The session that emits the message
+ * "method"           #FsDTMFMethod       The method used to send the DTMF
+ * "event"            #FSDTMFEvent        The event number
+ * "volume"           gint                The volume of the event
+ * ]|
+ * <para>
+ * This message is emitted after a succesful call to
+ * fs_session_start_telephony_event() to inform the application that the
+ * telephony event has started.
+ * </para>
+ * </refsect2>
+ * <refsect2><title>The "<literal>farstream-telephony-event-stopped</literal>"
+ *  message</title>
+ * |[
+ * "session"          #FsSession          The session that emits the message
+ * "method"           #FsDTMFMethod       The method used to send the DTMF
+ * ]|
+ * <para>
+ * This message is emitted after a succesful call to
+ * fs_session_stop_telephony_event() to inform the application that the
+ * telephony event has stopped.
+ * </para>
+ * </refsect2>
  * <para>
  */
 
@@ -423,6 +449,9 @@ fs_session_new_stream (FsSession *session,
  * tone) on the #FsSession. You have to call the function
  * fs_session_stop_telephony_event() to stop it.
  *
+ * If this function returns %TRUE, a "farstream-telephony-event-started" will
+ * always be emitted when the event is actually played out.
+ *
  * Returns: %TRUE if sucessful, it can return %FALSE if the #FsStream
  * does not support this telephony event.
  */
@@ -454,6 +483,9 @@ fs_session_start_telephony_event (FsSession *session, guint8 event,
  * duration was a positive and the event is not over, it will cut it
  * short.
  *
+ * If this function returns %TRUE, a "farstream-telephony-event-stopped" will
+ * always be emitted when the event is actually stopped.
+
  * Returns: %TRUE if sucessful, it can return %FALSE if the #FsSession
  * does not support telephony events or if no telephony event is being sent
  */
diff --git a/farstream/fs-session.h b/farstream/fs-session.h
index 4a7cf928..bc063afb 100644
--- a/farstream/fs-session.h
+++ b/farstream/fs-session.h
@@ -84,6 +84,21 @@ typedef enum _FsDTMFEvent
 } FsDTMFEvent;
 
 /**
+ * FsDTMFMethod:
+ * @FS_DTMF_METHOD_RTP_RFC4733: Send as a special payload type defined by RFC 4733
+ * (which obsoletes RFC 2833)
+ * @FS_DTMF_METHOD_SOUND: Send as tones as in-band audio sound
+ *
+ * An enum that represents the different ways a DTMF event can be sent
+ *
+ */
+typedef enum _FsDTMFMethod
+{
+  FS_DTMF_METHOD_RTP_RFC4733 = 1,
+  FS_DTMF_METHOD_SOUND = 2
+} FsDTMFMethod;
+
+/**
  * FsSessionClass:
  * @parent_class: Our parent
  * @new_stream: Create a new #FsStream