Common API

The common modules contains functions and interfaces that are shared in the whole library. This allows to grant consistency and to reduce code duplication. You can include all the common modules by including

#include <libpull/common.h>

Callback

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

Callback used to handle network events.

Parameters
  • err: Error received or PULL_SUCCESS if no error.
  • data: Received data.
  • len: Lenght of received data.
  • more: Raw pointer passed during connection initialization.

Crc16

Warning

doxygengroup: Cannot find namespace “com_crc16” in doxygen xml output for project “libpull” from directory: ./doxyxml/

Error

enum com_error::pull_error

Each module should returns just errors of that particular module. In this way it is possible for the calling function to have a finite set of errors returned by the function.

Values:

PULL_SUCCESS = 0
GENERIC_ERROR

Generic error

NOT_IMPLEMENTED_ERROR

Method not implemented

INVALID_ARGUMENTS_ERROR
CONNECTION_INIT_ERROR

The connection initialization failed

CALLBACK_ERROR

The callback could not be setted

RESOLVER_ERROR

Error resolving the backend

INVALID_URL_ERROR

The URL of the provided resource is invalid

BLOCK_WISE_ERROR

Error during the Block-Wise transfer

INVALID_METHOD_ERROR

The request method is invalid or not supported

INVALID_RESOURCE_ERROR

The requested resource is invalid

INVALID_DATA_ERROR

The received data is invalid

INVALID_CONN_DATA_ERROR

The data used to inizialize the connection is invalid

REQUEST_ERROR

Error performing the request

REQUEST_RST_ERROR
SEND_ERROR
MEMORY_ERROR
INVALID_OBJECT_ERROR
INVALID_ACCESS_ERROR
MEMORY_MAPPING_ERROR
MEMORY_OPEN_ERROR
MEMORY_CLOSE_ERROR
MEMORY_ERASE_ERROR
MEMORY_READ_ERROR
MEMORY_WRITE_ERROR
MEMORY_FLUSH_ERROR
READ_MANIFEST_ERROR
GET_NEWEST_ERROR
GET_OLDEST_ERROR
COPY_FIRMWARE_ERROR
INVALIDATE_OBJECT_ERROR
WRITE_MANIFEST_ERROR
INVALID_MANIFEST_ERROR
RECEIVER_OPEN_ERROR
RECEIVER_CHUNK_ERROR
RECEIVER_CLOSE_ERROR
INVALID_SIZE_ERROR
INVALID_IDENTITY_ERROR
NETWORK_ERROR
SUBSCRIBE_ERROR
SUBSCRIBER_CHECK_ERROR
DIGEST_INIT_ERROR
DIGEST_UPDATE_ERROR
DIGEST_FINAL_ERROR
SHA256_INIT_ERROR
SHA256_UPDATE_ERROR
SHA256_FINAL_ERROR
NOT_SUPPORTED_CURVE_ERROR
VERIFICATION_FAILED_ERROR
SIGN_FAILED_ERROR
const char *err_as_str(pull_error err)

This function returns a string representing the literal representation of the error.

Return
Pointer to a string describing the error.
Parameters
  • err: The error to be printed.

GENERATE_ENUM(ENUM)
GENERATE_STRING(STRING)
FOREACH_ERROR(ERROR)

External

const mem_slot_t memory_slots[]

This structure contains a list of the memory slots needed by your application. We already have a standard definition but you can define it by yourself and personalize according to your needs.

An example of a correctly implemented memory slot is structure is:

 const mem_slot_t memory_slots[] = {
  {
      .id = OBJ_1,
      .bootable = true,
      .loaded = true
  },
  {
      .id = OBJ_2,
     .bootable = false,
     .loaded = false
 },
 {OBJ_END}
};

OBJ_END

OBJ_END must be used to end a memory slot list. Internally the library uses it to know when to stop cycling over the structure.

Identity

pull_error update_random(identity_t *identity)

Function to update the random using a PRNG. The implementation is platform dependent and must often rely on hardware solutions included in the platform since there is no entropy source in many RTOS.

Return
PULL_SUCCESS on success, an error otherwise.
Parameters
  • identity: Pointer to the identity struct containing the value to be updated.

pull_error validate_identity(identity_t valid_identity, identity_t received_identity)

Function to validate an identity comparing it to the one stored on the device.

Return
PULL_SUCCESS if the identity is valid, an error otherwise.
Parameters
  • valid_identity: Pointe to the identity stored on the device.
  • received_identity: Pointer to the identity received that must be validated.

struct identity_t
#include <identity.h>

Structure used to univocally identify a device.

Note
This struct is often passed by value in the library, so it must not contain any pointer.

Loader

void load_object(mem_id_t id)

Loader interface used to load the object once stored.

Parameters
  • id: Id of the memory object to be loaded.

Logger

uint8_t verbosity_level

The verbosity_level variable indicates the log_impling level. If you want to change it at runtime you can define the external symbol in your application. In case you don’t need to change it at runtime you can define it as a constant, defining the LOGGER_VERBOSITY define. In this way the compiler will be able to optimize the code and remove the non needed debugging directives.

4 logging level are supported:

  • Error: Just the errors are printed.
  • Warn: Error and warnings are printed.
  • Info: Error, warnign and also information strings.
  • Debug: All the output is printed. This affect heavily the memory footprint of the library.

VERBOSITY_ERROR
VERBOSITY_WARN
VERBOSITY_INFO
VERBOSITY_DEBUG
log_output(...)
log_impl(...)
log_err(...)
log_debug(...)
log_info(...)
log_error(err, ...)

This function takes as first parameter an error and then an arbitrary number of arguments that will be printed. The first arguemnt will be used to print the literal value of the error.

log_warn(...)

Pull Assert

PULL_ASSERT(cond)

Types

typedef uint16_t version_t

Version type to be used across the library.

typedef uint16_t platform_t

Platform type to be used across the library

typedef uint32_t address_t

Address type to be used across the library

typedef int8_t mem_id_t

Identifier for the memory objects. It supports at most 255 objects This must be a signed integer since negative values are used to define an invalid object