Network API

async_interface connection_config connection_interface gatt receiver subscriber writer

Async Interface

void loop_once(conn_ctx *ctx, uint32_t timeout)

Loop one time and return.

Parameters

• ctx: An already initialized connection context.
• timeout: Time to wait before returning if no event is scheduled.

void loop(conn_ctx *ctx, uint32_t timeout)

Blocking function to start the loop.

Parameters

• ctx: An already initialized connection context.
• timeout: Time to wait before returning if no event is scheduled.

void break_loop(conn_ctx *ctx)

This function breaks the loop. The execution will continue from the loop() function.

Parameters

• ctx: An already initialized connection context.

Connection Config

pull_error conn_config(conn_config_t *cfg, char *endpoint, uint16_t port, conn_type type, void *conn_data, char *resource)

Connection Interface

enum net_connint::rest_method

Verbs supported by the REST connection

Values:

GET

PUT

Standard REST verb

POST

Standard REST verb

DELETE

Standard REST verb

OPTIONS

Standard REST verb

GET_BLOCKWISE2

Standard REST verb CoAP specific method

enum net_connint::conn_type

Values:

PULL_TCP

PULL_UDP

PULL_DTLS_PSK

PULL_DTLS_ECDH

typedef enum rest_method rest_method

Verbs supported by the REST connection

typedef enum conn_type conn_type

typedef struct conn_ctx conn_ctx

pull_error conn_init(conn_ctx *ctx, const char *addr, uint16_t port, conn_type type, void *data)

Init the connection context. This functions initialize the connection context and start the connection with the backend specified in the parameters.

Return

PULL_SUCCESS if success or the specific error otherwise.

Parameters

• ctx:
• addr: Backend address.
• port: Backend port.
• type: Connection type. This enumberation can be defined in the interface implementation. (i.e., TCP, UDP, DTLS, etc..);
• data: This raw pointer stores data for the specific connection type (e.g., keys for a DTLS connection).

pull_error conn_on_data(conn_ctx *ctx, callback handler, void *more)

Set the callback to be called in case of a new event. The callback is related to the connection and not the single request. This means that all the requests must be handled by the same callback. This is not a problem in the way the connection module is used by the library because each connection is used just for a specific operation and, in case you want to reuse a connection, you must be sure that all the previous requests has been satisfied.

Return

PULL_SUCCESS if the callback has been correcly setted.

Parameters

• ctx: An alredy initialized connection context.
• handler: The callback handler.
• more: A pointer that will be passed to the callback every time it is called.

pull_error conn_request(conn_ctx *ctx, rest_method method, const char *resource, const char *data, uint16_t length)

Perform a request to the backend. The request is performed using the method, the resource and the data specified.

Return

PULL_SUCCESS if the request was correcly sent or the specific error otherwise.

Parameters

• ctx: An already initialized connection context.
• method: The rest method to perform the request (e.g., GET, PUT, etc).
• resource: The REST resource.
• data: (Optional) The data to be sent or NULL.
• length: The lenght of the data or 0;

pull_error conn_observe(conn_ctx *ctx, const char *resource, const char *token, uint8_t token_length)

TODO TO BE IMPLEMENTED

void conn_end(conn_ctx *ctx)

Close the connection connection. This function must free all the resources and close the connection with the server.

Parameters

• ctx: The connection context to close.

Gatt

pull_error libpull_gatt_init()

LIBPULL_SERVICE_UUID

LIBPULL_VERSION_UUID

LIBPULL_PLATFORM_UUID

LIBPULL_IDENTITY_UUID

LIBPULL_UPDATE_UUID

LIBPULL_STATE_UUID

LIBPULL_RESULT_UUID

LIBPULL_RECEIVED_UUID

LIBPULL_IMAGE_UUID

Receiver

typedef struct receiver_ctx receiver_ctx

Receiver context used to hold data for the receiver function

pull_error receiver_open(receiver_ctx *ctx, conn_ctx *conn, identity_t *identity, const char *resource, mem_object_t *obj)

Open the receiver context. This function start the connection with the backend. It uses a connection object to communicate with it and needs a string rappresenting the resource we want to receive from the backend. It stores the received content into a memory object.

Return

PULL_SUCCESS in case the receiver was correcly initialized or the specific error otherwise.

Parameters

• ctx: The receiver context that should be passed to every receiver function.
• conn: The connection object. It must be already initialized.
• identity: The device identity used for this particular request
• resource: The resource we want to download from the backend.
• obj: Memory object used to store the received data. It must be opened.

pull_error receiver_chunk(receiver_ctx *ctx)

Receive and store a chunk of the update into the memory object.

Return

PULL_SUCCESS in case the chunk was correcly downloaded and stored or the specific error otherwise.

Parameters

• ctx: The previously initialized receiver context.

pull_error receiver_close(receiver_ctx *ctx)

Close the receiver context and close the connection with the server.

Return

PULL_SUCCESS in case the context was correcly closed or the specific error otherwise.

Parameters

• ctx: The receiver context to close.

RECEIVER_H_

MESSAGE_VERSION

struct receiver_ctx

#include <receiver.h>

Receiver context used to hold data for the receiver function

Subscriber

void subscriber_cb(pull_error err, const char *data, int len, void *more)

Callback handling the data received by the server. There is a default implementation of this callback but it can be overridden by the user by passing its own callback to the check update function.

Note

The more parameter can be useful to pass receive some structure from the function creating the trasnport when the callback is called.

Parameters

• err: Error received by the calling function. PULL_SUCCESS if no error.
• data: Data received by the network. NULL if error.
• len: Lenght of the received data. 0 if error.
• more: Pointer passed during initialization of the connection object.

pull_error subscribe(subscriber_ctx *ctx, conn_ctx *conn, const char *resource, mem_object_t *obj_t)

Subscribe to a backend for updates. This functions initialize the subsciber context and subscribe to a specific resource. It requires an already initialized connection context.

Return

PULL_SUCCESS on success or the specific error otherwise.

Parameters

• ctx: A pointer to the subscriber.
• conn: An already opended connection object.
• resource: A string rapresenting the resource.
• obj_t: A temporary memory object.

pull_error check_updates(subscriber_ctx *ctx, callback cb)

Check the presence of an update. This blocking function perform a request to the specified backend and resource and handles the response using the provided callback. An already defined callback is provided with the library, however you can define your own logic matching the protocol used in your server.

Return

PULL_SUCCESS on success or the specific error otherwise.

Parameters

• ctx: An already initialized ubscriber context.
• cb: The callback.

pull_error unsubscribe(subscriber_ctx *ctx)

Unsubscribe from the backend. This function closes context, however does not closes the connection tham must be closed by the caller.

Return

PULL_SUCCESS on success or the specific error otherwise.

Parameters

• ctx: The subscriber context to close.

Writer

typedef pull_error (*validate_mt)(manifest_t *mt, void *user_data)

typedef struct writer_ctx_t writer_ctx_t

pull_error writer_open(writer_ctx_t *ctx, mem_object_t *obj, validate_mt cb, void *user_data)

pull_error writer_chunk(writer_ctx_t *ctx, const char *data, uint32_t len)

pull_error writer_close(writer_ctx_t *ctx)

WRITER_BUFFER_LEN