Measurement Creation

Defined in dfx/api/MeasurementStreamAPI.hpp

Measurements are created using a MeasurementStream supported by both the WebSocket and gRPC transports.

Sending Chunk

With a valid Measurement obtained from dfx::api::MeasurementStreamAPI::setupStream payload chunks can be processed by the DFX Server.

std::shared_ptr<MeasurementStreamAPI> stream = cloud->measurementStream(config);
auto status = stream->setupStream(config, config.studyID);
 if ( status.OK() ) {
    stream->sendChunk(config, payloadBytes, isLast);
}

virtual CloudStatus dfx::api::MeasurementStreamAPI::sendChunk(const CloudConfig &config, const std::vector<uint8_t> &chunk, bool isLastChunk)

Asynchronously send a payload chunk to the server for processing.

Parameters

config – the connection configuration to use when sending the chunk.
chunk – the payload chunk of bytes obtained from DFX SDK.
isLastChunk – flag indicating if this is the last chunk for proper measurement completion.

Returns

status of the measurement connection, CLOUD_OK on SUCCESS

Measurement Completion

The proper way to complete a measurement is by identifying the last payload chunk in the sendChunk as true which will properly notify the server that it is processing the last chunk of a measurement.

After the final chunk has been sent though there will be a brief period while the server receives and finishes processing this final chunk. The best way to handle is to use the waitForCompletion method.

bool isLast = true;
auto status = stream->sendChunk(config, payloadBytes, isLast);

status = stream->waitForCompletion(config, 30*1000);    // Wait for up to 30 seconds
if ( status == CLOUD_TIMEOUT ) {
    stream->cancel(config);                             // Force the connection down
}

virtual CloudStatus dfx::api::MeasurementStreamAPI::waitForCompletion(const CloudConfig &config, int32_t timeoutMillis = 0)

Waits for the measurement connection to close ensuring that all results have been properly received.

In order for the server to properly close the connection when it has completed processing all the chunks, the last chunk needs to be flagged on the sendChunk call or this wait for completion may wait a very long time.

Parameters

config – the connection configuration to use when waiting.
timeoutMillis – the amount of time to wait for completion, zero is wait forever.

Returns

status of the measurement connection at close, CLOUD_OK on SUCCESS

Measurement Cancelling

It is possible to cancel a measurement which will notify the server and shutdown the internal asynchronous thread processing providing a proper cleanup of measurement resources.

stream->cancel(config);

virtual CloudStatus dfx::api::MeasurementStreamAPI::cancel(const CloudConfig &config)

cancel will inform the server that the Measurement should be terminated.

This will notify the server of the intent to cancel but leave all internal state setup to receive any final messages the server might wish to deliver.

Parameters: config – the connection configuration to use when cancelling.
Returns: status of operation, CLOUD_OK on SUCCESS