Blob

Types

Enumerates

type EVP_BLOB_TYPE

An integer constant for specifying the type of storage service.

Values:

enumerator EVP_BLOB_TYPE_AZURE_BLOB

Value:

0

A blob stored in an Azure storage container.

enumerator EVP_BLOB_TYPE_EVP

Value:

1

[deprecated] A blob stored in the EVP storage provider. EVP_BLOB_TYPE_EVP_EXT can be used instead of this type.

enumerator EVP_BLOB_TYPE_HTTP

Value:

2

A blob provided by an ordinary HTTP server. Only EVP_BLOB_OP_GET operation is supported.

enumerator EVP_BLOB_TYPE_EVP_EXT

Value:

3

A blob stored in the EVP storage provider. User can select the storage based on data type.

enumerator EVP_BLOB_TYPE_HTTP_EXT

Value:

4

A blob provided by an ordinary HTTP server. Only EVP_BLOB_OP_GET operation is supported. Allows to pass extra headers for the HTTP request.

type EVP_BLOB_OPERATION

An integer constant for specifying the blob operation.

Values:

enumerator EVP_BLOB_OP_GET

Value:

0

Operation GET a blob from the storage service.

enumerator EVP_BLOB_OP_PUT

Value:

1

Operation PUT a blob into the storage service.

type EVP_BLOB_IO_RESULT

The type to represent an outcome of a blob IO callback.

Values:

enumerator EVP_BLOB_IO_RESULT_SUCCESS

Value:

0

The operation completed successfully.

enumerator EVP_BLOB_IO_RESULT_ERROR

Value:

1

The operation failed.

type EVP_BLOB_RESULT

The type to represent an outcome of a blob operation.

Values:

enumerator EVP_BLOB_RESULT_SUCCESS

Value:

0

The operation completed successfully.

enumerator EVP_BLOB_RESULT_ERROR

Value:

1

The operation failed.

enumerator EVP_BLOB_RESULT_ERROR_HTTP

Value:

2

The operation failed with a valid HTTP status.

type EVP_BLOB_CALLBACK_REASON

The type to represent the reason of the callback invocation.

Values:

enumerator EVP_BLOB_CALLBACK_REASON_DONE

Value:

0

I/O completion, either success or error.

enumerator EVP_BLOB_CALLBACK_REASON_EXIT

Value:

1

Cancelled or rejected because the requesting Module Instance is going to exit. Users must not send any more requests to the agent when this code is received, and instead users must call ref EVP_processEvent until all events are flushed.

enumerator EVP_BLOB_CALLBACK_REASON_DENIED

Value:

2

A request was denied for transmission. This means the agent could not enqueue the request due to a full queue.

Structures

struct EVP_BlobLocalStore

A blob operation local store: file or memory

const char *filename

An absolute path of a local file to operate on. There are restrictions on the filename:

• It should be in the workspace directory for the module instance with type EVP_WORKSPACE_TYPE_DEFAULT.

• It shouldn’t contain parent directory references. (..)

• It shouldn’t involve symbolic links.

• It shouldn’t end with a slash.

• It shouldn’t contain redundant consecutive slashes. (E.g. //path///like////this)

EVP_BLOB_IO_CALLBACK io_cb

Callback to process partial IO data.

Warning

This functionality is provided as a solution for a particular use case.

Warning

Right now, this functionality is available only for NuttX.

This field is ignored if filename is not NULL.

The callback is invoked for each chunk in the blob. The chunk sizes are decided by the SDK automatically. The callback should not assume any specific sizes.

The callback is called sequentionally from the start of the blob (smaller offset) to the end of the blob. If a callback needs to know the current offset in the blob, the callback should keep track of it by itself, probably using userData.

Warning

The callback should return as soon as possible because otherwise it would interfere the entire device, not only the calling module instance. It’s recommended for the callback to copy the data to some application specific buffer and return without any extra processing.

size_t blob_len

The length of the blob to upload This field is only used when all conditions below are satisfied:

• filename is NULL

• PUT operations (type = EVP_BLOB_OP_PUT)

Azure blobs

struct EVP_BlobRequestAzureBlob

A blob operation request for Azure Blob Storage.

const char *url

Shared Access Signature URL for the blob.

• EVP_BLOB_OP_GET requires Read (r) permission.

• EVP_BLOB_OP_PUT requires Create (c) and/or Write (w) permission.

See Create Storage Service.

struct EVP_BlobResultAzureBlob

A blob operation result for Azure Blob Storage.

EVP_BLOB_RESULT result

The result of the blob operation.

unsigned int http_status

An HTTP status code.

int error

An errno value. Only valid for EVP_BLOB_RESULT_ERROR.

EVP blobs

struct EVP_BlobRequestEvp

Deprecated since version 1.0.0.

A blob operation request for EVP Storage Provider.

const char *remote_name

The unique string to identify this blob.

Consult the documentation of the EVP Storage Provider how this string is actually used.

struct EVP_BlobRequestEvpExt

A blob operation request for EVP Storage Provider.

const char *remote_name

The unique string to identify file name to upload.

Consult the documentation of the EVP Storage Provider how this string is actually used.

const char *storage_name

The unique string to identify the blob storage based on data type.

This parameter must be NULL to use the default STP or the same string as configured in EVP Hub when user create storage.

When this parameter is NULL, a file will be uploaded to the default EVP storage. This will be same behavior as EVP_BLOB_TYPE_EVP.

Consult the documentation of the EVP Storage Provider how this string is actually used.

Note

This member corresponds to the key field of the target STP configured in the Cloud API.

struct EVP_BlobResultEvp

A blob operation result for EVP Storage Provider.

EVP_BLOB_RESULT result

The result of the blob operation.

unsigned int http_status

An HTTP status code.

int error

An errno value. Only valid for EVP_BLOB_RESULT_ERROR.

HTTP blobs

struct EVP_BlobRequestHttp

A blob operation request for ordinary HTTP server.

const char *url

URL for the blob.

struct EVP_BlobResultHttp

A blob operation result for HTTP server.

EVP_BLOB_RESULT result

The result of the blob operation.

unsigned int http_status

An HTTP status code.

int error

An errno value. Only valid for EVP_BLOB_RESULT_ERROR.

HTTP Extended blobs

struct EVP_BlobRequestHttpExt

A blob operation request for ordinary HTTP server, supporting extra headers.

struct EVP_BlobResultHttpExt

A blob operation result for HTTP server.

EVP_BLOB_RESULT result

The result of the blob operation.

unsigned int http_status

An HTTP status code.

int error

An errno value. Only valid for EVP_BLOB_RESULT_ERROR.

Callbacks

typedef EVP_BLOB_IO_RESULT (*EVP_BLOB_IO_CALLBACK)(void *buf, size_t buflen, void *userData)

Function prototype for the callback passed to

EVP_BlobLocalStore

parameters:

• buf - The buffer with the contents.

• buflen - The length of the buffer.

• userData - The userData value specified for EVP_blobOperation().

typedef void (*EVP_BLOB_CALLBACK)(EVP_BLOB_CALLBACK_REASON reason, const void *result, void *userData)

Function prototype for the callback passed to the function EVP_blobOperation().

parameters:

• reason - One of EVP_BLOB_CALLBACK_REASON values.

• result - The result of the operation.

  Valid only when reason is EVP_BLOB_CALLBACK_REASON_DONE. The type of the result depends on the request’s type and op.

  It is a pointer to:

  • EVP_BlobResultAzureBlob for EVP_BLOB_TYPE_AZURE_BLOB.

  • EVP_BlobResultEvp for EVP_BLOB_TYPE_EVP.

  • EVP_BlobResultEvp for EVP_BLOB_TYPE_EVP_EXT.

• userData - The userData value specified for EVP_blobOperation().

Functions

EVP_RESULT EVP_blobOperation(struct EVP_client *h, EVP_BLOB_TYPE type, EVP_BLOB_OPERATION op, const void *request, struct EVP_BlobLocalStore *localStore, EVP_BLOB_CALLBACK cb, void *userData)

Schedule a blob operation

Enqueues the specified operation op on a blob of the given type which is described by request, linking it to the given data specified by localStore

Parameters:

• h – Client object pointer.

• type – Blob type

• op – Whether to GET or PUT the blob.

• request –

  A pointer to a structure to specify request parameters.

  It is a pointer to:

  • EVP_BlobRequestAzureBlob for EVP_BLOB_TYPE_AZURE_BLOB

  • EVP_BlobRequestEvp for EVP_BLOB_TYPE_EVP

  • EVP_BlobRequestEvpExt for EVP_BLOB_TYPE_EVP_EXT

  • EVP_BlobRequestHttp for EVP_BLOB_TYPE_HTTP

  • EVP_BlobRequestHttpExt for EVP_BLOB_TYPE_HTTP_EXT

• localStore – The info about the local store for the data. The pointed info is copied as needed, so it is responsibility of the caller to free it.

• cb – The callback function. It can not be NULL.

• userData – The SDK passes this value to the callback as it is. The SDK doesn’t care if it’s a valid pointer.

Returns:

EVP_OK Success.

EVP_RESULT EVP_blobGetUploadURL(struct EVP_client *h, const charstorageName, const charremoteName, EVP_BLOB_CALLBACK cb, void *userData)

Get the upload URL This API is only available from native. It cannot be used from the WASM module.

Warning

This is an experimental option and will be removed in future releases.

Parameters:

• h – struct EVP_client.

• storageName – The unique string to identify the blob storage based on data type.

• remoteName – The unique string to identify file name to upload. Set “” to get container UploadURL. Set other than “” to get Blob UploadURL.

• cb – The callback function. It can not be NULL.

• userData – The SDK passes this value to the callback as it is. The SDK doesn’t care if it’s a valid pointer.

Returns:

EVP_OK Success.

HTTP Extended

struct EVP_BlobRequestHttpExt *EVP_BlobRequestHttpExt_initialize(void)

Initializes an EVP_BlobRequestHttpExt

This function must be called when instantiating an EVP_BlobRequestHttpExt. It returns a pointer to a new request that must be later freed using EVP_BlobRequestHttpExt_free()

Returns:

Pointer to a newly allocated request struct. NULL on failure.

void EVP_BlobRequestHttpExt_free(struct EVP_BlobRequestHttpExt *request)

Frees an EVP_BlobRequestHttpExt

This function must be called when freeing an EVP_BlobRequestHttpExt

Parameters:

• request – A pointer to a EVP_BlobRequestHttpExt structure.

EVP_RESULT EVP_BlobRequestHttpExt_addHeader(struct EVP_BlobRequestHttpExt *request, const char *name, const char *value)

Inserts an extra header to EVP_BlobRequestHttpExt

This helper function inserts an extra header into the request.

Parameters:

• request – A pointer to a EVP_BlobRequestHttpExt structure.

• name – A pointer to a null-terminated string containing the name of the header.

• value – A pointer to a null-terminated string containing the value of the header.

Returns:

EVP_OK Success.

EVP_RESULT EVP_BlobRequestHttpExt_addAzureHeader(struct EVP_BlobRequestHttpExt *request)

Inserts an extra header to EVP_BlobRequestHttpExt

This helper function inserts the azure specific headers in the request.

Parameters:

• request – A pointer to a EVP_BlobRequestHttpExt structure.

Returns:

EVP_OK Success.

EVP_RESULT EVP_BlobRequestHttpExt_setUrl(struct EVP_BlobRequestHttpExt *request, char *url)

Sets the url of EVP_BlobRequestHttpExt

This function sets the url of the request.

Parameters:

• request – A pointer to a EVP_BlobRequestHttpExt structure.

• url – The destination URL of the request.

Returns:

EVP_OK Success.

---