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
studiesor 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
-
- Object
- ClientManager<
Smartphone, SmartphoneRegistration, SmartphoneStudy> - SmartPhoneClientManager
- 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
DeviceDataCollectorto use to collect data locally on this primary device and this factory is used to createConnectedDeviceDataCollectorinstances 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
DeviceRegistrationhas 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
studywhich 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
protocoland 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
studyDeploymentIdanddeviceRoleNamefrom 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
studyfrom 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
getStudyDeploymentStatusfor 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
studyDeploymentIdanddeviceRoleNamefrom this client manager.override -
requestPermissions(
List< Permission> permissions) → Future<void> -
Asks the user for
permissionswith 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
studyDeploymentIdand 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
studyDeploymentIdanddeviceRoleName, 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