Add documentation and logging

10 files changed, 84 insertions, 30 deletions

diff --git a/SmartDeviceLink-iOS.xcodeproj/project.pbxproj b/SmartDeviceLink-iOS.xcodeproj/project.pbxproj
index 8a9fb7c50..55f311aba 100644
--- a/SmartDeviceLink-iOS.xcodeproj/project.pbxproj
+++ b/SmartDeviceLink-iOS.xcodeproj/project.pbxproj
@@ -990,7 +990,7 @@
 		5DBF0D601F3B3DB4008AF2C9 /* SDLControlFrameVideoStartServiceAckSpec.m in Sources */ = {isa = PBXBuildFile; fileRef = 5DBF0D5F1F3B3DB4008AF2C9 /* SDLControlFrameVideoStartServiceAckSpec.m */; };
 		5DC09EDA1F2F7FEC00F4AB1D /* SDLControlFramePayloadNakSpec.m in Sources */ = {isa = PBXBuildFile; fileRef = 5DC09ED91F2F7FEC00F4AB1D /* SDLControlFramePayloadNakSpec.m */; };
 		5DC978261B7A38640012C2F1 /* SDLGlobalsSpec.m in Sources */ = {isa = PBXBuildFile; fileRef = 5DC978251B7A38640012C2F1 /* SDLGlobalsSpec.m */; };
-		5DCD7AE01FCCA8D200A0FC7F /* SDLCarWindow.h in Headers */ = {isa = PBXBuildFile; fileRef = 5DCD7ADC1FCCA8D100A0FC7F /* SDLCarWindow.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		5DCD7AE01FCCA8D200A0FC7F /* SDLCarWindow.h in Headers */ = {isa = PBXBuildFile; fileRef = 5DCD7ADC1FCCA8D100A0FC7F /* SDLCarWindow.h */; };
 		5DCD7AE11FCCA8D200A0FC7F /* SDLCarWindow.m in Sources */ = {isa = PBXBuildFile; fileRef = 5DCD7ADD1FCCA8D200A0FC7F /* SDLCarWindow.m */; };
 		5DCD7AF31FCCA8E400A0FC7F /* SDLScreenshotViewController.h in Headers */ = {isa = PBXBuildFile; fileRef = 5DCD7AE61FCCA8E400A0FC7F /* SDLScreenshotViewController.h */; };
 		5DCD7AF71FCCA8E400A0FC7F /* SDLScreenshotViewController.m in Sources */ = {isa = PBXBuildFile; fileRef = 5DCD7AEA1FCCA8E400A0FC7F /* SDLScreenshotViewController.m */; };
diff --git a/SmartDeviceLink/SDLCarWindow.h b/SmartDeviceLink/SDLCarWindow.h
index e20459b25..28964d70e 100755
--- a/SmartDeviceLink/SDLCarWindow.h
+++ b/SmartDeviceLink/SDLCarWindow.h
@@ -11,8 +11,18 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ SDLCarWindow is a class somewhat mimicking a `UIWindow` in that it has a `UIViewController` root, but it takes that ViewController, listens for a start to Video Streaming, and streams whatever is on that view controller to the head unit.
+ */
 @interface SDLCarWindow : NSObject
 
+/**
+ Initialize the CarWindow automatic streamer.
+
+ @param streamManager The stream manager to use for retrieving head unit dimension details and forwarding video frame data
+ @param framesPerSecond The number of frames per second CarWindow should attempt to generate
+ @return An instance of this class
+ */
 - (instancetype)initWithStreamManager:(SDLStreamingMediaLifecycleManager *)streamManager targetFramerate:(NSUInteger)framesPerSecond;
 
 /**
diff --git a/SmartDeviceLink/SDLCarWindow.m b/SmartDeviceLink/SDLCarWindow.m
index 8a870ba1c..9d56ca80a 100755
--- a/SmartDeviceLink/SDLCarWindow.m
+++ b/SmartDeviceLink/SDLCarWindow.m
@@ -42,6 +42,8 @@ NS_ASSUME_NONNULL_BEGIN
     self = [super init];
     if (!self) { return nil; }
 
+    SDLLogD(@"Initializing Car Window automatic streaming with framerate: %lu", (unsigned long)framesPerSecond);
+
     _streamManager = streamManager;
     _targetFramerate = framesPerSecond;
 
@@ -64,10 +66,12 @@ NS_ASSUME_NONNULL_BEGIN
         }
         
         if (self.sameFrameCounter == 30 && ((displayLink.timestamp - self.lastMd5HashTimestamp) <= 0.1)) {
+            SDLLogD(@"Paused CarWindow, no frame changes in over a second");
             return;
         }
 
         if (self.isLockScreenMoving) {
+            SDLLogD(@"Paused CarWindow, lock screen moving");
             return;
         }
         
@@ -116,6 +120,8 @@ NS_ASSUME_NONNULL_BEGIN
         // If the video stream has started, we want to resize the streamingViewController to the size from the RegisterAppInterface
         self.rootViewController.view.frame = CGRectMake(0, 0, self.streamManager.screenSize.width, self.streamManager.screenSize.height);
         self.rootViewController.view.bounds = self.rootViewController.view.frame;
+
+        SDLLogD(@"Video stream started, setting CarWindow frame to: %@", NSStringFromCGRect(self.rootViewController.view.bounds));
         
         // And reset the frame counter (incase we are coming from a disconnect).
         self.sameFrameCounter = 0;
@@ -139,10 +145,7 @@ NS_ASSUME_NONNULL_BEGIN
 
         // And also reset the streamingViewController's frame, because we are about to show it.
         self.rootViewController.view.frame = [UIScreen mainScreen].bounds;
-        SDLLogW(@"Setting the view back: %@", NSStringFromCGRect(self.rootViewController.view.frame));
-        // If the stream stops, we pause and invalidate the displayLink (do we really need to do this? can we just pause it).
-        self.displayLink.paused = YES;
-        [self.displayLink invalidate];
+        SDLLogD(@"Video stream ended, setting view controller frame back: %@", NSStringFromCGRect(self.rootViewController.view.frame));
     });
 }
 
diff --git a/SmartDeviceLink/SDLFocusableItemLocator.h b/SmartDeviceLink/SDLFocusableItemLocator.h
index 017ee4fcd..7bfb31d3e 100644
--- a/SmartDeviceLink/SDLFocusableItemLocator.h
+++ b/SmartDeviceLink/SDLFocusableItemLocator.h
@@ -17,7 +17,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, assign) BOOL enableHapticDataRequests;
 
 /**
- The projection window associated with the Haptic Manager
+ The projection view controller associated with the Haptic Manager
  */
 @property (nonatomic, weak) UIViewController *viewController;
 
diff --git a/SmartDeviceLink/SDLFocusableItemLocatorType.h b/SmartDeviceLink/SDLFocusableItemLocatorType.h
index 8f2a06051..a8cd2b8b0 100644
--- a/SmartDeviceLink/SDLFocusableItemLocatorType.h
+++ b/SmartDeviceLink/SDLFocusableItemLocatorType.h
@@ -22,7 +22,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, assign) BOOL enableHapticDataRequests;
 
 /**
- The projection window associated with the Haptic Manager
+ The projection view controller associated with the Haptic Manager
  */
 @property (nonatomic, weak) UIViewController *viewController;
 
@@ -34,6 +34,12 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (instancetype)initWithWindow:(UIWindow *)window connectionManager:(id<SDLConnectionManagerType>)connectionManager __deprecated_msg("Use initWithViewController:connectionManager: instead");
 
+/**
+ Initializes the haptic interface. After initializing the application must call updateInterfaceLayout to process the view controller. Application must update later view changes in the view controller (or a change in the view controller itself) by sending the SDLDidUpdateProjectionView notification.
+
+ @param viewController UIViewController to be checked for focusable views
+ @param connectionManager Object of a class that implements ConnectionManagerType. This is used for RPC communication.
+ */
 - (instancetype)initWithViewController:(UIViewController *)viewController connectionManager:(id<SDLConnectionManagerType>)connectionManager;
 
 /**
diff --git a/SmartDeviceLink/SDLLockScreenPresenter.m b/SmartDeviceLink/SDLLockScreenPresenter.m
index bb114f629..dc578a8e5 100644
--- a/SmartDeviceLink/SDLLockScreenPresenter.m
+++ b/SmartDeviceLink/SDLLockScreenPresenter.m
@@ -8,6 +8,7 @@
 
 #import "SDLLockScreenPresenter.h"
 
+#import "SDLLogMacros.h"
 #import "SDLScreenshotViewController.h"
 #import "SDLStreamingMediaManagerConstants.h"
 
@@ -38,9 +39,9 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (void)present {
     NSArray* windows = [[UIApplication sharedApplication] windows];
-    UIWindow* mapWindow = windows.firstObject;
+    UIWindow* appWindow = windows.firstObject;
 
-    if (self.lockWindow.isKeyWindow || mapWindow == self.lockWindow) {
+    if (self.lockWindow.isKeyWindow || appWindow == self.lockWindow) {
         return;
     }
 
@@ -48,18 +49,19 @@ NS_ASSUME_NONNULL_BEGIN
     [[NSNotificationCenter defaultCenter] postNotificationName:SDLLockScreenManagerWillPresentLockScreenViewController object:nil];
 
     dispatch_async(dispatch_get_main_queue(), ^{
-        CGRect firstFrame = mapWindow.frame;
+        CGRect firstFrame = appWindow.frame;
         firstFrame.origin.x = CGRectGetWidth(firstFrame);
-        mapWindow.frame = firstFrame;
+        appWindow.frame = firstFrame;
 
-        // Take a screenshot of the mapWindow.
-        [(SDLScreenshotViewController*)self.lockWindow.rootViewController loadScreenshotOfWindow:mapWindow];
+        // Take a screenshot of the appWindow.
+        [(SDLScreenshotViewController*)self.lockWindow.rootViewController loadScreenshotOfWindow:appWindow];
 
-        // We then move the lockWindow to the original mapWindow location.
-        self.lockWindow.frame = mapWindow.bounds;
+        // We then move the lockWindow to the original appWindow location.
+        self.lockWindow.frame = appWindow.bounds;
         [self.lockWindow makeKeyAndVisible];
 
         // And present the lock screen.
+        SDLLogD(@"Present lock screen window");
         [self.lockWindow.rootViewController presentViewController:self.lockViewController animated:YES completion:^{
             // Tell ourselves we are done.
             [[NSNotificationCenter defaultCenter] postNotificationName:SDLLockScreenManagerDidPresentLockScreenViewController object:nil];
@@ -79,10 +81,11 @@ NS_ASSUME_NONNULL_BEGIN
     [[NSNotificationCenter defaultCenter] postNotificationName:SDLLockScreenManagerWillDismissLockScreenViewController object:nil];
 
     dispatch_async(dispatch_get_main_queue(), ^{
-        // Take a screenshot of the mapWindow.
+        // Take a screenshot of the appWindow.
         [(SDLScreenshotViewController*)self.lockWindow.rootViewController loadScreenshotOfWindow:appWindow];
 
         // Dismiss the lockscreen, showing the screenshot.
+        SDLLogD(@"Dismiss lock screen window");
         [self.lockViewController dismissViewControllerAnimated:YES completion:^{
             CGRect lockFrame = self.lockWindow.frame;
             lockFrame.origin.x = CGRectGetWidth(lockFrame);
@@ -102,16 +105,6 @@ NS_ASSUME_NONNULL_BEGIN
     return (self.lockViewController.isViewLoaded && (self.lockViewController.view.window || self.lockViewController.isBeingPresented) && self.lockWindow.isKeyWindow);
 }
 
-+ (UIViewController *)sdl_getCurrentViewController {
-    // http://stackoverflow.com/questions/6131205/iphone-how-to-find-topmost-view-controller
-    UIViewController *topController = [UIApplication sharedApplication].keyWindow.rootViewController;
-    while (topController.presentedViewController != nil) {
-        topController = topController.presentedViewController;
-    }
-
-    return topController;
-}
-
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/SmartDeviceLink/SDLProtocol.m b/SmartDeviceLink/SDLProtocol.m
index 186226414..2216df326 100644
--- a/SmartDeviceLink/SDLProtocol.m
+++ b/SmartDeviceLink/SDLProtocol.m
@@ -410,7 +410,7 @@ NS_ASSUME_NONNULL_BEGIN
                 SDLControlFramePayloadRPCStartServiceAck *startServiceACKPayload = [[SDLControlFramePayloadRPCStartServiceAck alloc] initWithData:startServiceACK.payload];
 
                 if (startServiceACKPayload.mtu != SDLControlFrameInt64NotFound) {
-                    [[SDLGlobals sharedGlobals] setDynamicMTUSize:startServiceACKPayload.mtu forServiceType:startServiceACK.header.serviceType];
+                    [[SDLGlobals sharedGlobals] setDynamicMTUSize:(NSUInteger)startServiceACKPayload.mtu forServiceType:startServiceACK.header.serviceType];
                 }
                 if (startServiceACKPayload.hashId != SDLControlFrameInt32NotFound) {
                     self.hashId = startServiceACKPayload.hashId;
diff --git a/SmartDeviceLink/SDLScreenshotViewController.h b/SmartDeviceLink/SDLScreenshotViewController.h
index 02cd9c778..4bb543647 100755
--- a/SmartDeviceLink/SDLScreenshotViewController.h
+++ b/SmartDeviceLink/SDLScreenshotViewController.h
@@ -7,8 +7,16 @@
 
 #import <UIKit/UIKit.h>
 
+/**
+ This class interacts with `SDLLockScreenPresenter`. It loads a screenshot of the app window and presents it on itself in an image view. This view controller is then presented on the lock window, which then presents the lock view controller over it.
+ */
 @interface SDLScreenshotViewController : UIViewController
 
+/**
+ Load a screenshot of the specified window into the image view on this class
+
+ @param window The window to take a screenshot of
+ */
 - (void)loadScreenshotOfWindow:(UIWindow *)window;
 
 @end
diff --git a/SmartDeviceLink/SDLStreamingMediaConfiguration.h b/SmartDeviceLink/SDLStreamingMediaConfiguration.h
index a8eacaaf1..75896c28b 100644
--- a/SmartDeviceLink/SDLStreamingMediaConfiguration.h
+++ b/SmartDeviceLink/SDLStreamingMediaConfiguration.h
@@ -49,6 +49,17 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (weak, nonatomic, nullable) UIWindow *window __deprecated_msg("Use rootViewController instead");
 
+/**
+ Set the initial view controller your video streaming content is within.
+
+ Activates the haptic view parser and CarWindow systems when set. This library will also use that information to attempt to return the touched view to you in `SDLTouchManagerDelegate`.
+
+ @note If you wish to alter this rootViewController while streaming via CarWindow, you must set a new `rootViewController` on `SDLStreamingMediaManager` and this will update both the haptic view parser and CarWindow.
+
+ @warning Apps using views outside of the `UIView` heirarchy (such as OpenGL) are currently unsupported. If you app uses partial views in the heirarchy, only those views will be discovered. Your OpenGL views will not be discoverable to a haptic interface head unit and you will have to manually make these views discoverable via the `SDLSendHapticData` RPC request.
+
+ @warning This is a weak property and it's therefore your job to hold a strong reference to this view controller.
+ */
 @property (weak, nonatomic, nullable) UIViewController *rootViewController;
 
 /**
@@ -69,6 +80,15 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (instancetype)initWithSecurityManagers:(nullable NSArray<Class<SDLSecurityType>> *)securityManagers encryptionFlag:(SDLStreamingEncryptionFlag)encryptionFlag videoSettings:(nullable NSDictionary<NSString *, id> *)videoSettings dataSource:(nullable id<SDLStreamingMediaManagerDataSource>)dataSource window:(nullable UIWindow *)window __deprecated_msg("Use initWithSecurityManagers:encryptionFlag:videoSettings:dataSource:rootViewController: instead");
 
+/**
+ Manually set all the properties to the streaming media configuration
+
+ @param securityManagers The security managers to use or nil for none.
+ @param encryptionFlag The maximum encrpytion supported. If the connected head unit supports less than set here, it will still connect, but if it supports more than set here, it will not connect.
+ @param videoSettings Custom video encoder settings to be used in video streaming.
+ @param rootViewController The UIViewController wih the content that is being streamed on, to use for haptics if needed and possible (only works for UIViews)
+ @return The configuration
+ */
 - (instancetype)initWithSecurityManagers:(nullable NSArray<Class<SDLSecurityType>> *)securityManagers encryptionFlag:(SDLStreamingEncryptionFlag)encryptionFlag videoSettings:(nullable NSDictionary<NSString *, id> *)videoSettings dataSource:(nullable id<SDLStreamingMediaManagerDataSource>)dataSource rootViewController:(nullable UIViewController *)rootViewController;
 
 /**
@@ -94,7 +114,21 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (instancetype)insecureConfiguration NS_SWIFT_UNAVAILABLE("Use the standard initializer instead");
 
+/**
+ Create a CarWindow insecure configuration with a view controller
+
+ @param initialViewController The initial view controller that will be streamed
+ @return The configuration
+ */
 + (instancetype)autostreamingInsecureConfigurationWithInitialViewController:(UIViewController *)initialViewController;
+
+/**
+ Create a CarWindow secure configuration with a view controller and security managers
+
+ @param securityManagers The security managers available for secure streaming use
+ @param initialViewController The initial view controller that will be streamed
+ @return The configuration
+ */
 + (instancetype)autostreamingSecureConfigurationWithSecurityManagers:(NSArray<Class<SDLSecurityType>> *)securityManagers initialViewController:(UIViewController *)initialViewController;
 
 @end
diff --git a/SmartDeviceLink/SDLStreamingMediaLifecycleManager.m b/SmartDeviceLink/SDLStreamingMediaLifecycleManager.m
index 95be5636c..a32eef96f 100644
--- a/SmartDeviceLink/SDLStreamingMediaLifecycleManager.m
+++ b/SmartDeviceLink/SDLStreamingMediaLifecycleManager.m
@@ -468,7 +468,7 @@ typedef void(^SDLVideoCapabilityResponseHandler)(SDLVideoStreamingCapability *_N
     SDLLogV(@"ACK: %@", audioAckPayload);
 
     if (audioAckPayload.mtu != SDLControlFrameInt64NotFound) {
-        [[SDLGlobals sharedGlobals] setDynamicMTUSize:audioAckPayload.mtu forServiceType:SDLServiceTypeAudio];
+        [[SDLGlobals sharedGlobals] setDynamicMTUSize:(NSUInteger)audioAckPayload.mtu forServiceType:SDLServiceTypeAudio];
     }
 
     [self.audioStreamStateMachine transitionToState:SDLAudioStreamStateReady];
@@ -482,7 +482,7 @@ typedef void(^SDLVideoCapabilityResponseHandler)(SDLVideoStreamingCapability *_N
     SDLLogV(@"ACK: %@", videoAckPayload);
 
     if (videoAckPayload.mtu != SDLControlFrameInt64NotFound) {
-        [[SDLGlobals sharedGlobals] setDynamicMTUSize:videoAckPayload.mtu forServiceType:SDLServiceTypeVideo];
+        [[SDLGlobals sharedGlobals] setDynamicMTUSize:(NSUInteger)videoAckPayload.mtu forServiceType:SDLServiceTypeVideo];
     }
 
     // This is the definitive screen size that will be used
@@ -762,7 +762,7 @@ typedef void(^SDLVideoCapabilityResponseHandler)(SDLVideoStreamingCapability *_N
     // If this fails we have no known formats to use
     if (self.preferredFormatIndex >= self.preferredFormats.count
         || self.preferredResolutionIndex >= self.preferredResolutions.count) {
-        SDLLogE(@"No preferred format or no preferred resolution found that works: format index %lu, resolution index %lu", self.preferredFormatIndex, self.preferredResolutionIndex);
+        SDLLogE(@"No preferred format or no preferred resolution found that works: format index %lu, resolution index %lu", (unsigned long)self.preferredFormatIndex, (unsigned long)self.preferredResolutionIndex);
         [self sdl_transitionToStoppedState:SDLServiceTypeVideo];
         return;
     }