CARP Web Service Plugin for Flutter

A Flutter plugin to access the CARP Web Service API.

pub package

For Flutter plugins for other CARP products, see CARP Mobile Sensing in Flutter.

Note: This plugin is still under development, and some APIs might not be available yet. Feedback and Pull Requests are most welcome!

Setup

  1. You need a CARP Web Service host running. See the CARP Web Service API documentation for how to do this. If you're part of the CACHET team, you can use the specified development, staging, and production servers.

  2. Add carp_services as a dependency in your pubspec.yaml file.

Usage

import 'package:carp_webservices/carp_service/carp_service.dart';

Configuration

The CarpService is a singleton and needs to be configured once. Note that a valid Study with a valid study ID is needed.

final String uri = "http://staging.carp.cachet.dk:8080";

CarpApp app;
Study study;

study = new Study(testStudyId, "user@dtu.dk", name: "Test study #$testStudyId");
app = new CarpApp(
      study: study,
      name: "any_display_friendly_name_is_fine",
      uri: Uri.parse(uri),
      oauth: OAuthEndPoint(clientID: "the_client_id", clientSecret: "the_client_secret"));

CarpService.configure(app);

The singleton can then be accessed via CarpService.instance.

Authentication

Authentication is currently only supported using username and password.

CarpUser user;
try {
   user = await CarpService.instance.authenticate(username: "a_username", password: "the_password");
} catch (excp) {
   ...;
}

Data Points

A DataPointReference is used to manage data points on a CARP web service and have CRUD methods for:

  • post a data point
  • get a data point
  • delete data points
// Create a test location datum
LocationDatum datum = LocationDatum.fromMap(<String, dynamic>{
  "latitude": 23454.345,
  "longitude": 23.4,
  "altitude": 43.3,
  "accuracy": 12.4,
  "speed": 2.3,
  "speedAccuracy": 12.3
});

// create a CARP data point
final CARPDataPoint data = CARPDataPoint.fromDatum(study.id, study.userId, datum);
// post it to the CARP server, which returns the ID of the data point
data_point_id = await CarpService.instance.getDataPointReference().postDataPoint(data);

// get the data point back from the server
CARPDataPoint data = await CarpService.instance.getDataPointReference().getDataPoint(data_point_id);

// batch upload a list of raw json data points in a file
final File file = File("test/batch.json");
await CarpService.instance.getDataPointReference().batchPostDataPoint(file);

// delete the data point
await CarpService.instance.getDataPointReference().deleteDataPoint(data_point_id);

Application-specific Collections and Objects

A CollectionReference is used to manage collections on a CARP web service and have methods for:

  • creating, updating, and deleting objects
  • accessing objects in collections
// access an object 
//  - if the object id is not specified, a new object (with a new id) is created
//  - if the collection (users) don't exist, it is created
ObjectSnapshot object = await CarpService.instance
    .collection('/users')
    .object()
    .setData({'email': username, 'name': 'Administrator'});

// update the object
ObjectSnapshot updated_object = await CarpService.instance
    .collection('/users')
    .object(object.id)
    .updateData({'email': username, 'name': 'Super User'});

// get the object
ObjectSnapshot new_object = await CarpService.instance.collection('/users').object(object.id).get();

// delete the object
await CarpService.instance.collection('/users').object(object.id).delete();

// get all collections in the root
List<String> root = await CarpService.instance.collection("").collections;

// get all objects in a collection.
List<ObjectSnapshot> objects = await CarpService.instance.collection("/users").objects;

File Management

A FileStorageReference is used to manage files on a CARP web service and have methods for:

  • uploading a file
  • downloading a file
  • getting a file object
  • getting all file objects
  • deleting a file

When uploading a file, you can add metadata as a Map<String, String>.

// first upload a file
final File myFile = File("test/img.jpg");
final FileUploadTask uploadTask = CarpService.instance
   .getFileStorageReference()
   .upload(myFile, {'content-type': 'image/jpg', 'content-language': 'en', 'activity': 'test'});
CarpFileResponse response = await uploadTask.onComplete;
int id = response.id;

// then get its description back from the server
final CarpFileResponse result = await CarpService.instance.getFileStorageReference(id).get();

// then download the file again
// note that a local file to download is needed
final File myFile = File("test/img-$id.jpg");
final FileDownloadTask downloadTask = CarpService.instance.getFileStorageReference(id).download(myFile);
int response = await downloadTask.onComplete;

// now get references to ALL files in this study
final List<CarpFileResponse> results = await CarpService.instance.getFileStorageReference(id).getAll();

// finally, delete the file
final int result = await CarpService.instance.getFileStorageReference(id).delete();

Features and bugs

Please file feature requests and bug reports at the issue tracker.

License

This software is copyright (c) 2018 Copenhagen Center for Health Technology (CACHET) at the Technical University of Denmark (DTU). This software is made available 'as-is' in a MIT license.

Libraries

carp_auth
Contains classes for authentication to CARP.
carp_services

Dart

dart:ui
Built-in types and core primitives for a Flutter application. [...]

Core

dart:async
Support for asynchronous programming, with classes such as Future and Stream. [...]
dart:collection
Classes and utilities that supplement the collection support in dart:core. [...]
dart:convert
Encoders and decoders for converting between different data representations, including JSON and UTF-8. [...]
dart:core
Built-in types, collections, and other core functionality for every Dart program. [...]
dart:developer
Interact with developer tools such as the debugger and inspector. [...]
dart:math
Mathematical constants and functions, plus a random number generator. [...]
dart:typed_data
Lists that efficiently handle fixed sized data (for example, unsigned 8 byte integers) and SIMD numeric types. [...]

VM

dart:io
File, socket, HTTP, and other I/O support for non-web applications. [...]
dart:isolate
Concurrent programming using isolates: independent workers that are similar to threads but don't share memory, communicating only via messages. [...]