Skip to content
CARP Documentation

SmartphoneDeploymentService

A DeploymentService that runs locally on the phone and keeps deployments in memory.

Used when a study is deployed from a local SmartphoneStudyProtocol instead of from a server. It is the default deployment service in SmartPhoneClientManager.configure. Use a server-backed service, such as the one in carp_webservices, to get deployments from CARP.

Key points:

  • A singleton, accessed as SmartphoneDeploymentService().
  • Only accepts SmartphoneStudyProtocols.
  • Registers thisPhone as the primary device of every new deployment.
  • Deployments are not persisted, so they are lost when the app restarts. Running studies are restored by PersistenceService instead.
Implemented types

Constructors

SmartphoneDeploymentService

SmartphoneDeploymentService()

Get the singleton SmartphoneDeploymentService.

Properties

thisPhone

Smartphone thisPhone
getter/setter pair

The device configuration for this phone. Registered as the primary device of every deployment created by this service.

Methods

createStudyDeployment

Future<StudyDeploymentStatus> createStudyDeployment(
  1. StudyProtocol protocol, [
  2. List<ParticipantInvitation> invitations = const [],
  3. String? id,
  4. Map<String, DeviceRegistration>? connectedDevicePreregistrations,
])
override

Instantiate a study deployment for a given StudyProtocol with participants defined in invitations.

The identities specified in the invitations are used to invite and authenticate the participants. In case no account is associated to an identity, a new account is created for it. An invitation (and account details) is delivered to the person managing the identity, or should be handed out manually to the relevant participant by the person managing the identity.

id specifies the study deployment id. If not specified, an UUID v1 id is generated. connectedDevicePreregistrations lists optional pre-registrations for connected devices in the study protocol.

deployed

Future<StudyDeploymentStatus?> deployed(
  1. String studyDeploymentId, {
  2. DateTime? deviceDeploymentLastUpdateDate,
})

Marks the study deployment with studyDeploymentId as deployed successfully to this primary device (phone), i.e., that the study deployment was loaded on the device and that the necessary runtime is available to run it.

deviceDeployed

Future<StudyDeploymentStatus?> deviceDeployed(
  1. String studyDeploymentId,
  2. String primaryDeviceRoleName,
  3. DateTime? deviceDeploymentLastUpdatedOn
)
override

Indicate to stakeholders in the study deployment with studyDeploymentId that the device with primaryDeviceRoleName was deployed successfully, using the deployment with the specified deviceDeploymentLastUpdatedOn, i.e., that the study deployment was loaded on the device and that the necessary runtime is available to run it.

Returns null when:

  • a deployment with studyDeploymentId does not exist
  • primaryDeviceRoleName is not present in the deployment
  • the deviceDeploymentLastUpdatedOn does not match the expected date. The deployment might be outdated.
  • the deployment cannot be deployed yet, or the deployment has stopped.

getDeviceDeployment

Future<SmartphoneDeployment?> getDeviceDeployment(
  1. String studyDeploymentId
)

Returns the SmartphoneDeployment for studyDeploymentId for this phone (thisPhone), or null if the deployment is unknown.

getDeviceDeploymentFor

Future<SmartphoneDeployment?> getDeviceDeploymentFor(
  1. String studyDeploymentId,
  2. String primaryDeviceRoleName
)
override

Get the deployment configuration for the primary device with primaryDeviceRoleName in the study deployment with studyDeploymentId. Returns null if studyDeploymentId is not found.

getStudyDeploymentStatus

Future<StudyDeploymentStatus?> getStudyDeploymentStatus(
  1. String studyDeploymentId
)
override

Get the status for a study deployment with the given studyDeploymentId. Returns null if studyDeploymentId is not found.

getStudyDeploymentStatusList

Future<List<StudyDeploymentStatus?>> getStudyDeploymentStatusList(
  1. List<String> studyDeploymentIds
)
override

Get the statuses for a set of deployments with the specified studyDeploymentIds. Returns null for IDs in studyDeploymentIds for which no deployment exists.

registerDevice

Future<StudyDeploymentStatus?> registerDevice(
  1. String studyDeploymentId,
  2. String deviceRoleName,
  3. DeviceRegistration registration
)
override

Register the device with the specified deviceRoleName for the study deployment with studyDeploymentId.

registration is a matching configuration for the device with deviceRoleName. Returns null if studyDeploymentId is not found.

removeStudyDeployments

Future<Set<String>> removeStudyDeployments(
  1. Set<String> studyDeploymentIds
)
override

Remove study deployments with the given studyDeploymentIds. This also removes all data related to the study deployments.

Returns the IDs of study deployments which were removed (empty set if none were removed). IDs for which no study deployment exists are ignored.

stop

Future<StudyDeploymentStatus?> stop(
  1. String studyDeploymentId
)
override

Stops the study deployment with studyDeploymentId.

Returns null if the deployment is unknown.

toString

String toString()
override

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

unregisterDevice

Future<StudyDeploymentStatus?> unregisterDevice(
  1. String studyDeploymentId,
  2. String deviceRoleName
)
override

Unregister the device with the specified deviceRoleName for the study deployment with studyDeploymentId. Returns null if studyDeploymentId is not found.