ORKResult Class Reference
| Inherits from | NSObject |
|---|---|
| Conforms to | NSCopying NSSecureCoding |
| Declared in | ORKResult.h |
The ORKResult class defines the attributes of a result from one step or a group
of steps. When you use the ResearchKit framework APIs, you typically get a result from the result property
of either ORKTaskViewController or ORKStepViewController.
Certain types of results can contain other results, which together express a hierarchy; examples of these types of results are ORKCollectionResult subclasses, such as ORKStepResult and ORKTaskResult.
When you receive a result, you can store it temporarily by archiving it with
NSKeyedArchiver, because all ORKResult objects implement NSSecureCoding. If you want to serialize the result object to other formats, you’re responsible for implementing this.
The result object hierarchy does not necessarily include all the data collected
during a task. Some result objects, such as ORKFileResult, may refer to files
in the filesystem that were generated during the task. These files are easy to find, because they are all
located in the output directory of the task view controller.
It’s recommended that you use NSFileProtectionComplete (at a minimum) to protect these files, and that you similarly protect all serialization of ORKResult objects that you write to disk. It is also generally helpful to keep the results together with the referenced files as you submit them to a back-end server. For example, it can be convenient to zip all data corresponding to a particular task result into a single compressed archive.
Every object in the result hierarchy has an identifier that should correspond
to the identifier of an object in the original step hierarchy. Similarly, every
object has a start date and an end date that correspond to the range of
times during which the result was collected. In an ORKStepResult object, for example,
the start and end dates cover the range of time during which the step view controller was visible on
screen.
When you implement a new type of step, it is usually helpful to create a new
ORKResult subclass to hold the type of result data the step can generate, unless it makes sense to use an existing subclass. Return your custom result subclass as one of the results attached to the step’s ORKStepResult object.
Other Methods
– initWithIdentifier:
Returns an initialized result using the specified identifier.
- (instancetype)initWithIdentifier:(NSString *)identifierParameters
identifier |
The unique identifier of the result. |
|---|
Discussion
Typically, objects such as ORKStepViewController and ORKTaskViewController instantiate result (and ORKResult subclass) objects; you seldom need to instantiate a result object in your code.
Declared In
ORKResult.h
identifier
A meaningful identifier for the result.
@property (nonatomic, copy) NSString *identifierDiscussion
The identifier can be used to identify the question that was asked or the task that was completed to produce the result. Typically, the identifier is copied from the originating object by the view controller or recorder that produces it.
For example, a task result receives its identifier from a task, a step result receives its identifier from a step, and a question result receives its identifier from a step or a form item. Results that are generated by recorders also receive an identifier that corresponds to that recorder.
Declared In
ORKResult.h
startDate
The time when the task, step, or data collection began.
@property (nonatomic, copy) NSDate *startDateDiscussion
The value of this property is set by the view controller or recorder that produces the result, to indicate when data collection started.
Note that for instantaneous items, startDate and endDate can have the same value, and should
generally correspond to the end of the instantaneous data collection period.
Declared In
ORKResult.h
endDate
The time when the task, step, or data collection stopped.
@property (nonatomic, copy) NSDate *endDateDiscussion
The value of this property is set by the view controller or recorder that produces the result, to indicate when data collection stopped.
Note that for instantaneous items, startDate and endDate can have the same value, and should
generally correspond to the end of the instantaneous data collection period.
Declared In
ORKResult.h
userInfo
Metadata that describes the conditions under which the result was acquired.
@property (nonatomic, copy, nullable) NSDictionary *userInfoDiscussion
The userInfo dictionary can be set by the view controller or recorder
that produces the result. However, it’s often a better choice to use a new ORKResult subclass for passing additional information back to code that uses
the framework, because using
typed accessors is safer than using a dictionary.
The user info dictionary must contain only keys and values that are suitable for property list or JSON serialization.
Declared In
ORKResult.h
Extension Methods
saveable
A boolean value indicating whether this result can be saved in a save and restore procedure.
@property (nonatomic, readonly, getter=isSaveable) BOOL saveableDiscussion
This is currently considered a private method, but overriding the getter in a result is the correct way to prevent this result being considered as saveable for the purpose of deciding whether to offer a “Save” option when the user cancels a task in progress.
ORKResult subclasses should return YES if they have data that the user
might want to be able to restore if the task were interrupted and later
resumed from the current state.
Declared In
ORKResult_Private.h