SmartPhoneClientManager class

The main entry point of CARP Mobile Sensing (CAMS) on the phone.

A singleton that holds all studies running on this phone, deploys them via a DeploymentService, and gives one SmartphoneStudyController per study. An app calls configure once at startup, then adds studies with addStudyFromProtocol, addStudyFromInvitation or addStudy.

Key points:

  • configure must be called before adding studies. It initializes the infrastructure services, registers the built-in data managers, restores studies saved in earlier app runs and resumes their sampling.
  • Deploying a study (tryDeployment) does not resume its task controls. Use resume and pause to control sampling in all studies. (A connected device that connects does resume its own task controls.)
  • Permission requests go through requestPermissions, one at a time.
  • measurements merges the measurements of all studies on this phone.
  • Is a ChangeNotifier: listeners are notified when the list of studies or the sampling state changes. events emits ClientManagerState changes.

See also SmartphoneStudyController, which runs a single study, and DeviceController, which manages the devices on this phone.

await SmartPhoneClientManager().configure();
var study = await SmartPhoneClientManager().addStudyFromProtocol(protocol);
await SmartPhoneClientManager().tryDeployment(
  study.studyDeploymentId,
  study.deviceRoleName,
);
SmartPhoneClientManager().resume();
Inheritance
Mixed-in types

Constructors

SmartPhoneClientManager()
Returns the singleton SmartPhoneClientManager.
factory

Properties

askForPermissions → bool
Whether permissions are asked for automatically when a study is deployed.
no setter
dataCollectorFactory → DeviceDataCollectorFactory?
Determines which DeviceDataCollector to use to collect data locally on this primary device and this factory is used to create ConnectedDeviceDataCollector instances for connected devices.
no setterinherited
deploymentService → DeploymentService
The application service through which study deployments, to be run on this client, can be managed and retrieved.
no setterinherited
deviceController → DeviceController
The DeviceController that manages all devices on this phone.
no setter
events → Stream<ClientManagerState>
A stream of ClientManagerState events.
no setter
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
isConfigured → bool
Determines whether a DeviceRegistration has been configured for this client, which is necessary to start adding studies.
no setterinherited
measurements → Stream<Measurement>
All Measurements collected by all studies on this client.
no setter
notificationManager → NotificationManager
The NotificationManager that shows notifications for AppTasks.
no setter
proxy ↔ StudyDeploymentProxy?
Performs deployment calls for studies; created by configure.
getter/setter pairinherited
registration → SmartphoneRegistration
The registration of this client, set by configure.
no setterinherited
repository → ClientRepository<SmartphoneStudy>
Repository within which the state of this client is stored.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state ↔ ClientManagerState
The runtime state of this client manager.
getter/setter pair
studies → List<SmartphoneStudy>
Get the studies running on this client device.
no setterinherited

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
addStudy(SmartphoneStudy study) → Future<SmartphoneStudy>
Add a study which needs to be executed on this client. No deployment is attempted yet.
override
addStudyFromInvitation(ActiveParticipationInvitation invitation) → Future<SmartphoneStudy>
Adds a study based on an invitation, e.g. from a CARP server.
addStudyFromProtocol(StudyProtocol protocol, [String? studyDeploymentId]) → Future<SmartphoneStudy>
Creates a study deployment from protocol and adds it as a study.
configure({SmartphoneRegistration? registration, DeploymentService? deploymentService, DeviceDataCollectorFactory? dataCollectorFactory, bool enableNotifications = true, bool enableBackgroundMode = true, String? backgroundNotificationTitle, String? backgroundNotificationText, bool askForPermissions = true, PermissionRequester permissionRequester = requestPermissionsInOrder}) → Future<void>
Configures this SmartPhoneClientManager. Call once, before adding studies.
override
dispose() → void
Pauses and disposes all studies on this client.
override
getStudy(String studyDeploymentId, String deviceRoleName) → SmartphoneStudy?
Get the study with studyDeploymentId and deviceRoleName from this client manager. Returns null if no such study has been added.
inherited
getStudyController(SmartphoneStudy study) → SmartphoneStudyController?
Returns the SmartphoneStudyController for study.
getStudyDeploymentStatus(SmartphoneStudy study) → Future<StudyDeploymentStatus?>
Get the deployment status for the study from the deployment service. This updates the study's deployment status and sets the study's status accordingly. Returns null if the deployment status could not be retrieved from the deployment service or if the study has not been added to this client manager.
inherited
getStudyStatusList() → List<StudyStatus>
Get the status for the studies which run on this client device. Note that this is the latest known status, held locally. If you want an updated status from the deployment service, use getStudyDeploymentStatus for each study.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
pause() → void
Pauses data sampling in all studies on this client.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
removeStudy(String studyDeploymentId, String deviceRoleName) → Future<void>
Remove the study with studyDeploymentId and deviceRoleName from this client manager.
override
requestPermissions(List<Permission> permissions) → Future<void>
Asks the user for permissions with the configured PermissionRequester.
resume() → void
Restarts data sampling in all studies on this client.
stopStudy(String studyDeploymentId, String deviceRoleName) → Future<StudyStatus>
Permanently stop collecting data for the study with id studyDeploymentId and mark it as stopped.
override
toString() → String
A string representation of this object.
inherited
tryDeployment(String studyDeploymentId, String deviceRoleName) → Future<StudyStatus>
Verifies whether the device is ready for deployment of the study runtime identified by studyDeploymentId and deviceRoleName, and in case it is, deploys. Also runs for a study that is already deployed, to refresh its deployment information. Returns the study's status afterwards.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited