ORKRecorder Class Reference

Inherits from	NSObject
Declared in	ORKRecorder.h

A recorder is the runtime companion to an ORKRecorderConfiguration object, and is usually generated by one.

During active tasks, it is often useful to collect one or more pieces of data from sensors on the device. In research tasks, it’s not always necessary to display that data, but it’s important to record it in a controlled manner.

An active step (ORKActiveStep) has an array of recorder configurations (ORKRecorderConfiguration) that identify the types of data it needs to record for the duration of the step. When a step starts, the active step view controller instantiates a recorder for each of the step’s recorder configurations. The step view controller starts the recorder when the active step is started, and stops the recorder when the active step is finished.

The results of recording are typically written to a file specified by the value of the outputDirectory property.

Usually, the ORKActiveStepViewController object is the recorder’s delegate, and it receives callbacks when errors occur or when recording is complete.

Configuration

`identifier`

A short string that uniquely identifies the recorder (usually assigned by the recorder configuration).

@property (nonatomic, copy, readonly) NSString *identifier

Discussion

The identifier is reproduced in the results of a recorder created from this configuration. In fact, the only way to link a result (an ORKFileResult object) to the recorder that generated it is to look at the value of identifier. To accurately identify recorder results, you need to ensure that recorder identifiers are unique within each step.

In some cases, it can be useful to link the recorder identifier to a unique identifier in a database; in other cases, it can make sense to make the identifier human readable.

Declared In

ORKRecorder.h

`step`

The step that produced this recorder, configured during initialization.

@property (nonatomic, strong, readonly, nullable) ORKStep *step

Declared In

ORKRecorder.h

`configuration`

The configuration that produced this recorder.

@property (nonatomic, strong, readonly, nullable) ORKRecorderConfiguration *configuration

Declared In

ORKRecorder.h

`outputDirectory`

The file URL of the output directory configured during initialization.

@property (nonatomic, copy, readonly, nullable) NSURL *outputDirectory

Discussion

Typically, you set the outputDirectory property for the ORKTaskViewController object before presenting the task.

Declared In

ORKRecorder.h

`– logName`

Returns the log prefix for the log file.

- (nullable NSString *)logName

Declared In

ORKRecorder.h

Runtime Life Cycle

`– start`

Starts data recording.

- (void)start

Discussion

If an error occurs when recording starts, it is returned through the delegate.

Declared In

ORKRecorder.h

`– stop`

Stops data recording, which generally triggers the return of results.

- (void)stop

Discussion

If an error occurs when stopping the recorder, it is returned through the delegate. Subclasses should call finishRecordingWithError: rather than calling super.

Declared In

ORKRecorder.h

`recording`

A Boolean value indicating whether the recorder is currently recording.

@property (nonatomic, readonly, getter=isRecording) BOOL recording

Return Value

YES if the recorder is recording; otherwise, NO.

Declared In

ORKRecorder.h

Extension Methods

`– initWithIdentifier:step:outputDirectory:`

Returns an initialized recorder.

- (instancetype)initWithIdentifier:(NSString *)identifier step:(nullable ORKStep *)step outputDirectory:(nullable NSURL *)outputDirectory

Parameters

`identifier`	The unique identifier of the recorder.
`step`	The step for which this recorder is being created.
`outputDirectory`	The directory in which all output file data should be written (if producing `ORKFileResult` instances).

Return Value

An initialized recorder.

Discussion

This method is the designated initializer.

Declared In

ORKRecorder_Private.h

`– viewController:willStartStepWithView:`

A preparation step to provide viewController and view before record starting.

- (void)viewController:(UIViewController *)viewController willStartStepWithView:(nullable UIView *)view

Parameters

`viewController`	The view controller that is about to ‘start’
`view`	Primary active view for the step.

Discussion

The step view controller should call this method before starting the recorder, so that recorders that need a view or gesture recognizer in order to function can attach themselves.

Declared In

ORKRecorder_Private.h

`– finishRecordingWithError:`

Indicates that recording has failed; stop recording and report the error to the delegate

- (void)finishRecordingWithError:(nullable NSError *)error

Parameters

`error`	Error that occurred.

Declared In

ORKRecorder_Private.h

`– applyFileProtection:toFileAtURL:`

Helper for subclasses to request that file protection be applied to a file on disk.

- (void)applyFileProtection:(ORKFileProtectionMode)fileProtection toFileAtURL:(NSURL *)url

Parameters

`fileProtection`	Level of file protection desired
`url`	URL of file to protect.

Discussion

This method is exposed to facilitate unit testing.

Declared In

ORKRecorder_Private.h