CarpService

Gives access to the CAWS-only ("non-core") endpoints: files, documents and collections.

Use it to store app resources (like JSON documents) or upload files for a study. It also exposes the legacy informed consent and data point endpoints, which are deprecated in CAWS.

Key points:

• The default constructor returns a shared instance; CarpService.instance creates a separately configured one. Call configure before use. Other services often copy its setup via CarpBaseService.configureFrom. Its requests still use the default CarpAuthService for authentication.
• Most methods take an optional studyId; if omitted, the study ID of study is used, or a CarpServiceException is thrown.
• Returns references (FileStorageReference, DocumentReference, CollectionReference) that do the actual reads and writes.

The CARP Core services are reached through CarpDeploymentService, CarpProtocolService, CarpParticipationService and CarpDataStreamService instead.

CarpService().configure(app, study);
final doc = CarpService().collection('activities').document('running');
await doc.setData({'distance': 5.2});

Inheritance

• Object
• CarpBaseService
• CarpService

Constructors

CarpService.instance

CarpService.instance()

Creates a new, separate instance (not the singleton).

CarpService

CarpService()

Returns the singleton default instance of the CarpService. Before this instance can be used, it must be configured using the configure method.

Properties

rpcEndpointName

1. @override

String get rpcEndpointName

override

The name of this service's RPC endpoint at CAWS, like deployment-service.

Methods

collection

CollectionReference collection(

1. String path, {
2. String? studyId,

})

Gets a CollectionReference for the path, like activities/running/geopositions.

studyId can be omitted if specified as part of this service's study.

createConsentDocument

1. @Deprecated('The Informed Consent endpoints are deprecated in CAWS. ' 'Informed Consent is uploaded as [InformedConsentInput] participant input ' 'data using a [ParticipationReference].')

Future<ConsentDocument> createConsentDocument(

1. Map<String, dynamic> document, {
2. String? studyDeploymentId,

})

Creates a new (signed) consent document.

Returns the created ConsentDocument if the document is uploaded correctly.

If studyDeploymentId is specified use this, otherwise use the study deployment id from CarpService.study.

dataPointReference

1. @Deprecated('The DataPoint endpoints is deprecated in CAWS. ' 'Data should be uploaded using the CARP-Core Data Stream endpoint.')

DataPointReference dataPointReference([

1. String? studyDeploymentId

])

Creates a DataPointReference for the study deployment with studyDeploymentId, or the deployment of study if omitted.

document

DocumentReference document(

1. String path, {
2. String? studyId,

})

Gets a DocumentReference for the specified path, like activities/running.

studyId can be omitted if specified as part of this service's study.

documentById

DocumentReference documentById(

1. int id, {
2. String? studyId,

})

Gets a DocumentReference for the specified unique id for study with id studyId.

studyId can be omitted if specified as part of this service's study.

documents

Future<List<DocumentSnapshot>> documents([

1. String? studyId

])

Gets all documents for the study with id studyId.

Can only be accessed by users who are authenticated as researchers.

Note that this might return a very long list of documents and the request may time out.

documentsByQuery

Future<List<DocumentSnapshot>> documentsByQuery(

1. String query, {
2. String? studyId,

})

Gets a list of documents based on a query.

The query string uses the RSQL query language for RESTful APIs. See the RSQL Documentation.

Can only be accessed by users who are authenticated as researchers.

getAllFiles

Future<List<CarpFileResponse>> getAllFiles([

1. String? studyId

])

Gets all file objects in the study.

studyId can be omitted if specified as part of this service's study.

getConsentDocument

1. @Deprecated('The Informed Consent endpoints are deprecated in CAWS. ' 'Informed Consent is uploaded as [InformedConsentInput] participant input ' 'data using a [ParticipationReference].')

Future<ConsentDocument> getConsentDocument(

1. int id, {
2. String? studyDeploymentId,

})

Gets a previously uploaded (signed) consent document with document id.

If studyDeploymentId is specified use this, otherwise use the study deployment id from CarpService.study.

getConsentDocumentEndpointUri

String getConsentDocumentEndpointUri([

1. String? studyDeploymentId

])

The URL of the legacy consent document endpoint for studyDeploymentId.

getDocumentEndpointUri

String getDocumentEndpointUri([

1. String? studyId

])

The URL of the document endpoint for the study with id studyId.

studyId can be omitted if specified as part of this service's study.

getFileEndpointUri

String getFileEndpointUri([

1. String? studyId

])

The URL of the file endpoint for the study with id studyId.

getFileStorageReference

FileStorageReference getFileStorageReference([

1. int id = -1,
2. String? studyId

])

Gets a FileStorageReference to the file with id in the study with id studyId.

Omit id (defaults to -1) for a file that is not uploaded yet. studyId can be omitted if specified as part of this service's study.

getFileStorageReferenceByName

Future<FileStorageReference?> getFileStorageReferenceByName(

1. String name, {
2. String? studyId,

})

Gets a FileStorageReference to the file with the original name name in the study with id studyId.

studyId can be omitted if specified as part of this service's study.

If more than one file with the same name exists, the first one is returned. If no files with that name exists, null is returned.

queryFiles

Future<List<CarpFileResponse>> queryFiles(

1. String? query, {
2. String? studyId,

})

Returns file objects in the study based on an RSQL query, like original_name==notes.txt.

studyId can be omitted if specified as part of this service's study. If query is null, all file objects are returned.