Public Release 3.2.0

Author: sofia-apple

RELEASE-NOTES.md

@@ -1,5 +1,43 @@
 # ResearchKit Release Notes
 
+## ResearchKit 3.2.0 Release Notes
+### API Changes
+- **`ORKRecorderConfiguration`**
+Deprecated `recorder(for:outputDirectory:)` method in favor of setting the `outputDirectory` property when initializing `ORKConfiguration`, then calling its new `recorder(for:)` method. 
+
+### General bug fixes
+- **`ORKRecorder`**
+	- Fixed issue where results for active tasks using `ORKRecorder` did not account for all recorded files.
+	- Added file rolling as an API-level setting for `ORKRecorder` configuration.
+	- Added `timestampSince1970` for logged `CMLogItems` for better usability.
+
+- **Active Tasks**
+	- **Amsler Grid**
+		- Fixed issue where the names of the dat files created for the recorded data contained two periods.
+		- Fixed serialization issue preventing `ORKAmslerGridResult` from being properly serialized.
+
+	- **dBHL Tone Audiometry**
+		- Updated the current retSPL dBSPL tables for improved accuracy in audio-based active tasks.
+
+	- **Reaction Time**
+		- Fixed issue where all device motion files were not taken into account when reporting results.
+
+	- **Shoulder Range of Motion**
+		- Fixed issue where some instructions were not vocalized  during the task.
+
+	- **Spatial Span Memory**
+		- Fixed crash when serializing `ORKSpatialSpanMemoryGameTouchSample` objects.
+
+	- **Tremor Test**
+		- Fixed serialization issue preventing tremor test results from being properly serialized.
+
+- **`ORKFormStepViewController`**
+	- Fixed crash in `ORKFormStepViewController` that could occur during form step 
+navigation.
+
+- **`ORKCheckMarkView`**
+	- Fixed recursive crash that occurred when setting tint color on `ORKCheckMarkView` components.
+
 ## ResearchKit 3.1.1 Release Notes
 General bug fixes for the following:
 

ResearchKit.xcodeproj/project.pbxproj

@@ -122,12 +122,13 @@ ORK_CLASS_AVAILABLE
  @param url         The URL of the directory in which to place log files
  @param logName     The prefix on the log file name in an ASCII string. Note that
  the string must not contain the hyphen character ("-"), because a hyphen is used as a separator in the log naming scheme.
+ @param fileExtension    The file extension to use when creating files on disk.
  @param formatter   The type of formatter to use for the log, such as `ORKJSONLogFormatter`.
  @param delegate    The initial delegate. May be `nil`.
  
  @return An initialized data logger.
  */
-- (instancetype)initWithDirectory:(NSURL *)url logName:(NSString *)logName formatter:(ORKLogFormatter *)formatter delegate:(nullable id<ORKDataLoggerDelegate>)delegate NS_DESIGNATED_INITIALIZER;
+- (instancetype)initWithDirectory:(NSURL *)url logName:(NSString *)logName fileExtension:(NSString *)fileExtension formatter:(ORKLogFormatter *)formatter delegate:(nullable id<ORKDataLoggerDelegate>)delegate NS_DESIGNATED_INITIALIZER;
 
 /// The delegate to be notified when file sizes change or the log rolls over.
 @property (weak, nullable) id<ORKDataLoggerDelegate> delegate;
@@ -483,12 +484,13 @@ ORK_CLASS_AVAILABLE
  Adds a data logger with a particular formatter to the directory.
  
  @param logName     The log name prefix for the data logger.
+ @param fileExtension   The file extension to use when creating files on disk.
  @param formatter   The log formatter instance to use for this logger.
  
  @return The `ORKDataLogger` object that was added, or the existing one if one already existed for
  that log name.
  */
-- (ORKDataLogger *)addDataLoggerForLogName:(NSString *)logName formatter:(ORKLogFormatter *)formatter;
+- (ORKDataLogger *)addDataLoggerForLogName:(NSString *)logName fileExtension:(NSString *)fileExtension formatter:(ORKLogFormatter *)formatter;
 
 /**
  Retrieves the already existing data logger for a log name.

ResearchKit/Common/ORKDataLogger.h

@@ -73,25 +73,30 @@ - (void)resume;
 
 @implementation NSURL (ORKDataLogger)
 
+- (NSString *)ork_fileName {
+    NSString *fileName = [[self lastPathComponent] stringByDeletingPathExtension];
+    return fileName;
+}
+
 - (NSString *)ork_logName {
-    NSString *lastComponent = [self lastPathComponent];
-    NSRange idx = [lastComponent rangeOfString:@"-"];
+    NSString *fileName = [self ork_fileName];
+    NSRange idx = [fileName rangeOfString:@"-"];
     if (!idx.length) {
         @throw [NSException exceptionWithName:NSGenericException reason:@"URL is not a completed log file" userInfo:@{@"url":self}];
     }
 
-    NSString *logName = [lastComponent substringToIndex:idx.location];
+    NSString *logName = [fileName substringToIndex:idx.location];
     return logName;
 }
 
 - (NSString *)ork_logDateComponent {
-    NSString *lastComponent = [self lastPathComponent];
-    NSRange idx = [lastComponent rangeOfString:@"-"];
+    NSString *fileName = [self ork_fileName];
+    NSRange idx = [fileName rangeOfString:@"-"];
     if (!idx.length) {
         @throw [NSException exceptionWithName:NSGenericException reason:@"URL is not a completed log file" userInfo:@{@"url":self}];
     }
 
-    NSString *logDateComponent = [lastComponent substringFromIndex:idx.location + 1];
+    NSString *logDateComponent = [fileName substringFromIndex:idx.location + 1];
     return logDateComponent;
 }
 
@@ -145,8 +150,8 @@ - (NSString *)ork_logNameInDirectory:(NSURL *)directory {
         @throw [NSException exceptionWithName:NSGenericException reason:@"URL is not a fileURL" userInfo:@{@"url":self}];
     }
 
-    NSString *lastComponent = [self lastPathComponent];
-    NSRange idx = [lastComponent rangeOfString:@"-"];
+    NSString *fileName = [self ork_fileName];
+    NSRange idx = [fileName rangeOfString:@"-"];
     if (!idx.length) {
         @throw [NSException exceptionWithName:NSGenericException reason:@"URL is not a completed log file" userInfo:@{@"url":self}];
     }
@@ -155,7 +160,7 @@ - (NSString *)ork_logNameInDirectory:(NSURL *)directory {
         @throw [NSException exceptionWithName:NSGenericException reason:@"URL is not in expected directory" userInfo:@{@"url":self}];
     }
 
-    NSString *logName = [lastComponent substringToIndex:idx.location];
+    NSString *logName = [fileName substringToIndex:idx.location];
     return logName;
 }
 
@@ -446,6 +451,7 @@ @implementation ORKDataLogger {
     ORKObjectObserver *_observer;
 
     NSString *_oldLogsPrefix;
+    NSString *_fileExtension;
 
     NSFileHandle *_currentFileHandle;
 
@@ -457,7 +463,7 @@ @implementation ORKDataLogger {
 }
 
 + (ORKDataLogger *)JSONDataLoggerWithDirectory:(NSURL *)url logName:(NSString *)logName delegate:(id<ORKDataLoggerDelegate>)delegate {
-    return [[ORKDataLogger alloc] initWithDirectory:url logName:logName formatter:[ORKJSONLogFormatter new] delegate:delegate];
+    return [[ORKDataLogger alloc] initWithDirectory:url logName:logName fileExtension:@"json" formatter:[ORKJSONLogFormatter new] delegate:delegate];
 }
 
 + (instancetype)new {
@@ -468,7 +474,7 @@ - (instancetype)init {
     ORKThrowMethodUnavailableException();
 }
 
-- (instancetype)initWithDirectory:(NSURL *)url logName:(NSString *)logName formatter:(ORKLogFormatter *)formatter delegate:(id<ORKDataLoggerDelegate>)delegate {
+- (instancetype)initWithDirectory:(NSURL *)url logName:(NSString *)logName fileExtension:(NSString *)fileExtension formatter:(ORKLogFormatter *)formatter delegate:(id<ORKDataLoggerDelegate>)delegate {
     self = [super init];
     if (self) {
         _url = [url copy];
@@ -486,13 +492,13 @@ - (instancetype)initWithDirectory:(NSURL *)url logName:(NSString *)logName forma
         _queue = dispatch_queue_create([queueId cStringUsingEncoding:NSUTF8StringEncoding], DISPATCH_QUEUE_SERIAL);
 
         _directoryUpdateGroup = dispatch_group_create();
-        
+
         self.logName = logName;
         self.logFormatter = formatter;
         self.delegate = delegate;
         self.fileProtectionMode = ORKFileProtectionNone;
         _oldLogsPrefix = [_logName stringByAppendingString:@"-"];
-        
+        _fileExtension = fileExtension;
         _observer = [[ORKObjectObserver alloc] initWithObject:self keys:@[@"maximumCurrentLogFileLifetime", @"maximumCurrentLogFileSize"] selector:@selector(fileSizeLimitsDidChange)];
 
         [self setupDirectorySource];
@@ -506,7 +512,7 @@ - (instancetype)initWithDirectory:(NSURL *)url configuration:(NSDictionary *)con
         @throw [NSException exceptionWithName:NSGenericException reason:[NSString stringWithFormat:@"%@ is not a class", configuration[@"formatterClass"]] userInfo:nil];
     }
 
-    self = [self initWithDirectory:url logName:configuration[@"logName"] formatter:[[formatterClass alloc] init] delegate:delegate];
+    self = [self initWithDirectory:url logName:configuration[@"logName"] fileExtension:configuration[@"fileExtension"] formatter:[[formatterClass alloc] init] delegate:delegate];
     if (self) {
         // Don't notify about initial setup
         [_observer pause];
@@ -519,6 +525,7 @@ - (instancetype)initWithDirectory:(NSURL *)url configuration:(NSDictionary *)con
 
 - (NSDictionary *)configuration {
     return @{@"logName": self.logName,
+             @"fileExtension": _fileExtension,
              @"formatterClass": NSStringFromClass([self.logFormatter class]),
              @"fileProtectionMode": @(self.fileProtectionMode),
              @"maximumCurrentLogFileSize": @(self.maximumCurrentLogFileSize),
@@ -574,12 +581,18 @@ - (void)finishCurrentLog {
 }
 
 - (NSURL *)currentLogFileURL {
-    return [_url URLByAppendingPathComponent:_logName];
+    return [[_url URLByAppendingPathComponent:_logName] URLByAppendingPathExtension:_fileExtension];
 }
 
-- (BOOL)urlMatchesLogName:(NSURL *)url {
-    NSString *lastComponent = [url lastPathComponent];
-    return ([lastComponent isEqualToString:_logName] || [lastComponent hasPrefix:_oldLogsPrefix]);
+- (BOOL)doesURLMatchLogName:(NSURL *)url {
+    NSString *fileName = [url ork_fileName];
+    return [fileName isEqualToString:_logName];
+}
+
+- (BOOL)didCreateLogAt:(NSURL *)url {
+    BOOL doesURLMatchLogName = [self doesURLMatchLogName:url];
+    NSString *fileName = [url ork_fileName];
+    return (doesURLMatchLogName || [fileName hasPrefix:_oldLogsPrefix]);
 }
 
 - (NSFileHandle *)fileHandle {
@@ -724,10 +737,10 @@ - (BOOL)queue_enumerateLogs:(void (^)(NSURL *logFileUrl, BOOL *stop))block error
     NSError *error = nil;
     NSMutableArray *urls = [NSMutableArray array];
     for (NSURL *url in enumerator) {
-        if (![self urlMatchesLogName:url]) {
+        if (![self didCreateLogAt:url]) {
             continue;
         }
-        if ( [[url lastPathComponent] isEqualToString:_logName]) {
+        if ([self doesURLMatchLogName:url]) {
             // Don't include the "current" log file
             continue;
         }
@@ -839,7 +852,7 @@ - (NSFileHandle *)queue_fileHandleWithError:(NSError **)errorOut {
     return _currentFileHandle;
 }
 
-+ (NSURL *)nextUrlForDirectoryUrl:(NSURL *)directory logName:(NSString *)logName {
++ (NSURL *)nextUrlForDirectoryUrl:(NSURL *)directory logName:(NSString *)logName fileExtension:(NSString *)fileExtension {
     static NSDateFormatter *dateFromatter = nil;
     static dispatch_once_t onceToken;
     dispatch_once(&onceToken, ^{
@@ -849,14 +862,14 @@ + (NSURL *)nextUrlForDirectoryUrl:(NSURL *)directory logName:(NSString *)logName
     });
 
     NSString *datedLog = [NSString stringWithFormat:@"%@-%@",logName, [dateFromatter stringFromDate:[NSDate date]]];
-    NSURL *destinationUrl = [directory URLByAppendingPathComponent:datedLog];
+    NSURL *destinationUrl = [[directory URLByAppendingPathComponent:datedLog] URLByAppendingPathExtension:fileExtension];
 
     NSFileManager *fileManager = [NSFileManager defaultManager];
     int digit = 0;
     while ([fileManager fileExistsAtPath:[destinationUrl path] isDirectory:NULL]) {
         digit ++;
-        NSString *lastComponent = [datedLog stringByAppendingFormat:@"-%02d",digit];
-        destinationUrl = [directory URLByAppendingPathComponent:lastComponent];
+        NSString *newDatedLog = [datedLog stringByAppendingFormat:@"-%02d",digit];
+        destinationUrl = [[directory URLByAppendingPathComponent:newDatedLog] URLByAppendingPathExtension:fileExtension];
     }
 
     return destinationUrl;
@@ -878,7 +891,7 @@ - (void)queue_closeAndRenameLog {
 
     if (((NSNumber *)parameters[NSURLIsRegularFileKey]).boolValue) {
         if (((NSNumber *)parameters[NSURLFileSizeKey]).intValue > 0) {
-            NSURL *destinationUrl = [ORKDataLogger nextUrlForDirectoryUrl:_url logName:_logName];
+            NSURL *destinationUrl = [ORKDataLogger nextUrlForDirectoryUrl:_url logName:_logName fileExtension:_fileExtension];
             ORK_Log_Debug("Rollover: %@ to %@", [url lastPathComponent], [destinationUrl lastPathComponent]);
             [fileManager moveItemAtURL:url toURL:destinationUrl error:nil];
             if (self.fileProtectionMode == ORKFileProtectionCompleteUnlessOpen) {
@@ -1135,17 +1148,17 @@ - (void)configurationDidChange {
 }
 
 - (ORKDataLogger *)addJSONDataLoggerForLogName:(NSString *)logName {
-    return [self addDataLoggerForLogName:logName formatter:[ORKJSONLogFormatter new]];
+    return [self addDataLoggerForLogName:logName fileExtension:@"json" formatter:[ORKJSONLogFormatter new]];
 }
 
-- (ORKDataLogger *)queue_addDataLoggerForLogName:(NSString *)logName formatter:(ORKLogFormatter *)formatter {
-    ORKDataLogger *dataLogger = [[ORKDataLogger alloc] initWithDirectory:_directory logName:logName formatter:formatter delegate:self];
-    dataLogger.delegate = nil;
+- (ORKDataLogger *)queue_addDataLoggerForLogName:(NSString *)logName fileExtension:(NSString *)fileExtension formatter:(ORKLogFormatter *)formatter {
+    ORKDataLogger *dataLogger = [[ORKDataLogger alloc] initWithDirectory:_directory logName:logName fileExtension:fileExtension formatter:formatter delegate:self];
+    
     // Pick suitable defaults for a typical use pattern
     dataLogger.maximumCurrentLogFileLifetime = ORKDataLoggerManagerDefaultLogFileLifetime;
     dataLogger.maximumCurrentLogFileSize = ORKDataLoggerManagerDefaultLogFileSize;
     dataLogger.delegate = self;
-    
+
     _records[logName] = dataLogger;
     [self queue_synchronizeConfiguration];
 
@@ -1154,14 +1167,14 @@ - (ORKDataLogger *)queue_addDataLoggerForLogName:(NSString *)logName formatter:(
     return dataLogger;
 }
 
-- (ORKDataLogger *)addDataLoggerForLogName:(NSString *)logName formatter:(ORKLogFormatter *)formatter {
+- (ORKDataLogger *)addDataLoggerForLogName:(NSString *)logName fileExtension:(NSString *)fileExtension formatter:(ORKLogFormatter *)formatter {
     if (_records[logName]) {
         @throw [NSException exceptionWithName:NSInvalidArgumentException reason:[NSString stringWithFormat:@"Duplicate logger with log name '%@'",logName] userInfo:nil];
     }
 
     __block ORKDataLogger *dataLogger = nil;
     dispatch_sync(_queue, ^{
-        dataLogger = [self queue_addDataLoggerForLogName:logName formatter:formatter];
+        dataLogger = [self queue_addDataLoggerForLogName:logName fileExtension:fileExtension formatter:formatter];
     });
     return dataLogger;
 }

ResearchKit/Common/ORKDataLogger.m

@@ -55,6 +55,7 @@ - (instancetype)initWithIdentifier:(NSString *)identifier
         self.useCardView = YES;
         self.autoScrollEnabled = YES;
         self.cardViewStyle = ORKCardViewStyleDefault;
+        self.headerTextAlignment = NSTextAlignmentNatural;
     }
     return self;
 }

ResearchKit/Common/ORKFormStep.m

@@ -560,3 +560,24 @@ void ORKAdjustPageViewControllerNavigationDirectionForRTL(UIPageViewControllerNa
     return numberFormatter;
 }
 
+
+// MARK: - NSPredicate
+         
+NSPredicate* _Nullable ORKPredicateWithFormat(NSString * _Nonnull predicateFormat,
+                                              NSString * _Nonnull callerID) {
+    NSPredicate *predicate;
+    @try {
+        predicate = [NSPredicate predicateWithFormat:predicateFormat];
+    } @catch (NSException *exception) {
+        ORK_Log_Fault(
+            "%{public}@: Error creating predicate from predicateWithFormat string: \
+            '%{public}@' (error: %{public}@)",
+                      callerID,
+                      predicateFormat,
+                      [exception debugDescription]
+                      );
+        predicate = nil;
+    }
+    return predicate;
+}
+

ResearchKit/Common/ORKHelpers.m

@@ -421,3 +421,18 @@ ORKLocalizedHiddenString(key)
 [NSNumberFormatter localizedStringFromNumber:number numberStyle:NSNumberFormatterNoStyle]
 
 NS_ASSUME_NONNULL_END
+
+// MARK: - NSPredicate
+
+/**
+ This function attempts to create an `NSPredicate` from a predicate format `NSString`.
+ If this fails, an error message starting with the provided `callerID` `NSString` will be logged,
+ and the `NSPredicate` returned will be `nil`.
+ 
+ @param predicateFormat The `NSString` to attempt creating the `NSPredicate` from.
+ @param callerID An `NSString` identifying the calling class for error logging purposes.
+ 
+ @return An `NSPredicate` created from `predicateFormat` if the operation was successful, `nil` if not.
+ */
+NSPredicate* _Nullable ORKPredicateWithFormat(NSString * _Nonnull predicateFormat,
+                                              NSString * _Nonnull callerID);

ResearchKit/Common/ORKHelpers_Internal.h

@@ -43,13 +43,8 @@ - (instancetype)init {
 }
 
 - (nullable instancetype)initWithPredicateFormat:(NSString *)predicateFormat {
-    NSPredicate *predicate;
-    @try {
-        predicate = [NSPredicate predicateWithFormat:predicateFormat];
-    } @catch (NSException *exception) {
-        ORK_Log_Fault("ORKPredicateFormItemVisibilityRule: Error creating predicate from predicateFormat string: '%{public}@' (error: %{public}@)", predicateFormat, [exception debugDescription]);
-        predicate = nil;
-    }
+    NSPredicate *predicate = ORKPredicateWithFormat(predicateFormat, @"ORKPredicateFormItemVisibilityRule");
+    
     if (predicate != nil) {
         self = [self initWithPredicate:predicate];
         _predicateFormat = [predicateFormat copy];

ResearchKit/Common/ORKPredicateFormItemVisibilityRule.m

@@ -36,11 +36,16 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  To support deserialization, where deserialization of NSPredicates isn't supported, this class extension allows initializing
- an `ORKPredicateFormItemVisibilityRule` with a predicateFormat `NSString` instead of an `NSPredicate`
- and retains the original predicateFormat for serialization.
+ an `ORKPredicateFormItemVisibilityRule` with a `predicateFormat` `NSString` instead of an `NSPredicate`
+ and retains the original `predicateFormat` for serialization.
 */
 - (nullable instancetype)initWithPredicateFormat:(NSString *)predicateFormat;
 
+/**
+ To support deserialization, where deserialization of NSPredicates isn't supported, this class extension allows initializing
+ an `ORKPredicateFormItemVisibilityRule` with a `predicateFormat` `NSString` instead of an `NSPredicate`
+ and retains the original `predicateFormat` for serialization by setting this property.
+*/
 @property (nonatomic, nullable, copy, readonly) NSString *predicateFormat;
 
 @end