DriveManager

DriveManager

The DriveManager object helps to organise the filesystem as virtual drives. Each virtual drive can be "mounted to" or "unmounted from" your application folder on-the-fly. Once mounted, the virual drive contents are accessible as a part of your application which means that your application can use Fetch API or "src" / "href" attributes from the same origin to access the contents the same way it normally uses integrated application assets.

Methods

createDrive(name, options) → {Promise.<module:DriveManager~Drive>}

Create a new virtual drive.

Parameters:
Name Type Description
name String

The unique virtual drive name
options Object

The options object: {readOnly: false}
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     const result = await agent.DriveManager.createDrive('drive1');

     console.log(result.name);

     //
     //    Will Print
     //
     //    "drive1"
     //
};

init();

deleteDrive(name)

Delete the virtual drive.

Parameters:
Name Type Description
name String

The unique virtual drive name
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     await agent.DriveManager.createDrive('drive1');

     const result1 = await agent.DriveManager.getDrives();

     console.log(result1);

     //
     //    Will Print
     //    [
     //        "drive1",
     //    ]
     //

     await agent.DriveManager.deleteDrive('drive1');

     const result2 = await agent.DriveManager.getDrives();

     console.log(result2);

     //
     //    Will Print
     //    [
     //
     //    ]
     //
};

init();

driveExists(name) → {Boolean}

Get the virtual drive by name.

Parameters:
Name Type Description
name String

The unique virtual drive name
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     const result = await agent.DriveManager.driveExists('random-drive-name');

     console.log(result);

     //
     //    Will Print
     //
     //    false
     //
};

init();

getDrive(name, mode) → {Promise.<module:DriveManager~Drive>}

Get the virtual drive by name.

Parameters:
Name Type Description
name String

The unique virtual drive name
mode Object

The mode object: {createIfNotFound: false}
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     const result = await agent.DriveManager.getDrive('drive1', {createIfNotFound: true});

     console.log(result.name);

     //
     //    Will Print
     //
     //    "drive1"
     //
};

init();

getDriveMountPaths(name) → {Promise.<Array.<String>>}

Get the list of virtual paths in the application virtual directory where the drive is mounted to

Parameters:
Name Type Description
name String

The unique virtual drive name
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     await agent.DriveManager.createDrive('drive1');

     await agent.DriveManager.mountDrive('drive1', '/media');
     await agent.DriveManager.mountDrive('drive1', 'assets/config');

     const result = await agent.DriveManager.getDriveMountPaths('drive1');

     console.log(result);

     //
     //    Will Print
     //    [
     //        "/media/",
     //        "/assets/config/",
     //    ]
     //
};

init();

getDrives() → {Promise.<Array.<String>>}

Get all the virtual drives available on the device.

Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     await agent.DriveManager.createDrive('drive1');
     await agent.DriveManager.createDrive('drive2');

     const result = await agent.DriveManager.getDrives();

     console.log(result);

     //
     //    Will Print
     //    [
     //        "drive1",
     //        "drive2",
     //    ]
     //
};

init();

getMountedDrives() → {Promise.<Array.<String>>}

Get all the virtual drives mounted to the current application folder.

Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     await agent.DriveManager.createDrive('drive1');
     await agent.DriveManager.createDrive('drive2');

     await agent.DriveManager.mountDrive('drive1', 'media');

     const result = await agent.DriveManager.getMountedDrives();

     console.log(result);

     //
     //    Will Print
     //    [
     //        "drive1",
     //    ]
     //
};

init();

mountDrive(name, path, mode) → {Promise.<module:DriveManager~Drive>}

Mount the drive into the application virtual directory. Even though this method works both in the emulator and in the device context - the emulator does not provide the local web server functionality. This emulator limitation means that if we need to request the file from the same origin (using for example Fetch API) using the mounted drive - then the file should be locally hosted together with other application assets. Please note that the MeldCX Agent running on the real device without emulation doesn't have such limitations.

Parameters:
Name Type Description
name String

The unique virtual drive name
path String

The relative path within the application where the drive should be mounted
mode Object

The mode object: {createIfNotFound: false}
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     const fileContents = new TextEncoder('utf8').encode(JSON.stringify({test: 'file'})).buffer;
     const drive1 = await agent.DriveManager.mountDrive('drive1', 'assets', {createIfNotFound: true});
     await drive1.fileSystem.createFile('/config/file.json', fileContents, 'application/json');

     // This works both in emulator and device context and doesn't require the drive to be mounted
     // Please note that we do not use the mount point "assets" here.
     // So we could have used the "getDrive" instead of the "mountDrive" with the same result:
     // const drive1 = await agent.DriveManager.getDrive('drive1', {createIfNotFound: true});
     const result1 = await drive1.fileSystem.readFileAsString('/config/file.json');

     console.log(result1);

     //
     //    Will Print
     //
     //    {"test": "file"}
     //

     // This works in the native MeldCX Agent context on the real device because we have the
     // drive mounted to the application virtual directory using the mount point "assets".
     // But this code will not automatically work in the MeldCX Emulator context because
     // emulator doesn't provide the local web server to host application file. For the full
     // test environment in the emulator context these additional assets have to be hosted
     // on your locally running web server.
     let result2 = await fetch(`${location.origin}/assets/config/file.json`);
     result2 = await result2.text();

     console.log(result2);

     //
     //    Will Print
     //
     //    {"test": "file"}
     //
};

init();

renameDrive(oldName, newName) → {Promise.<module:DriveManager~Drive>}

Change the unique name of the virtual drive.

Parameters:
Name Type Description
oldName String

The old virtual drive name
newName String

The new virtual drive name (should be unique)
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     await agent.DriveManager.createDrive('drive1');

     const result = await agent.DriveManager.renameDrive('drive1', 'drive2');

     console.log(result.name);

     //
     //    Will Print
     //
     //    "drive2"
     //
};

init();

unmountDrive(name, path, mode) → {Promise.<module:DriveManager~Drive>}

Unmount the drive from the application virtual directory. Even though this method works both in the emulator and in the device context - the emulator does not provide the local web server functionality. Please see the mountDrive() documentation for more information.

Parameters:
Name Type Description
name String

The unique virtual drive name
path String

The relative path within the application from which the drive should be unmounted
mode Object

The mode object: {createIfNotFound: false}
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     const fileContents = new TextEncoder('utf8').encode(JSON.stringify({test: 'file'})).buffer;
     const drive1 = await agent.DriveManager.mountDrive('drive1', 'assets', {createIfNotFound: true});
     await drive1.fileSystem.createFile('/config/file.json', fileContents, 'application/json');

     const result1 = await fetch(`${location.origin}/assets/config/file.json`);

     console.log(result1.ok);

     //
     //    Will Print
     //
     //    true
     //

     await agent.DriveManager.unmountDrive('drive1', 'assets');

     const result2 = await fetch(`${location.origin}/assets/config/file.json`);

     console.log(result2.ok);

     //
     //    Will Print
     //
     //    false
     //
};

init();

updateDrive(name, options, mode) → {Promise.<module:DriveManager~Drive>}

Update the existing virtual drive options.

Parameters:
Name Type Description
name String

The unique virtual drive name
options Object

The options object: {readOnly: false}
mode Object

The mode object: {createIfNotFound: false}
Example
import Agent from '@meldcx/agent';

const agent = new Agent();

const init = async() => {
     await agent.onReadyAsync();

     let result = await agent.DriveManager.createDrive('drive1', {readOnly: false});
     result = await agent.DriveManager.updateDrive('drive1', {readOnly: true});

     console.log(result.options);

     //
     //    Will Print
     //
     //    {
     //        "readOnly": true,
     //    }
     //
};

init();