From 354a392d696763b95ff35747989ab8821bd12934 Mon Sep 17 00:00:00 2001
From: irungentoo <irungentoo@gmail.com>
Date: Wed, 19 Feb 2014 08:08:55 -0500
Subject: [PATCH] Added better documentation to the api, move some defines,
 fixed a possible issue.

---
 toxav/rtp.c   |  2 +-
 toxav/toxav.c | 24 ++++++++++++++++++------
 toxav/toxav.h | 25 +++++++++----------------
 3 files changed, 28 insertions(+), 23 deletions(-)

diff --git a/toxav/rtp.c b/toxav/rtp.c
index 8f6f0be7..8eca46d4 100644
--- a/toxav/rtp.c
+++ b/toxav/rtp.c
@@ -517,7 +517,7 @@ int rtp_handle_packet ( void *object, IP_Port ip_port, uint8_t *data, uint32_t l
     RTPSession *_session = object;
     RTPMessage *_msg;
 
-    if ( !_session || length < 13 ) /* 12 is the minimum length for rtp + desc. byte */
+    if ( !_session || length < 13 + crypto_secretbox_MACBYTES) /* 12 is the minimum length for rtp + desc. byte */
         return -1;
 
     uint8_t _plain[MAX_UDP_PACKET_SIZE];
diff --git a/toxav/toxav.c b/toxav/toxav.c
index f704bc6b..e0ddc731 100644
--- a/toxav/toxav.c
+++ b/toxav/toxav.c
@@ -35,6 +35,16 @@
 
 #include "toxav.h"
 
+/* Default video bitrate in bytes/s */
+#define VIDEO_BITRATE   (10*1000*100)
+
+/* Default audio bitrate in bits/s */
+#define AUDIO_BITRATE   64000
+
+/* Assume 60 fps*/
+#define MAX_ENCODE_TIME_US ((1000 / 60) * 1000)
+
+
 #define inline__ inline __attribute__((always_inline))
 
 static const uint8_t audio_index = 0, video_index = 1;
@@ -474,11 +484,12 @@ inline__ int toxav_send_video ( ToxAv *av, vpx_image_t *input)
  * @brief Receive decoded audio frame.
  *
  * @param av Handler.
- * @param frame_size ...
- * @param dest Destination of the packet. Make sure it has enough space for
- *             RTP_PAYLOAD_SIZE bytes.
+ * @param frame_size The size of dest in frames/samples (one frame/sample is 16 bits or 2 bytes
+ *                   and corresponds to one sample of audio.)
+ * @param dest Destination of the raw audio (16 bit signed pcm with AUDIO_CHANNELS channels).
+ *             Make sure it has enough space for frame_size frames/samples.
  * @return int
- * @retval >=0 Size of received packet.
+ * @retval >=0 Size of received data in frames/samples.
  * @retval ToxAvError On error.
  */
 inline__ int toxav_recv_audio ( ToxAv *av, int frame_size, int16_t *dest )
@@ -503,8 +514,9 @@ inline__ int toxav_recv_audio ( ToxAv *av, int frame_size, int16_t *dest )
  * @brief Encode and send audio frame.
  *
  * @param av Handler.
- * @param frame The frame.
- * @param frame_size It's size.
+ * @param frame The frame (raw 16 bit signed pcm with AUDIO_CHANNELS channels audio.)
+ * @param frame_size Its size in number of frames/samples (one frame/sample is 16 bits or 2 bytes)
+ *                   frame size should be AUDIO_FRAME_SIZE.
  * @return int
  * @retval 0 Success.
  * @retval ToxAvError On error.
diff --git a/toxav/toxav.h b/toxav/toxav.h
index be7a2950..40cd90db 100644
--- a/toxav/toxav.h
+++ b/toxav/toxav.h
@@ -39,12 +39,6 @@ typedef struct Tox Tox;
 
 #define RTP_PAYLOAD_SIZE 65535
 
-/* Default video bitrate in bytes/s */
-#define VIDEO_BITRATE   10*1000*100
-
-/* Default audio bitrate in bits/s */
-#define AUDIO_BITRATE   64000
-
 /* Number of audio channels. */
 #define AUDIO_CHANNELS 1
 
@@ -55,10 +49,7 @@ typedef struct Tox Tox;
 #define AUDIO_SAMPLE_RATE   48000
 
 /* The amount of samples in one audio frame */
-#define AUDIO_FRAME_SIZE    AUDIO_SAMPLE_RATE*AUDIO_FRAME_DURATION/1000
-
-/* Assume 60 fps*/
-#define MAX_ENCODE_TIME_US ((1000 / 60) * 1000)
+#define AUDIO_FRAME_SIZE    (AUDIO_SAMPLE_RATE*AUDIO_FRAME_DURATION/1000)
 
 
 /**
@@ -246,11 +237,12 @@ int toxav_recv_video ( ToxAv *av, vpx_image_t **output);
  * @brief Receive decoded audio frame.
  *
  * @param av Handler.
- * @param frame_size ...
- * @param dest Destination of the packet. Make sure it has enough space for
- *             RTP_PAYLOAD_SIZE bytes.
+ * @param frame_size The size of dest in frames/samples (one frame/sample is 16 bits or 2 bytes
+ *                   and corresponds to one sample of audio.)
+ * @param dest Destination of the raw audio (16 bit signed pcm with AUDIO_CHANNELS channels).
+ *             Make sure it has enough space for frame_size frames/samples.
  * @return int
- * @retval >=0 Size of received packet.
+ * @retval >=0 Size of received data in frames/samples.
  * @retval ToxAvError On error.
  */
 int toxav_recv_audio( ToxAv *av, int frame_size, int16_t *dest );
@@ -270,8 +262,9 @@ int toxav_send_video ( ToxAv *av, vpx_image_t *input);
  * @brief Encode and send audio frame.
  *
  * @param av Handler.
- * @param frame The frame.
- * @param frame_size It's size.
+ * @param frame The frame (raw 16 bit signed pcm with AUDIO_CHANNELS channels audio.)
+ * @param frame_size Its size in number of frames/samples (one frame/sample is 16 bits or 2 bytes)
+ *                   frame size should be AUDIO_FRAME_SIZE.
  * @return int
  * @retval 0 Success.
  * @retval ToxAvError On error.