668 lines
19 KiB
HTML
668 lines
19 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<title>ORKTask Protocol Reference</title>
|
|
|
|
<link rel="stylesheet" href="../css/style.css">
|
|
<meta name="viewport" content="initial-scale=1, maximum-scale=1.4">
|
|
<meta name="generator" content="appledoc 2.2.1 (build 1334)">
|
|
</head>
|
|
<body class="appledoc">
|
|
<header>
|
|
<div class="container" class="hide-in-xcode">
|
|
|
|
<h1 id="library-title">
|
|
<a href="../index.html">ResearchKit </a>
|
|
</h1>
|
|
|
|
<p id="developer-home">
|
|
<a href="../index.html">ResearchKit</a>
|
|
</p>
|
|
|
|
</div>
|
|
</header>
|
|
|
|
<aside>
|
|
<div class="container">
|
|
<nav>
|
|
<ul id="header-buttons" role="toolbar">
|
|
<li><a href="../index.html">Index</a></li>
|
|
<li><a href="../hierarchy.html">Hierarchy</a></li>
|
|
|
|
<li id="on-this-page" role="navigation">
|
|
<label>
|
|
On This Page
|
|
|
|
<div class="chevron">
|
|
<div class="chevy chevron-left"></div>
|
|
<div class="chevy chevron-right"></div>
|
|
</div>
|
|
|
|
<select id="jump-to">
|
|
<option value="top">Jump To…</option>
|
|
|
|
<option value="overview">Overview</option>
|
|
|
|
|
|
|
|
|
|
<option value="tasks">Tasks</option>
|
|
|
|
|
|
|
|
|
|
|
|
<optgroup label="Properties">
|
|
|
|
<option value="//api/name/identifier">identifier</option>
|
|
|
|
<option value="//api/name/providesBackgroundAudioPrompts">providesBackgroundAudioPrompts</option>
|
|
|
|
<option value="//api/name/requestedHealthKitTypesForReading">requestedHealthKitTypesForReading</option>
|
|
|
|
<option value="//api/name/requestedHealthKitTypesForWriting">requestedHealthKitTypesForWriting</option>
|
|
|
|
<option value="//api/name/requestedPermissions">requestedPermissions</option>
|
|
|
|
</optgroup>
|
|
|
|
|
|
|
|
|
|
|
|
<optgroup label="Instance Methods">
|
|
|
|
<option value="//api/name/progressOfCurrentStep:withResult:">- progressOfCurrentStep:withResult:</option>
|
|
|
|
<option value="//api/name/stepAfterStep:withResult:">- stepAfterStep:withResult:</option>
|
|
|
|
<option value="//api/name/stepBeforeStep:withResult:">- stepBeforeStep:withResult:</option>
|
|
|
|
<option value="//api/name/stepWithIdentifier:">- stepWithIdentifier:</option>
|
|
|
|
<option value="//api/name/validateParameters">- validateParameters</option>
|
|
|
|
</optgroup>
|
|
|
|
|
|
</select>
|
|
</label>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
</div>
|
|
</aside>
|
|
|
|
<article>
|
|
<div id="overview_contents" class="container">
|
|
<div id="content">
|
|
<main role="main">
|
|
<h1 class="title">ORKTask Protocol Reference</h1>
|
|
|
|
|
|
<div class="section section-specification"><table cellspacing="0"><tbody>
|
|
<tr>
|
|
<th>Conforms to</th>
|
|
<td>NSObject</td>
|
|
</tr><tr>
|
|
<th>Declared in</th>
|
|
<td>ORKTask.h</td>
|
|
</tr>
|
|
</tbody></table></div>
|
|
|
|
|
|
|
|
|
|
<div class="section section-overview">
|
|
<a title="Overview" name="overview"></a>
|
|
<h2 class="subtitle subtitle-overview">Overview</h2>
|
|
<p>The <code>ORKTask</code> protocol defines a task to be carried out by a participant
|
|
in a research study. To present the ResearchKit framework UI in your app, instantiate an
|
|
object that implements the <code>ORKTask</code> protocol (such as <a href="../Classes/ORKOrderedTask.html"><code>ORKOrderedTask</code></a>) and
|
|
provide it to an <a href="../Classes/ORKTaskViewController.html"><code>ORKTaskViewController</code></a> object.</p>
|
|
|
|
<p>Implement this protocol to enable dynamic selection of the steps for a given task.
|
|
By default, <a href="../Classes/ORKOrderedTask.html"><code>ORKOrderedTask</code></a> implements this protocol for simple sequential tasks.</p>
|
|
|
|
<p>Each step (<a href="../Classes/ORKStep.html"><code>ORKStep</code></a>) in a task roughly corresponds to one screen, and represents the
|
|
primary unit of work in any task presented by a task view controller. For example,
|
|
an <a href="../Classes/ORKQuestionStep.html"><code>ORKQuestionStep</code></a> object corresponds to a single question presented on screen,
|
|
together with controls the participant uses to answer the question. Another example is <a href="../Classes/ORKFormStep.html"><code>ORKFormStep</code></a>, which corresponds to a single
|
|
screen that displays multiple questions or items for which participants provide information, such as first name, last name, and birth date.</p>
|
|
|
|
<p>Each step corresponds to one
|
|
<a href="../Classes/ORKStepViewController.html"><code>ORKStepViewController</code></a> object, which may manage child view controllers in a particular
|
|
sequence. The correspondence of step to view controller holds even though some steps, such as <a href="../Classes/ORKVisualConsentStep.html"><code>ORKVisualConsentStep</code></a> and
|
|
<a href="../Classes/ORKConsentReviewStep.html"><code>ORKConsentReviewStep</code></a>, can produce multiple screens.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="section section-tasks">
|
|
<a title="Tasks" name="tasks"></a>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="task-list">
|
|
<div class="section-method">
|
|
<a name="//api/name/identifier" title="identifier"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/identifier"> identifier</a></code>
|
|
<span class="task-item-suffix">required method</span></h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>The unique identifier for this task.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>@property (nonatomic, copy, readonly) NSString *identifier</code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>The identifier should be a short string that identifies the task. The identifier is copied
|
|
into the <a href="../Classes/ORKTaskResult.html"><code>ORKTaskResult</code></a> objects generated by the task view controller for this
|
|
task. You can use a human-readable string for the task identifier
|
|
or a UUID; the exact string you use depends on your app.</p>
|
|
|
|
<p>In the case of apps whose tasks come from a server, the unique
|
|
identifier for the task may be in an external database.</p>
|
|
|
|
<p>The task view controller uses the identifier when constructing the task result.
|
|
The identifier can also be used during UI state restoration to identify the
|
|
task that needs to be restored.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/stepAfterStep:withResult:" title="stepAfterStep:withResult:"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/stepAfterStep:withResult:">– stepAfterStep:withResult:</a></code>
|
|
<span class="task-item-suffix">required method</span></h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>- (nullable ORKStep *)stepAfterStep:(nullable ORKStep *)<em>step</em> withResult:(ORKTaskResult *)<em>result</em></code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/stepBeforeStep:withResult:" title="stepBeforeStep:withResult:"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/stepBeforeStep:withResult:">– stepBeforeStep:withResult:</a></code>
|
|
<span class="task-item-suffix">required method</span></h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>- (nullable ORKStep *)stepBeforeStep:(nullable ORKStep *)<em>step</em> withResult:(ORKTaskResult *)<em>result</em></code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/stepWithIdentifier:" title="stepWithIdentifier:"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/stepWithIdentifier:">– stepWithIdentifier:</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>Returns the step that matches the specified <a href="../Protocols/ORKTask.html#//api/name/identifier">identifier</a>.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>- (nullable ORKStep *)stepWithIdentifier:(NSString *)<em>identifier</em></code></div>
|
|
|
|
|
|
|
|
<div class="method-subsection arguments-section parameters">
|
|
<h4 class="method-subtitle parameter-title">Parameters</h4>
|
|
<table class="argument-def parameter-def">
|
|
|
|
<tr>
|
|
<th scope="row" class="argument-name"><code>identifier</code></th>
|
|
<td><p>The <a href="../Protocols/ORKTask.html#//api/name/identifier">identifier</a> of the step to restore.</p></td>
|
|
</tr>
|
|
|
|
</table>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection return">
|
|
<h4 class="method-subtitle parameter-title">Return Value</h4>
|
|
<p>The step that matches the specified <a href="../Protocols/ORKTask.html#//api/name/identifier">identifier</a>.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>Implementing this method allows state restoration of a task
|
|
to a particular step. If you don’t implement this method, <a href="../Classes/ORKTaskViewController.html"><code>ORKTaskViewController</code></a> restores the state
|
|
to the first step of the task.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/progressOfCurrentStep:withResult:" title="progressOfCurrentStep:withResult:"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/progressOfCurrentStep:withResult:">– progressOfCurrentStep:withResult:</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>- (ORKTaskProgress)progressOfCurrentStep:(ORKStep *)<em>step</em> withResult:(ORKTaskResult *)<em>result</em></code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/validateParameters" title="validateParameters"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/validateParameters">– validateParameters</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>Validates the task parameters.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>- (void)validateParameters</code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>The implementation of this method should check that all the task parameters are correct. An invalid task
|
|
is considered an unrecoverable error: the implementation should throw an exception on parameter validation failure.
|
|
For example, the <a href="../Classes/ORKOrderedTask.html"><code>ORKOrderedTask</code></a> implementation makes sure that all its step identifiers are unique, throwing an
|
|
exception otherwise.</p>
|
|
|
|
<p>This method is usually called by a task view controller when its task is set.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/requestedHealthKitTypesForReading" title="requestedHealthKitTypesForReading"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/requestedHealthKitTypesForReading"> requestedHealthKitTypesForReading</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>The set of HealthKit types that steps in the task need to be able to
|
|
read. (read-only)</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>@property (nonatomic, copy, readonly, nullable) NSSet<HKObjectType*> *requestedHealthKitTypesForReading</code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>The value of this property is a set of <code>HKObjectType</code> values to request for reading from HealthKit during this task. After the last of the initial instruction steps, the task view controller
|
|
requests access to these HealthKit types.</p>
|
|
|
|
<p>To set this property, you can scan the steps in the task
|
|
and collate the HealthKit types that are requested by each active step, question, or
|
|
form step that has a Health answer format, and then include any additional types known
|
|
to be required. (Note that <a href="../Classes/ORKOrderedTask.html"><code>ORKOrderedTask</code></a> does something similar for this property.)</p>
|
|
|
|
<p>See also: <a href="../Protocols/ORKTask.html#//api/name/requestedHealthKitTypesForWriting"><code>requestedHealthKitTypesForWriting</code></a>.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/requestedHealthKitTypesForWriting" title="requestedHealthKitTypesForWriting"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/requestedHealthKitTypesForWriting"> requestedHealthKitTypesForWriting</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>The set of HealthKit types for which the task needs to request write access.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>@property (nonatomic, copy, readonly, nullable) NSSet<HKObjectType*> *requestedHealthKitTypesForWriting</code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>The requested <code>HKObjectType</code> values for writing can be returned by an extended task,
|
|
to request write access to these HealthKit types together with the read access
|
|
requested by the task view controller by calling <a href="../Protocols/ORKTask.html#//api/name/requestedHealthKitTypesForReading"><code>requestedHealthKitTypesForReading</code></a>.</p>
|
|
|
|
<p>See also: <a href="../Protocols/ORKTask.html#//api/name/requestedHealthKitTypesForReading"><code>requestedHealthKitTypesForReading</code></a>.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/requestedPermissions" title="requestedPermissions"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/requestedPermissions"> requestedPermissions</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>The set of permissions requested by the task.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>@property (nonatomic, readonly) ORKPermissionMask requestedPermissions</code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>By default in <a href="../Classes/ORKOrderedTask.html"><code>ORKOrderedTask</code></a> object, these permissions are collected from the
|
|
recorder configurations associated with the active steps in the task.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div><div class="section-method">
|
|
<a name="//api/name/providesBackgroundAudioPrompts" title="providesBackgroundAudioPrompts"></a>
|
|
<h3 class="method-title"><code><a href="#//api/name/providesBackgroundAudioPrompts"> providesBackgroundAudioPrompts</a></code>
|
|
</h3>
|
|
|
|
<div class="method-info">
|
|
<div class="pointy-thing"></div>
|
|
|
|
<div class="method-info-container">
|
|
|
|
|
|
<div class="method-subsection brief-description">
|
|
<p>A Boolean value indicating whether this task involves spoken audio prompts. (read-only)</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="method-subsection method-declaration"><code>@property (nonatomic, readonly) BOOL providesBackgroundAudioPrompts</code></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection discussion-section">
|
|
<h4 class="method-subtitle">Discussion</h4>
|
|
<p>If the value of this property is <code>YES</code>, the shared <code>AVAudioSession</code> is configured for playback in the background.
|
|
The audio <code>UIBackgroundMode</code> value must be set in the application’s <code>Info.plist</code> file
|
|
for this to be effective.</p>
|
|
|
|
<p>By default, this property looks for active steps that have
|
|
audio prompts or count down enabled, and returns <code>YES</code> if such steps exist in
|
|
the task.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div class="method-subsection declared-in-section">
|
|
<h4 class="method-subtitle">Declared In</h4>
|
|
<p><code class="declared-in-ref">ORKTask.h</code></p>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</main>
|
|
|
|
<footer>
|
|
<div class="footer-copyright">
|
|
|
|
<p class="copyright">Copyright © 2018 ResearchKit. All rights reserved. Updated: 2018-07-23</p>
|
|
|
|
|
|
<p class="generator">Generated by <a href="http://appledoc.gentlebytes.com">appledoc 2.2.1 (build 1334)</a>.</p>
|
|
|
|
</div>
|
|
</footer>
|
|
</div>
|
|
</div>
|
|
</article>
|
|
|
|
<script src="../js/script.js"></script>
|
|
</body>
|
|
</html> |