Version 1.2.0 alexa-client-sdk

Changes in this update
* **Enhancements**
  * Updated MediaPlayer to solve stability issues
  * All capability agents were refined to work with the updated MediaPlayer
  * Added the TemplateRuntime capability agent
  * Added the SpeakerManager capability agent
  * Added a configuration option ("sampleApp":"endpoint") that allows the endpoint that SampleApp connects to to be specified without changing code or rebuilding
  * Added very verbose capture of libcurl debug information
  * Added an observer interface to observer audio state changes from AudioPlayer
  * Added support for StreamMetadataExtracted Event. Stream tags found in the stream are represented in JSON and sent to AVS
  * Added to the SampleApp a simple GuiRenderer as an observer to the TemplateRuntime Capability Agent
  * Moved shared libcurl functionality to AVSCommon/Utils
  * Added a CMake option to exclude tests from the "make all" build. Use "cmake <absolute-path-to-source>
  -DACSDK_EXCLUDE_TEST_FROM_ALL=ON" to enable it. When this option is enabled "make unit" and "make integration" still could be used to build and run the tests

* **Bug fixes**:
  * Previously scheduled alerts now play following a restart
  * General stability fixes
  * Bug fix for CertifiedSender blocking forever if the network goes down while it's trying to send a message to AVS
  * Fixes for known issue of Alerts integration tests fail: AlertsTest.UserLongUnrelatedBargeInOnActiveTimer and AlertsTest.handleOneTimerWithVocalStop
  * Attempting to end a tap-to-talk interaction with the tap-to-talk button wouldn't work
  * SharedDataStream could encounter a race condition due to a combination of a blocking Reader and a Writer closing before writing any data
  * Bug-fix for the ordering of notifications within alerts scheduling. This fixes the issue where a local-stop on an alert would also stop a subsequent alert if it were to begin without delay

* **Known Issues**

* Capability agent for Notifications is not included in this release
* Inconsistent playback behavior when resuming content ("Alexa, pause." / "Alexa, resume."). Specifically, handling playback offsets, which causes the content to play from the start. This behavior is also occasionally seen with "Next" /
"Previous".
* `ACL`'s asynchronous receipt of audio attachments may manage resources poorly in scenarios where attachments are received but not consumed.

.clang-format

@@ -0,0 +1,102 @@
+---
+Language:        Cpp
+BasedOnStyle:  Google
+AccessModifierOffset: -4
+AlignAfterOpenBracket: AlwaysBreak
+#AlignConsecutiveAssignments: false
+#AlignConsecutiveDeclarations: false
+#AlignEscapedNewlines: Left
+#AlignOperands:   true
+#AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: false
+#AllowShortBlocksOnASingleLine: false
+#AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+#AllowShortIfStatementsOnASingleLine: true
+#AllowShortLoopsOnASingleLine: true
+#AlwaysBreakAfterDefinitionReturnType: None
+#AlwaysBreakAfterReturnType: None
+#AlwaysBreakBeforeMultilineStrings: true
+#AlwaysBreakTemplateDeclarations: true
+BinPackArguments: false
+BinPackParameters: false
+#BraceWrapping:   
+#  AfterClass:      false
+#  AfterControlStatement: false
+#  AfterEnum:       false
+#  AfterFunction:   false
+#  AfterNamespace:  false
+#  AfterObjCDeclaration: false
+#  AfterStruct:     false
+#  AfterUnion:      false
+#  BeforeCatch:     false
+#  BeforeElse:      false
+#  IndentBraces:    false
+#  SplitEmptyFunctionBody: true
+#BreakBeforeBinaryOperators: None
+#BreakBeforeBraces: Attach
+BreakBeforeInheritanceComma: true
+#BreakBeforeTernaryOperators: true
+#BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: AfterColon
+#BreakAfterJavaFieldAnnotations: false
+#BreakStringLiterals: true
+ColumnLimit:     120
+#CommentPragmas:  '^ IWYU pragma:'
+#CompactNamespaces: false
+#ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 8
+#ContinuationIndentWidth: 4
+#Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+#DisableFormat:   false
+#ExperimentalAutoDetectBinPacking: false
+#FixNamespaceComments: true
+#ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
+#IncludeCategories: 
+#  - Regex:           '^<.*\.h>'
+#    Priority:        1
+#  - Regex:           '^<.*'
+#    Priority:        2
+#  - Regex:           '.*'
+#    Priority:        3
+#IncludeIsMainRegex: '([-_](test|unittest))?$'
+#IndentCaseLabels: true
+IndentWidth:     4
+#IndentWrappedFunctionNames: false
+#JavaScriptQuotes: Leave
+#JavaScriptWrapImports: true
+#KeepEmptyLinesAtTheStartOfBlocks: false
+#MacroBlockBegin: ''
+#MacroBlockEnd:   ''
+#MaxEmptyLinesToKeep: 1
+#NamespaceIndentation: None
+#ObjCBlockIndentWidth: 2
+#ObjCSpaceAfterProperty: false
+#ObjCSpaceBeforeProtocolList: false
+#PenaltyBreakAssignment: 2
+#PenaltyBreakBeforeFirstCallParameter: 1
+#PenaltyBreakComment: 300
+#PenaltyBreakFirstLessLess: 120
+#PenaltyBreakString: 1000
+#PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 20000
+#PointerAlignment: Left
+#ReflowComments:  true
+SortIncludes:    false
+#SpaceAfterCStyleCast: false
+#SpaceAfterTemplateKeyword: true
+#SpaceBeforeAssignmentOperators: true
+#SpaceBeforeParens: ControlStatements
+#SpaceInEmptyParentheses: false
+#SpacesBeforeTrailingComments: 2
+#SpacesInAngles:  false
+#SpacesInContainerLiterals: true
+#SpacesInCStyleCastParentheses: false
+#SpacesInParentheses: false
+#SpacesInSquareBrackets: false
+#Standard:        Auto
+#TabWidth:        8
+#UseTab:          Never
+...
+

.gitignore

@@ -0,0 +1,7 @@
+#CLion project files
+.idea
+#config file required for SDK integration tests.  Each user will configure this differently, so it is preferable that git not show this file as
+#'untracked' when printing the status. 
+Integration/AuthDelegate.config
+#macOS specific files
+.DS_Store

ACL/CMakeLists.txt

@@ -4,4 +4,4 @@ project(ACL LANGUAGES CXX)
 include(../build/BuildDefaults.cmake)
 
 add_subdirectory("src")
-add_subdirectory("test")
+acsdk_add_test_subdirectory_if_allowed()

ACL/include/ACL/Transport/HTTP2Stream.h

@@ -25,13 +25,21 @@
 #include <string>
 
 #include <AVSCommon/AVS/Attachment/AttachmentManager.h>
+#include <AVSCommon/Utils/LibcurlUtils/CurlEasyHandleWrapper.h>
 #include <AVSCommon/AVS/MessageRequest.h>
 #include <AVSCommon/SDKInterfaces/MessageRequestObserverInterface.h>
 
-#include "ACL/Transport/CurlEasyHandleWrapper.h"
 #include "ACL/Transport/MimeParser.h"
 #include "ACL/Transport/MessageConsumerInterface.h"
 
+/// Whether or not curl logs should be emitted.
+#ifdef ACSDK_EMIT_SENSITIVE_LOGS
+
+#define ACSDK_EMIT_CURL_LOGS
+#include <fstream>
+
+#endif
+
 namespace alexaClientSDK {
 namespace acl {
 
@@ -165,14 +173,14 @@ class HTTP2Stream {
     bool setConnectionTimeout(const std::chrono::seconds timeoutSeconds);
 
     /**
-     * Resume network IO for this stream
+     * Un-pend all transfers for this stream
      */
-    void resumeNetworkIO();
+    void unPause();
 
     /**
-     * Return whether this stream is blocked on local IO
+     * Return whether this stream has pending transfers.
      */
-    bool isBlockedOnLocalIO() const;
+    bool isPaused() const;
 
     /**
      * Set the logical stream ID for this stream.
@@ -213,6 +221,45 @@ class HTTP2Stream {
      */
     bool setCommonOptions(const std::string& url, const std::string& authToken);
 
+    /**
+     * Helper function for calling @c curl_easy_setopt and checking the result.
+     *
+     * @param option The option parameter to pass through to curl_easy_setopt.
+     * @param optionName The name of the option to be set (for logging)
+     * @param param The param option to pass through to curl_easy_setopt.
+     * @return @c true of the operation was successful.
+     */
+    template <typename ParamType>
+    bool setopt(CURLoption option, const char* optionName, ParamType param);
+
+    /**
+     * Initialize capturing this streams activities in a log file.
+     */
+    void initStreamLog();
+
+#ifdef ACSDK_EMIT_CURL_LOGS
+
+    /**
+     * Callback that is invoked when @c libcurl has debug information to provide.
+     *
+     * @param handle @c libcurl handle of the transfer being reported upon.
+     * @param type The type of data being reported.
+     * @param data Pointer to the data being provided.
+     * @param size Size (in bytes) of the data being reported.
+     * @param user User pointer used to pass which HTTP2Stream is being reported on.
+     * @return Always returns zero.
+     */
+    static int debugFunction(CURL* handle, curl_infotype type, char* data, size_t size, void* user);
+
+    /// File to log the stream I/O to
+    std::unique_ptr<std::ofstream> m_streamLog;
+    /// File to dump data streamed in
+    std::unique_ptr<std::ofstream> m_streamInDump;
+    /// File to dump data streamed out
+    std::unique_ptr<std::ofstream> m_streamOutDump;
+
+#endif  // ACSDK_EMIT_CURL_LOGS
+
     /**
      * The logical id for this particular object instance.  (see note for @c m_streamIdCounter in this class).
      * @note This is NOT the actual HTTP/2 stream id.  Instead, this is an id which this class generates which is
@@ -221,19 +268,13 @@ class HTTP2Stream {
      */
     unsigned int m_logicalStreamId;
     /// The underlying curl easy handle.
-    CurlEasyHandleWrapper m_transfer;
+    avsCommon::utils::libcurlUtils::CurlEasyHandleWrapper m_transfer;
     /// An DirectiveParser instance used to parse multipart MIME messages.
     MimeParser m_parser;
     /// The current request being sent on this HTTP/2 stream.
     std::shared_ptr<avsCommon::avs::MessageRequest> m_currentRequest;
-    /// Whether the send operation has completed.
-    bool m_hasSendCompleted;
-    /// Whether send to network is blocked on local reads (i.e. awaiting new data to send).
-    bool m_isNetworkSendBlockedOnLocalRead;
-    /// Whether we have received any data
-    bool m_hasReceiveStarted;
-    /// Whether receive from network is blocked on local writes (i.e. buffer full).
-    bool m_isNetworkReceiveBlockedOnLocalWrite;
+    /// Whether this stream has any paused transfers.
+    bool m_isPaused;
     /**
      * The exception message being received from AVS by this stream.  It may be built up over several calls if either
      * the write quanta are small, or if the message is long.

ACL/include/ACL/Transport/HTTP2Transport.h

@@ -34,7 +34,7 @@
 
 #include "AVSCommon/SDKInterfaces/AuthDelegateInterface.h"
 #include "AVSCommon/SDKInterfaces/ContextManagerInterface.h"
-#include "ACL/Transport/CurlMultiHandleWrapper.h"
+#include "AVSCommon/Utils/LibcurlUtils/CurlMultiHandleWrapper.h"
 #include "ACL/Transport/HTTP2Stream.h"
 #include "ACL/Transport/HTTP2StreamPool.h"
 #include "ACL/Transport/MessageConsumerInterface.h"
@@ -337,7 +337,7 @@ class HTTP2Transport
     std::shared_ptr<HTTP2Stream> m_pingStream;
 
     /// Represents a CURL multi handle.
-    std::unique_ptr<CurlMultiHandleWrapper> m_multi;
+    std::unique_ptr<avsCommon::utils::libcurlUtils::CurlMultiHandleWrapper> m_multi;
 
     /// The list of streams that either do not have HTTP response headers, or have outstanding response data.
     std::map<CURL*, std::shared_ptr<HTTP2Stream>> m_activeStreams;