Base

Types

struct EVP_client

An opaque structure to represent an EVP client.

This client is used by EVP module instances to communicate with the EVP agent running locally on the same device.

An EVP module instance can obtain the pointer to the client by calling EVP_initialize().

The majority of SDK API functions take a pointer to this structure.

type EVP_RESULT

The type to represent either a success or an error. Used as the return value of several of the functions in this SDK.

Values:
enumerator EVP_OK
Value:

0

At least one event has been processed.

enumerator EVP_SHOULDEXIT
Value:

1

The module instance is requested to stop. It should exit performing cleanup as soon as possible.

enumerator EVP_TIMEDOUT
Value:

2

The specified period has elapsed without any events.

enumerator EVP_ERROR
Value:

3

An error ocurred.

enumerator EVP_INVAL
Value:

4

Invalid parameter.

enumerator EVP_NOMEM
Value:

5

Memory allocation failed.

enumerator EVP_TOOBIG
Value:

6

Too big payload.

enumerator EVP_AGAIN
Value:

7

Failure because of temporary conditions.

enumerator EVP_AGENT_PROTOCOL_ERROR
Value:

8

Protocol error when communicating with the agent.

enumerator EVP_EXIST
Value:

9

The request failed bacause of conflicting existing entries.

enumerator EVP_FAULT
Value:

10

Invalid address was detected.

Note

An application should not rely on such a detection. It’s the responsibility of applications to always specify vaild addresses.

enumerator EVP_DENIED
Value:

11

A request was denied. It could mean the agent cannot be transmitting due to a full queue.

enumerator EVP_NOTSUP
Value:

12

The request is still not supported by the implementation.

typedef uint64_t EVP_RPC_ID

The integer request ID used for RPCs.

Reasons

Each callback type have its associated EVP_*_CALLBACK_REASON enum.

They share some common definitions:

enumerator CALLBACK_REASON_SENT

The request has been received by the next hop entity. (Typically the agent within the device. It will try its best to deliver the State to the Cloud reliably.)

Note

This doesn’t mean the State has reached the Cloud.

enumerator CALLBACK_REASON_EXIT

The request has been cancelled because the module instance is going to exit. This gives the module instance a chance to cleanup the associated resources before exiting.

Users must not send any more requests to the agent when this code is received, and instead must call EVP_processEvent() until all events are flushed.

enumerator CALLBACK_REASON_ERROR

The request has not been processed because it is invalid.

enumerator CALLBACK_REASON_DENIED

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

type EVP_STATE_CALLBACK_REASON

The type to represent the reason of the callback invocation.

Values:
enumerator EVP_STATE_CALLBACK_REASON_SENT
Value:

0

See CALLBACK_REASON_SENT.

enumerator EVP_STATE_CALLBACK_REASON_OVERWRITTEN
Value:

1

The State has been overwritten by another EVP_sendState() call with the same topic.

Note

The SDK only cares about the latest State for a topic.

enumerator EVP_STATE_CALLBACK_REASON_EXIT
Value:

2

See CALLBACK_REASON_EXIT.

enumerator EVP_STATE_CALLBACK_REASON_DENIED
Value:

3

See CALLBACK_REASON_DENIED.

type EVP_MESSAGE_SENT_CALLBACK_REASON

The type to represent the reason of the callback invocation.

Values:
enumerator EVP_MESSAGE_SENT_CALLBACK_REASON_SENT
Value:

0

See CALLBACK_REASON_SENT.

enumerator EVP_MESSAGE_SENT_CALLBACK_REASON_ERROR
Value:

1

See CALLBACK_REASON_ERROR.

enumerator EVP_MESSAGE_SENT_CALLBACK_REASON_EXIT
Value:

2

See CALLBACK_REASON_EXIT.

type EVP_TELEMETRY_CALLBACK_REASON

The type to represent the reason of the callback invocation.

Values:
enumerator EVP_TELEMETRY_CALLBACK_REASON_SENT
Value:

0

See CALLBACK_REASON_SENT.

enumerator EVP_TELEMETRY_CALLBACK_REASON_ERROR
Value:

1

See CALLBACK_REASON_ERROR.

enumerator EVP_TELEMETRY_CALLBACK_REASON_EXIT
Value:

2

See CALLBACK_REASON_EXIT.

enumerator EVP_TELEMETRY_CALLBACK_REASON_DENIED
Value:

3

See CALLBACK_REASON_DENIED.

type EVP_RPC_RESPONSE_CALLBACK_REASON

The type to represent the reason of the callback invocation.

Values:
enumerator EVP_RPC_RESPONSE_CALLBACK_REASON_SENT
Value:

0

See CALLBACK_REASON_SENT.

enumerator EVP_RPC_RESPONSE_CALLBACK_REASON_ERROR
Value:

1

See CALLBACK_REASON_ERROR.

enumerator EVP_RPC_RESPONSE_CALLBACK_REASON_EXIT
Value:

2

See CALLBACK_REASON_EXIT.

enumerator EVP_RPC_RESPONSE_CALLBACK_REASON_DENIED
Value:

3

See CALLBACK_REASON_DENIED.

type EVP_RPC_RESPONSE_STATUS

The type to specify a status condition for a RPC response to the Hub.

Values:
enumerator EVP_RPC_RESPONSE_STATUS_OK
Value:

0

The RPC request executed successfully and the response contains the results of the execution.

enumerator EVP_RPC_RESPONSE_STATUS_METHOD_NOT_FOUND
Value:

1

The originating RPC request specified a method that is not implemented, so it is reported back as not found.

enumerator EVP_RPC_RESPONSE_STATUS_ERROR
Value:

2

The RPC request executed with error and the response contains the error message

type EVP_WORKSPACE_TYPE

The type to represent a workspace type.

Values:
enumerator EVP_WORKSPACE_TYPE_DEFAULT
Value:

0

Default type of Workspace.

typedef int EVP_STREAM

The type used to represent a stream.

typedef unsigned long EVP_STREAM_PEER_ID

The type used to represent a peer identifier.

Callbacks

typedef void (*EVP_CONFIGURATION_CALLBACK)(const char *topic, const void *config, size_t configlen, void *userData)

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

Parameters:

  • topic - Destination topic.

  • config - The buffer to pass as configuration.

  • configlen - The size of the configuration data for sending.

  • userData - An arbitrary blob of data to pass to the callback.

typedef void (*EVP_STATE_CALLBACK)(EVP_STATE_CALLBACK_REASON reason, void *userData)

Function prototype for the callback passed to State message-dealing functions such as EVP_sendState().

Parameters:

  • reason - The cause code for executing the callback.

  • userData - An arbitrary blob of data to pass to the callback.

typedef void (*EVP_MESSAGE_SENT_CALLBACK)(EVP_MESSAGE_SENT_CALLBACK_REASON reason, void *userData)

Function prototype for the callback passed to generic message-dealing functions such as EVP_sendMessage().

Parameters:

  • reason - The cause code for executing the callback.

  • userData - An arbitrary blob of data to pass to the callback.

typedef void (*EVP_MESSAGE_RECEIVED_CALLBACK)(const char *topic, const void *msgPayload, size_t msgPayloadLen, void *userData)

Function prototype for the callback passed to the function EVP_setMessageCallback(). Executed when a message is received on the configured topic.

Parameters:

  • topic - Destination topic.

  • msgPayload - The buffer to pass as configuration.

  • msgPayloadLen - The size of the configuration data for sending.

  • userData - An arbitrary blob of data to pass to the callback.

typedef void (*EVP_TELEMETRY_CALLBACK)(EVP_TELEMETRY_CALLBACK_REASON reason, void *userData)

Function prototype for the callback passed to EVP_sendTelemetry().

Parameters:

  • reason - The cause code for executing the callback.

  • userData - An arbitrary blob of data to pass to the callback.

typedef void (*EVP_RPC_REQUEST_CALLBACK)(EVP_RPC_ID id, const char *methodName, const char *params, void *userData)

Function prototype for the callback passed to EVP_setRpcCallback().

Parameters:

  • id - The request Id for EVP_sendRpcResponse().

  • methodName - The name of method.

  • params - The call parameters. A string representation of

    a JSON value.

typedef void (*EVP_RPC_RESPONSE_CALLBACK)(EVP_RPC_RESPONSE_CALLBACK_REASON reason, void *userData)

Function prototype for the callback passed to EVP_sendRpcResponse().

Parameters:

  • reason - The cause code for executing the callback.

  • userData - An arbitrary blob of data to pass to the callback.

typedef void (*EVP_STREAM_READ_CALLBACK)(EVP_STREAM_PEER_ID id, const void *buf, size_t n, void *userData)

The callback type used to represent a read-available stream operation.

Parameters:

  • id - Peer identifier. Whereas this remains as an opaque type, applications can rely on different identifiers meaning different connections to a given stream.

  • buf - Buffer containing the input data.

  • n - Buffer length.

  • userData - An opaque pointer to user-defined data, as defined by EVP_streamInputOpen() .

Functions

struct EVP_client *EVP_initialize(void)

Initialize the SDK.

Performs the required initialization operations for the module instance.

This should be called by the main thread of the module instance. Otherwise, the behaviour is undefined.

This should not be called more than once for a module instance. Otherwise, the behaviour is undefined.

Returns:

Client object pointer for the calling module instance.

const char EVP_getWorkspaceDirectory(struct EVP_client *h, EVP_WORKSPACE_TYPE type)

Returns the absolute path of the workspace directory for the calling Module Instance.

The workspace directory with the default type (EVP_WORKSPACE_TYPE_DEFAULT) has the following characteristics:

  • Initially, the workspace directory is empty.

  • The workspace directory is left intact across a reboot of the Module Instace and/or the device. It can contain the contents left by the Module Instance before a reboot.

  • The Module Instance has an exclusive access to its workspace directory during its lifetime.

  • The Module Instance can access the workspace directory directly, using the OS interfaces like open() and mkdir().

  • The Module Instance can request file operations on the workspace directory via the SDK. For example, upload from/download to a file on the workspace directory.

  • The Module Instance should only use regular files and directories on the workspace directory. If it attempts to create other file types, the behavior is undefined.

  • The agent will remove files in the workspace directory after the corresponding Module Instance has gone away. That is, at some point after a successful deployment of a new Deployment which doesn’t contain the Module Instance anymore.

Parameters:

  • h – Client object pointer.

  • type – Workspace type

Returns:

The absolute path to the workspace directory.

EVP_RESULT EVP_setConfigurationCallback(struct EVP_client *h, EVP_CONFIGURATION_CALLBACK cb, void *userData)

Register a callback function for Configuration.

This should not be called more than once for a EVP_client object. Otherwise, the behaviour is undefined.

The callback cb will be called in the context of this function or of EVP_processEvent().

The callback will be called on the following events at least:

  • When the callback function is registered.

  • When the SDK received the latest Configuration.

The SDK might coalesce multiple events into one. In that case, the callback will be called with the latest Configuration.

The SDK might choose to invoke this callback more frequently than necessary. The callback function should not assume that the given Configuration was updated.

All pointers given to the callback, including topic and Configuration, are only valid until the callback function returns. The callback function should make a copy if necessary.

Parameters:

  • h – Client object pointer.

  • cb – User callback function.

  • 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 on Success.

EVP_RESULT EVP_sendState(struct EVP_client *h, const char *topic, const void *state, size_t statelen, EVP_STATE_CALLBACK cb, void *userData)

Schedule to send the specified State for the specified topic.

The callback cb will be called in the context of this function or of EVP_processEvent(), when the request has been sent or cancelled. It will be invoked with one of the reasons defined by EVP_STATE_CALLBACK_REASON.

Warning

It’s the caller’s responsibility to keep the specified topic and state valid until the callback is called. Otherwise, the behaviour is undefined. (The SDK implementation might choose to keep pointers of them without making copies.)

Parameters:

  • h – Client object pointer.

  • topic – Destination topic.

  • state – State data.

  • statelen – State size in bytes.

  • cb – User callback function.

  • 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_sendMessage(struct EVP_client *h, const char *topic, const void *state, size_t statelen, EVP_MESSAGE_SENT_CALLBACK cb, void *userData)

Schedule to send the specified message.

The callback will be called in the context of this function or of EVP_processEvent(), when the request has been sent or cancelled. It will be invoked with one of the reasons defined by EVP_MESSAGE_SENT_CALLBACK_REASON.

Warning

It’s the caller’s responsibility to keep the specified topic and state valid until the callback is called. Otherwise, the behaviour is undefined. (The SDK implementation might choose to keep pointers of them without making copies.)

Parameters:

  • h – Client object pointer.

  • topic – Destination topic.

  • state – State data.

  • statelen – State size in bytes.

  • cb – User callback function.

  • 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.

struct EVP_telemetry_entry

Describe a telemetry data

A Key-Value pair to be sent as a telemetry. Both of the key and value should be a valid UTF-8 string. The value should be a string representation of a valid JSON value.

const char *key

A key

const char *value

A JSON value

EVP_RESULT EVP_sendTelemetry(struct EVP_client *h, const struct EVP_telemetry_entry *entries, size_t nentries, EVP_TELEMETRY_CALLBACK cb, void *userData)

Schedule to send the telemetry.

The callback will be called in the context of this function or of EVP_processEvent(), when the request has been sent or cancelled. It will be invoked with one of the reasons defined by EVP_TELEMETRY_CALLBACK_REASON.

Warning

It’s the caller’s responsibility to keep the specified entries valid until the callback is called. Otherwise, the behaviour is undefined. (The SDK implementation might choose to keep pointers of them without making copies.)

Parameters:

  • h – Client object pointer.

  • entries – The array of the telemetry data.

  • nentries – The size of the array.

  • cb – User callback function.

  • 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_processEvent(struct EVP_client *h, int timeout_ms)

Wait for an event and process it.

This function is intended to be called in the main loop of the module instance. It waits for an event (e.g. Configuration update) and process it. It processes one pending event per call.

Parameters:

  • h – Client object pointer.

  • milliseconds –

    • 0 means immediate.

    • -1 means forever.

Returns:

  • EVP_OK When at least one event has been processed.

  • EVP_TIMEDOUT When the period specified by timeout_ms has elapsed without any events.

  • EVP_SHOULDEXIT When the module instance is requested to stop and all events have been already dispatched. It should exit performing cleanup as soon as possible.

See EVP_STATE_CALLBACK_REASON_EXIT, EVP_MESSAGE_SENT_CALLBACK_REASON_EXIT, EVP_TELEMETRY_CALLBACK_REASON_EXIT, EVP_RPC_RESPONSE_CALLBACK_REASON_EXIT, EVP_BLOB_CALLBACK_REASON_EXIT

EVP_RESULT EVP_setMessageCallback(struct EVP_client *h, EVP_MESSAGE_RECEIVED_CALLBACK incoming_cb, void *userData)

Specifies a callback to invoke on every incoming message.

This should not be called more than once for a EVP_client. Otherwise, the behaviour is undefined.

The callback will be called in the context of EVP_processEvent(), upon reception of a message on any of the subscribed topics.

Note

Messages which have arrived before a successful call to this function might or might not be delivered to the specified callback.

Parameters:

  • h – Client object pointer.

  • incoming_cb – User callback function.

  • 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_setRpcCallback(struct EVP_client *h, EVP_RPC_REQUEST_CALLBACK cb, void *userData)

Specifies a callback to invoke on every incoming RPC call.

This should not be called more than once for a EVP_client. Otherwise, the behaviour is undefined.

The callback will be called in the context of EVP_processEvent(), upon reception of a RPC request.

Note

RPC calls which have arrived before a successful call of this function might or might not be delivered to the specified callback.

For each invocation of the specified callback, EVP_sendRpcResponse() should be called exactly once with the ID given by the callback and Client object pointer specified to this function. It’s the caller’s responsibility to ensure that. Otherwise, the behaviour is undefined.

Parameters:

  • h – Client object pointer.

  • cb – User callback function.

  • 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_sendRpcResponse(struct EVP_client *h, EVP_RPC_ID id, const char *response, EVP_RPC_RESPONSE_STATUS status, EVP_RPC_RESPONSE_CALLBACK cb, void *userData)

Schedule to send the specified RPC response.

This function can be used within the context of EVP_RPC_REQUEST_CALLBACK.

The callback will be called in the context of this function or of EVP_processEvent(), when the request has been sent or cancelled. It will be invoked with one of the reasons defined by EVP_RPC_RESPONSE_CALLBACK_REASON.

For implementing named methods, the SDK provides a method-not-found response by setting the status flag to EVP_RPC_RESPONSE_STATUS_METHOD_NOT_FOUND. In that case, the value of response will be ignored.

See the entire set of values of EVP_RPC_RESPONSE_STATUS to use in other situations.

It’s the caller’s responsibility to keep the specified parameters valid until the callback is called. Otherwise, the behavior is undefined (The SDK implementation might choose to keep pointers of them without making copies).

Parameters:

  • h – Client object pointer.

  • id – The request ID from EVP_RPC_REQUEST_CALLBACK, to which you want to reply.

  • response – The response. It should be a string representation of a valid JSON value.

  • status – Response status.

  • cb – User callback function.

  • 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 in case of success.

  • EVP_TOOBIG when the payload is larger than the agent can handle (i.e. due to device constraints).

  • EVP_INVAL if the response is NULL.

EVP_RESULT EVP_streamOutputOpen(struct EVP_client *h, const char *name, EVP_STREAM *stream)

Opens an output stream.

Streams allow for device-to-device and module-to-module communication, using an interface somewhat similar to BSD sockets. However, the actual implementation depends on which stream type has been selected from the deployment manifest.

Parameters:

  • h – Client object pointer.

  • name – Null-terminated string with the stream name. This must match the name of one of the streams defined on the deployment manifest.

  • stream – [OUT] On success, it shall be assigned to a non-negative integer. Otherwise, it shall be assigned to a negative integer.

Returns:

  • EVP_OK Success.

  • EVP_INVAL if the stream was not defined by the deployment manifest or the stream was not defined for output.

  • EVP_EXIST if a stream with the same name has already been opened.

  • EVP_NOMEM if memory could not be allocated.

  • EVP_ERROR if an unexpected error occurred.

Streams

EVP_RESULT EVP_streamInputOpen(struct EVP_client *h, const char *name, EVP_STREAM_READ_CALLBACK cb, void *userData, EVP_STREAM *stream)

Opens an input stream.

Streams allow for device-to-device and module-to-module communication, using an interface somewhat similar to BSD sockets. However, the actual implementation depends on which stream type has been selected from the deployment manifest.

Parameters:

  • h – Client object pointer.

  • name – Null-terminated string with the stream name. This must match the name of one of the streams defined on the deployment manifest.

  • cb – User callback that shall be executed when input data becomes available.

  • userData – Opaque pointer to user-defined data that shall be passed to cb.

  • stream – [OUT] On success, it shall be asssigned to a non-negative integer. Otherwise, it shall be assigned to a negative integer.

Returns:

  • EVP_OK Success.

  • EVP_INVAL if the stream was not defined by the deployment manifest or the stream was not defined for input.

  • EVP_EXIST if a stream with the same name has already been opened.

  • EVP_NOMEM if memory could not be allocated.

  • EVP_ERROR if an unexpected error occurred.

EVP_RESULT EVP_streamClose(struct EVP_client *h, EVP_STREAM stream)

Closes a stream previously opened with EVP_streamInputOpen() or EVP_streamOutputOpen().

Parameters:

  • h – Client object pointer.

  • stream – Stream identifier.

Returns:

  • EVP_OK Success.

  • EVP_INVAL if the stream was not defined by the deployment manifest.

  • EVP_ERROR if an unexpected error occurred.

EVP_RESULT EVP_streamWrite(struct EVP_client *h, EVP_STREAM stream, const void *buf, size_t n)

Sends a buffer over a stream previously opened with EVP_streamInputOpen() or EVP_streamOutputOpen().

Parameters:

  • h – Client object pointer.

  • stream – Stream identifier.

  • buf – Buffer to send.

  • n – Buffer length.

Returns:

  • EVP_OK Success.

  • EVP_INVAL if the stream was not defined by the deployment manifest or was not configured for output.

  • EVP_ERROR if an unexpected error occurred.