Storage Module API

The Logos Storage Module is a high-level C++ API built on Qt that provides file upload and download operations over the Logos Storage network. It underpins the Logos Storage UI App.

All methods return a LogosResult object containing a success boolean and a value (QVariant). Always check success before extracting the value:

LogosResult result = m_logos->storage_module.someOperation(args);
if (!result.success) {
    QString error = result.getError<QString>();
    // Or use the shorthand because the default error type is QString
    QString error = result.getError();
} else {
    auto value = result.getValue<ExpectedType>();
    // Or you can use shorthand
    QString value = result.getString();
}

Tip

The Logos Storage App Skeleton provides a ready-made entry point with access to the LogosModules object (m_logos) and Qt-compatible synchronization utilities.

---

Node Lifecycle

init(jsonConfig)

Initializes the storage module with the given JSON configuration.

const QString jsonConfig = "{}";
bool result = m_logos->storage_module.init(jsonConfig);

Parameter	Type	Description
jsonConfig	QString	JSON string with node configuration — see Configuration Reference

Caution

Do not call init() more than once per instance unless you call destroy(). Note that the result is a boolean in order to be compatible with Logos headless mode.

start()

Starts the storage node. Listen for the storageStart event for completion.

m_logos->storage_module.on("storageStart", [this](const QVariantList& data) {
    bool success = data[0].toBool();
    if (!success) {
        QString error = data[1].toString();
    }
});
bool result = m_logos->storage_module.start();

Returns: LogosResult

Event: storageStart — (bool success, QString message)

stop()

Stops the storage node.

LogosResult result = m_logos->storage_module.stop();

Event: storageStop

Caution

It is strongly recommended to stop the node before calling destroy() to prevent data loss.

destroy()

Frees all resources associated with the storage module.

LogosResult result = m_logos->storage_module.destroy();

---

Network Operations

peerId()

Returns the node’s libp2p peer identifier.

LogosResult result = m_logos->storage_module.peerId();
QString id = result.getValue<QString>();

spr()

Returns the node’s Signed Peer Record — a string encoding the node’s public key, network ID, and connection addresses.

LogosResult result = m_logos->storage_module.spr();
QString spr = result.getValue<QString>();

connect(peerId, peerAddresses)

Establishes a connection to another peer.

LogosResult result = m_logos->storage_module.connect(peerId, peerAddresses);

Parameter	Type	Description
peerId	QString	Target peer’s identifier
peerAddresses	QStringList	List of multiaddresses for the peer

Event: storageConnect

Caution

This API is currently unstable and might not work properly.

debug()

Returns node diagnostic data as JSON.

LogosResult result = m_logos->storage_module.debug();

QStringList addrs = result.getValue<QStringList>("addrs");
for (const QString& addr : addrs) {
    // Use the listen addr
}

QStringList announceAddresses = result.getValue<QStringList>("announceAddresses");
for (const QString& addr : announceAddresses) {
    // Use the announce address
}

QVariantMap table = result.getValue<QVariantMap>("table");
QVariantList nodes = table["nodes"].toList();

for (const QVariant& nodeVar : nodes) {
    QVariantMap node = nodeVar.toMap();
    QString peerId = node["peerId"].toString();
    bool seen = node["seen"].toBool();
    // ...
}

---

Publish/Download Operations

uploadUrl(url, chunkSize) — Simple Upload

Publishes a file from a local URL. This is the recommended approach for most use cases.

LogosResult result = m_logos->storage_module.uploadUrl(fileUrl);

// With optional chunk size
int chunkSize = 1024 * 64;
LogosResult result = m_logos->storage_module.uploadUrl(fileUrl, chunkSize);

Parameter	Type	Description
url	QUrl	Local file URL to publish
chunkSize	int	(Optional) Chunk size in bytes. Default: 65536

Event: storageUploadDone — (bool success, QString sessionId, QString cidOrError)

Event: storageUploadProgress — (bool success, QString sessionId, int bytesUploaded)

m_logos->storage_module.on("storageUploadDone", [this](const QVariantList& data) {
    bool success = data[0].toBool();
    QString sessionId = data[1].toString();
    QString cidOrError = data[2].toString();
});

m_logos->storage_module.on("storageUploadProgress", [this](const QVariantList& data) {
    bool success = data[0].toBool();
    QString sessionId = data[1].toString();
    int bytes = data[2].toInt();
});

Tip

This is the recommended way to upload a file.

uploadInit(filename, chunkSize) — Streaming Publish

Initializes a streaming session to publish a file, returning a session ID.

LogosResult result = m_logos->storage_module.uploadInit(filename);
QString sessionId = result.getValue<QString>();

// With optional chunk size
LogosResult result = m_logos->storage_module.uploadInit(filename, chunkSize);

Parameter	Type	Description
filename	QString	Name for the upload
chunkSize	int	(Optional) Chunk size in bytes

uploadChunk(sessionId, data)

Uploads a chunk of data for an active streaming session.

QFile file(filepath);
file.open(QIODevice::ReadOnly);
while (!file.atEnd()) {
    QByteArray chunk = file.read(chunkSize);
    result = m_logos->storage_module.uploadChunk(sessionId, chunk);
    if (!result.success) {
        // Handle error
    }
}

Parameter	Type	Description
sessionId	QString	Session ID from uploadInit
data	QByteArray	Chunk data

uploadFinalize(sessionId)

Completes a streaming upload and returns the CID.

LogosResult result = m_logos->storage_module.uploadFinalize(sessionId);
if (result.success) {
    QString cid = result.getValue<QString>();
}

uploadCancel(sessionId)

Aborts an active upload session.

LogosResult result = m_logos->storage_module.uploadCancel(sessionId);

Tip

This is an advanced API. It is recommended to use the uploadUrl api if it fits your needs.

---

downloadToUrl(cid, url, local, chunkSize) — File Download

Downloads content identified by CID to a local file.

LogosResult result = m_logos->storage_module.downloadToUrl(cid, destinationUrl);

// With optional parameters
bool local = false;
int chunkSize = 1024 * 64;
LogosResult result = m_logos->storage_module.downloadToUrl(cid, url, local, chunkSize);

Parameter	Type	Description
cid	QString	Content identifier
url	QUrl	Destination file URL
local	bool	(Optional) If true, only retrieve locally-cached data. Default: false
chunkSize	int	(Optional) Chunk size in bytes. Default: 65536

Event: storageDownloadProgress — (bool success, QString sessionId, int bytes)

Event: storageDownloadDone — (bool success, QString sessionId, QString errorMessage)

m_logos->storage_module.on("storageDownloadProgress", [this](const QVariantList& data) {
    bool success = data[0].toBool();
    QString sessionId = data[1].toString();
    int size = data[2].toInt();
});

m_logos->storage_module.on("storageDownloadDone", [this](const QVariantList& data) {
    bool success = data[0].toBool();
    QString message = data[1].toString();
});

downloadChunks(cid, local, chunkSize) — Streaming Download

Downloads content and receives chunks via events instead of writing to a file.

LogosResult result = m_logos->storage_module.downloadChunks(cid);

// With optional parameters
LogosResult result = m_logos->storage_module.downloadChunks(cid, local, chunkSize);

Parameter	Type	Description
cid	QString	Content identifier
local	bool	(Optional) Only retrieve locally-cached data. Default: false
chunkSize	int	(Optional) Chunk size in bytes. Default: 65536

downloadCancel(cid)

Aborts an active download.

LogosResult result = m_logos->storage_module.downloadCancel(cid);

manifests()

Lists all locally stored manifests.

LogosResult result = m_logos->storage_module.manifests();
if (result.success) {
    // Get first item value
    QString cid = result.getValue<QString>(0, "cid");
    QString treeCid = result.getValue<QString>(0, "treeCid");
    qint64 datasetSize = result.getValue<qint64>(0, "datasetSize");
    qint64 blockSize = result.getValue<qint64>(0, "blockSize");
    QString filename = result.getValue<QString>(0, "filename");
    QString mimetype = result.getValue<QString>(0, "mimetype");
}

downloadManifest(cid)

Fetches metadata for a given CID.

LogosResult result = m_logos->storage_module.downloadManifest(cid);

LogosResult result = manifests();

if (result.success) {
    QString cid = result.getValue<QString>("cid");
    QString treeCid = result.getValue<QString>("treeCid");
    qint64 datasetSize = result.getValue<qint64>("datasetSize");
    qint64 blockSize = result.getValue<qint64>("blockSize");
    QString filename = result.getValue<QString>("filename");
    QString mimetype = result.getValue<QString>("mimetype");
}

---

Storage Management

exists(cid)

Checks whether a CID exists in local storage.

LogosResult result = m_logos->storage_module.exists(cid);

fetch(cid)

Triggers a background network retrieval for the given CID.

LogosResult result = m_logos->storage_module.fetch(cid);

Caution

This operation is done in the background, i.e., no event is emitted upon completion.

remove(cid)

Deletes content from local storage.

LogosResult result = m_logos->storage_module.remove(cid);

space()

Returns storage usage statistics.

LogosResult result = m_logos->storage_module.space();
if (result.success) {
    int totalBlocks = result.getValue<int>("totalBlocks");
    int quotaMaxBytes = result.getValue<int>("quotaMaxBytes");
    int quotaUsedBytes = result.getValue<int>("quotaUsedBytes");
    int quotaReservedBytes = result.getValue<int>("totalBlocks");
}

---

Configuration

updateLogLevel(level)

Updates the runtime log level.

LogosResult result = m_logos->storage_module.updateLogLevel("INFO");

Supported levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR, FATAL

version()

Returns version information for the module.

LogosResult result = m_logos->storage_module.version();
QString ver = result.getValue<QString>();

---

Events Reference

All asynchronous operations emit Events managed by the Logos SDK. Subscribe using on():

Event	Parameters	Emitted By
storageStart	(bool success, QString message)	start()
storageStop	(bool success)	stop()
storageConnect	(bool success, QString message)	connect()
storageUploadDone	(bool success, QString sessionId, QString cidOrError)	uploadUrl(), uploadFinalize()
storageUploadProgress	(bool success, QString sessionId, int bytes)	uploadUrl(), uploadChunk()
storageDownloadDone	(bool success, QString sessionId, QString message)	downloadToUrl(), downloadChunks()
storageDownloadProgress	(bool success, QString sessionId, int bytes)	downloadToUrl(), downloadChunks()

Tip

Progress events fire frequently. Use thresholds before updating the UI to prevent blocking.