Latest cumulative changes including:

* Addition of a received application ACK notification callback
* Lifecycle management improvements
* Exposed failure on progressive back-off/retry logic
* Hardening/fixing various edge-cases

Author: MushMal

.gitignore

@@ -1 +1,12 @@
 .DS_Store
+CMakeCache.txt
+CMakeFiles/
+Makefile
+cmake_install.cmake
+kinesis-video-native-build/downloads/
+kinesis-video-native-build/kinesis_video_gstreamer_sample_app
+kinesis-video-native-build/libKinesisVideoProducerJNI.dylib
+kinesis-video-native-build/libproducer.dylib
+kinesis-video-native-build/start
+kinesis-video-native-build/test_h264_jpg.mkv
+kinesis-video-native-build/test_jpeg.mkv

README.md

@@ -17,9 +17,22 @@ Amazon Kinesis Video Streams Producer SDK for C/C++ contains the following sub-d
 * kinesis-video-native-build - Native build directory with a build script for Mac OS/Linux/Raspberry PI. This is the directory that will contain the artifacts after the build.
 
 ## Building from Source
+There are few build-time tools/dependencies which need to be installed in order to build the core SDK libraries and the samples.
+
+### Build Dependencies 
+Please install the following additional build tools before proceeding (the example below is for Mac Os X).
+* autoconf 2.69 (License GPLv3+/Autoconf: GNU GPL version 3 or later) http://www.gnu.org/software/autoconf/autoconf.html
+* cmake 3.7/3.8 https://cmake.org/
+* flex 2.5.35 Apple(flex-31)
+* bison 2.4 (GNU License)
+* automake 1.15.1 (GNU License)
+* libtool (Apple Inc. version cctools-898)
+* xCode (Mac OS) / clang / gcc (xcode-select version 2347)
+* Java jdk (for Java JNI compilation)
+
 After you've downloaded the code from GitHub, you can build it on Mac OS or Ubuntu using ./kinesis-video-native-build/install-script script. This will produce the core library, the JNI library, unit tests executable and the sample GStreamer application. The script will download and build the dependent open source components in the 'downloads' directory and link against it. 
 
-Important: Set the JAVA_HOME environment variable to your version of the JDK `export JAVA_HOME=<your java home directory>` in order to build and link JNI component.
+**Important:** Set the JAVA_HOME environment variable to your version of the JDK `export JAVA_HOME=<your java home directory>` in order to build and link JNI component.
 
 The bulk of the install script is building the open source dependencies. The project is based on CMake so the open source components building can be skipped if the system versions can be used for linking. Running 'cmake . && make' from the kinesis-video-native-build directory will build and link the SDK.
 
@@ -45,16 +58,6 @@ The projects depend on the following open source components. Running `install-sc
 * gst-plugins-ugly
 * x264 - https://www.videolan.org/developers/x264.html
 
-### Build Dependencies 
-Please install the following additional build tools before running install-script.
-* autoconf 2.69 (License GPLv3+/Autoconf: GNU GPL version 3 or later) http://www.gnu.org/software/autoconf/autoconf.html
-* cmake 3.7/3.8 https://cmake.org/
-* bison 2.4 (GNU License)
-* automake 1.15.1 (GNU License)
-* libtool (Apple Inc. version cctools-898)
-* xCode (Mac OS) / clang / gcc (xcode-select version 2347)
-* Java jdk (for Java JNI compilation)
-
 ## Certificate store integration
 Kinesis Video Streams Produicer SDK for C++ needs to establish trust with the backend service through TLS. This is done through validating the CAs in the public certificate store. On Linux-based models, this store is located in /etc/ssl/ directory by default. 
 
@@ -216,11 +219,29 @@ OpenJDK 64-Bit Server VM (build 25.151-b12, mixed mode)
 
 * Raspberry PI failure to load the camera device. To check this is the case run `ls /dev/video*` - it should be file not found. The remedy is to run the following:
 
-> vcgencmd get_camera
-supported=1 detected=1
+$ls /dev/video* {not found}
+
+$vcgencmd get_camera {output is similar to supported=1 detected=1}
+
+if the driver does not detect the camera then 
+
+* Check for the camera setup and whether it's connected properly
+* Run firmware update `$ sudo rpi-update` and restart
+
+$sudo modprobe bcm2835-v4l2
+
+$ls /dev/video* {lists the device}
+
+
+* Raspberry PI timestamp/range assertion at runtime. Update the Raspberry PI firmware.
+
+$ sudo rpi-update 
+
+$ sudo reboot
+
+
+* Raspberry PI GStreamer assertion on gst_value_set_fraction_range_full: assertion 'gst_util_fraction_compare (numerator_start, denominator_start, numerator_end, denominator_end) < 0' failed. The uv4l service running in the background. Kill the service and restart the sample app.
 
-> sudo modprobe bcm2835-v4l2
-> ls /dev/video*
 
 * Raspberry PI seg fauls after some time running on libx264.so. Rebuilding the libx264.so library and re-linking the demo application fixes the issue.
 

kinesis-video-pic/src/client/include/com/amazonaws/kinesis/video/client/Include.h

@@ -1200,6 +1200,19 @@ typedef STATUS (*StreamErrorReportFunc)(UINT64,
                                         UINT64,
                                         STATUS);
 
+/**
+ * Reports a received fragment ack for the stream.
+ *
+ * @param 1 UINT64 - Custom handle passed by the caller.
+ * @param 2 STREAM_HANDLE - The stream to report for.
+ * @param 3 PFragmentAck - The constructed fragment ack.
+ *
+ * @return Status of the callback
+ */
+typedef STATUS (*FragmentAckReceivedFunc)(UINT64,
+                                          STREAM_HANDLE,
+                                          PFragmentAck);
+
 ///////////////////////////////////////////////////////////////
 // State transition callbacks
 ///////////////////////////////////////////////////////////////
@@ -1484,6 +1497,7 @@ struct __ClientCallbacks {
     DroppedFrameReportFunc droppedFrameReportFn;
     DroppedFragmentReportFunc droppedFragmentReportFn;
     StreamErrorReportFunc streamErrorReportFn;
+    FragmentAckReceivedFunc fragmentAckReceivedFn;
     StreamDataAvailableFunc streamDataAvailableFn;
     StreamReadyFunc streamReadyFn;
     StreamClosedFunc streamClosedFn;

kinesis-video-pic/src/client/src/Client.cpp

@@ -176,7 +176,7 @@ STATUS freeKinesisVideoClient(PCLIENT_HANDLE pClientHandle)
 
     // Release the underlying objects
     for (i = 0; i < pKinesisVideoClient->deviceInfo.streamCount; i++) {
-        // Call is indempotent so NULL is OK
+        // Call is idempotent so NULL is OK
         retStatus = freeStream(pKinesisVideoClient->streams[i]);
         freeStreamStatus = STATUS_FAILED(retStatus) ? retStatus : freeStreamStatus;
     }
@@ -485,7 +485,7 @@ STATUS describeStreamResultEvent(UINT64 customData, SERVICE_CALL_RESULT callResu
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
 
     DLOGI("Describe stream result event.");
 
@@ -505,7 +505,7 @@ STATUS createStreamResultEvent(UINT64 customData, SERVICE_CALL_RESULT callResult
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
 
     DLOGI("Create stream result event.");
 
@@ -525,7 +525,7 @@ STATUS getStreamingTokenResultEvent(UINT64 customData, SERVICE_CALL_RESULT callR
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
 
     DLOGI("Get streaming token result event.");
 
@@ -545,7 +545,7 @@ STATUS getStreamingEndpointResultEvent(UINT64 customData, SERVICE_CALL_RESULT ca
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
 
     DLOGI("Get streaming endpoint result event.");
 
@@ -565,7 +565,7 @@ STATUS putStreamResultEvent(UINT64 customData, SERVICE_CALL_RESULT callResult, U
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
 
     DLOGI("Put stream result event.");
 
@@ -595,23 +595,20 @@ STATUS tagResourceResultEvent(UINT64 customData, SERVICE_CALL_RESULT callResult)
 
     objectIdentifier = KINESIS_VIDEO_OBJECT_IDENTIFIER_FROM_CUSTOM_DATA(customData);
 
-    switch(objectIdentifier) {
-        case KINESIS_VIDEO_OBJECT_IDENTIFIER_CLIENT:
-            pKinesisVideoClient = CLIENT_FROM_CUSTOM_DATA(customData);
+    // Check if it's a client
+    if (objectIdentifier == KINESIS_VIDEO_OBJECT_IDENTIFIER_CLIENT) {
+        pKinesisVideoClient = CLIENT_FROM_CUSTOM_DATA(customData);
 
-            // Call tagging result for client
-            CHK_STATUS(tagClientResult(pKinesisVideoClient, callResult));
-            break;
+        // Call tagging result for client
+        CHK_STATUS(tagClientResult(pKinesisVideoClient, callResult));
+    } else {
+        pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
 
-        case KINESIS_VIDEO_OBJECT_IDENTIFIER_STREAM:
-            pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
+        // Validate it's a stream object
+        CHK(pKinesisVideoStream->base.identifier == KINESIS_VIDEO_OBJECT_IDENTIFIER_STREAM, STATUS_INVALID_CUSTOM_DATA);
 
-            // Call tagging result for stream
-            CHK_STATUS(tagStreamResult(pKinesisVideoStream, callResult));
-            break;
-
-        default:
-            CHK(FALSE, STATUS_INVALID_CUSTOM_DATA);
+        // Call tagging result for stream
+        CHK_STATUS(tagStreamResult(pKinesisVideoStream, callResult));
     }
 
 CleanUp:
@@ -626,7 +623,7 @@ STATUS kinesisVideoStreamTerminated(STREAM_HANDLE streamHandle, SERVICE_CALL_RES
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(streamHandle);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(streamHandle);
 
     DLOGI("Stream terminated event.");
 
@@ -646,7 +643,7 @@ STATUS kinesisVideoStreamFragmentAck(STREAM_HANDLE streamHandle, PFragmentAck pF
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(streamHandle);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(streamHandle);
 
     DLOGS("Stream fragment ACK event.");
 
@@ -666,7 +663,7 @@ STATUS kinesisVideoStreamParseFragmentAck(STREAM_HANDLE streamHandle, PCHAR ackS
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(streamHandle);
+    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(streamHandle);
 
     DLOGS("Parsing stream fragment ACK.");
 
@@ -690,7 +687,7 @@ VOID viewItemRemoved(PContentView pContentView, UINT64 customData, PViewItem pVi
 {
     ENTERS();
     STATUS retStatus = STATUS_SUCCESS;
-    PKinesisVideoStream pKinesisVideoStream = FROM_STREAM_HANDLE(customData);
+    PKinesisVideoStream pKinesisVideoStream = STREAM_FROM_CUSTOM_DATA(customData);
     PKinesisVideoClient pKinesisVideoClient = NULL;
     BOOL streamLocked = FALSE;
 

kinesis-video-pic/src/client/src/Include_i.h

@@ -104,8 +104,8 @@ typedef __KinesisVideoBase* PKinesisVideoBase;
 #define TO_CLIENT_HANDLE(p) ((CLIENT_HANDLE) (p))
 #define FROM_CLIENT_HANDLE(h) ((PKinesisVideoClient) (h))
 
-#define TO_STREAM_HANDLE(p) ((STREAM_HANDLE) (p))
-#define FROM_STREAM_HANDLE(h) ((PKinesisVideoStream) (h))
+#define TO_STREAM_HANDLE(p) (toStreamHandle(p))
+#define FROM_STREAM_HANDLE(h) (fromStreamHandle(h))
 
 #define TO_CUSTOM_DATA(p) ((UINT64) (p))
 #define STREAM_FROM_CUSTOM_DATA(h) ((PKinesisVideoStream) (h))
@@ -205,6 +205,16 @@ typedef __KinesisVideoClient* PKinesisVideoClient;
 ////////////////////////////////////////////////////
 // Internal functionality
 ////////////////////////////////////////////////////
+/**
+ * Converts the stream to a stream handle
+ */
+STREAM_HANDLE toStreamHandle(PKinesisVideoStream);
+
+/**
+ * Converts handle to a stream
+ */
+PKinesisVideoStream fromStreamHandle(STREAM_HANDLE);
+
 /**
  * Callback function which is invoked when an item gets purged from the view
  */

kinesis-video-pic/src/client/src/Stream.cpp

@@ -181,7 +181,7 @@ STATUS createStream(PKinesisVideoClient pKinesisVideoClient, PStreamInfo pStream
     CHK_STATUS(createContentView(maxViewItems,
                                  pKinesisVideoStream->streamInfo.streamCaps.bufferDuration,
                                  viewItemRemoved,
-                                 (UINT64) pKinesisVideoStream,
+                                 TO_CUSTOM_DATA(pKinesisVideoStream),
                                  &pView));
     pKinesisVideoStream->pView = pView;
 
@@ -1388,4 +1388,26 @@ STATUS checkStreamingTokenExpiration(PKinesisVideoStream pKinesisVideoStream) {
 
     LEAVES();
     return retStatus;
-}
+}
+
+/**
+ * Converts the stream to a stream handle
+ */
+STREAM_HANDLE toStreamHandle(PKinesisVideoStream pKinesisVideoStream) {
+    if (pKinesisVideoStream == NULL) {
+        return INVALID_STREAM_HANDLE_VALUE;
+    } else {
+        return (STREAM_HANDLE) &pKinesisVideoStream->pKinesisVideoClient->streams[pKinesisVideoStream->streamId];
+    }
+}
+
+/**
+ * Converts handle to a stream
+ */
+PKinesisVideoStream fromStreamHandle(STREAM_HANDLE streamHandle) {
+    if (streamHandle == INVALID_STREAM_HANDLE_VALUE) {
+        return NULL;
+    } else {
+        return *((PKinesisVideoStream*) streamHandle);
+    }
+}

kinesis-video-pic/src/client/src/StreamEvent.cpp

@@ -639,6 +639,13 @@ STATUS streamFragmentAckEvent(PKinesisVideoStream pKinesisVideoStream, PFragment
 
 CleanUp:
 
+    // Notify on success and if we have the callback
+    if (STATUS_SUCCEEDED(retStatus) && pKinesisVideoClient->clientCallbacks.fragmentAckReceivedFn != NULL) {
+        pKinesisVideoClient->clientCallbacks.fragmentAckReceivedFn(pKinesisVideoClient->clientCallbacks.customData,
+                                                                   TO_STREAM_HANDLE(pKinesisVideoStream),
+                                                                   pFragmentAck);
+    }
+
     // Unlock the stream
     if (locked) {
         pKinesisVideoClient->clientCallbacks.unlockMutexFn(pKinesisVideoClient->clientCallbacks.customData, pKinesisVideoStream->base.lock);

kinesis-video-pic/src/client/src/StreamState.cpp

@@ -84,7 +84,7 @@ STATUS executeDescribeStreamState(UINT64 customData, UINT64 time)
 
     pKinesisVideoStream->base.serviceCallContext.pAuthInfo = &pKinesisVideoClient->tokenAuthInfo;
     pKinesisVideoStream->base.serviceCallContext.version = SERVICE_CALL_CONTEXT_CURRENT_VERSION;
-    pKinesisVideoStream->base.serviceCallContext.customData = TO_CUSTOM_DATA(pKinesisVideoStream);
+    pKinesisVideoStream->base.serviceCallContext.customData = TO_STREAM_HANDLE(pKinesisVideoStream);
     pKinesisVideoStream->base.serviceCallContext.timeout = SERVICE_CALL_DEFAULT_TIMEOUT;
     pKinesisVideoStream->base.serviceCallContext.callAfter = time;
 
@@ -406,7 +406,7 @@ STATUS executeGetEndpointStreamState(UINT64 customData, UINT64 time)
 
     pKinesisVideoStream->base.serviceCallContext.pAuthInfo = &pKinesisVideoClient->tokenAuthInfo;
     pKinesisVideoStream->base.serviceCallContext.version = SERVICE_CALL_CONTEXT_CURRENT_VERSION;
-    pKinesisVideoStream->base.serviceCallContext.customData = TO_CUSTOM_DATA(pKinesisVideoStream);
+    pKinesisVideoStream->base.serviceCallContext.customData = TO_STREAM_HANDLE(pKinesisVideoStream);
     pKinesisVideoStream->base.serviceCallContext.timeout = SERVICE_CALL_DEFAULT_TIMEOUT;
     pKinesisVideoStream->base.serviceCallContext.callAfter = time;
 
@@ -442,7 +442,7 @@ STATUS executeGetTokenStreamState(UINT64 customData, UINT64 time)
 
     pKinesisVideoStream->base.serviceCallContext.pAuthInfo = &pKinesisVideoClient->tokenAuthInfo;
     pKinesisVideoStream->base.serviceCallContext.version = SERVICE_CALL_CONTEXT_CURRENT_VERSION;
-    pKinesisVideoStream->base.serviceCallContext.customData = TO_CUSTOM_DATA(pKinesisVideoStream);
+    pKinesisVideoStream->base.serviceCallContext.customData = TO_STREAM_HANDLE(pKinesisVideoStream);
     pKinesisVideoStream->base.serviceCallContext.timeout = SERVICE_CALL_DEFAULT_TIMEOUT;
     pKinesisVideoStream->base.serviceCallContext.callAfter = time;
 
@@ -478,7 +478,7 @@ STATUS executeCreateStreamState(UINT64 customData, UINT64 time)
 
     pKinesisVideoStream->base.serviceCallContext.pAuthInfo = &pKinesisVideoClient->tokenAuthInfo;
     pKinesisVideoStream->base.serviceCallContext.version = SERVICE_CALL_CONTEXT_CURRENT_VERSION;
-    pKinesisVideoStream->base.serviceCallContext.customData = TO_CUSTOM_DATA(pKinesisVideoStream);
+    pKinesisVideoStream->base.serviceCallContext.customData = TO_STREAM_HANDLE(pKinesisVideoStream);
     pKinesisVideoStream->base.serviceCallContext.timeout = SERVICE_CALL_DEFAULT_TIMEOUT;
     pKinesisVideoStream->base.serviceCallContext.callAfter = time;
 
@@ -518,7 +518,7 @@ STATUS executeTagStreamState(UINT64 customData, UINT64 time)
 
     pKinesisVideoStream->base.serviceCallContext.pAuthInfo = &pKinesisVideoClient->tokenAuthInfo;
     pKinesisVideoStream->base.serviceCallContext.version = SERVICE_CALL_CONTEXT_CURRENT_VERSION;
-    pKinesisVideoStream->base.serviceCallContext.customData = TO_CUSTOM_DATA(pKinesisVideoStream);
+    pKinesisVideoStream->base.serviceCallContext.customData = TO_STREAM_HANDLE(pKinesisVideoStream);
     pKinesisVideoStream->base.serviceCallContext.timeout = SERVICE_CALL_DEFAULT_TIMEOUT;
     pKinesisVideoStream->base.serviceCallContext.callAfter = time;
 
@@ -584,7 +584,7 @@ STATUS executePutStreamState(UINT64 customData, UINT64 time)
 
     pKinesisVideoStream->base.serviceCallContext.pAuthInfo = &pKinesisVideoStream->streamingAuthInfo;
     pKinesisVideoStream->base.serviceCallContext.version = SERVICE_CALL_CONTEXT_CURRENT_VERSION;
-    pKinesisVideoStream->base.serviceCallContext.customData = TO_CUSTOM_DATA(pKinesisVideoStream);
+    pKinesisVideoStream->base.serviceCallContext.customData = TO_STREAM_HANDLE(pKinesisVideoStream);
     pKinesisVideoStream->base.serviceCallContext.timeout = SERVICE_CALL_DEFAULT_TIMEOUT;
     pKinesisVideoStream->base.serviceCallContext.callAfter = time;