Files
file	pt_api.h
	Protocol translator external API V2.

file	pt_certificate_api.h
	API for subscribing certificate renewal notications and renewing certificates.

file	pt_client_api.h
	Contains the interface to create, connect, register, unregister and shut down the protocol translator client. Also contains call declaration of call-back which is called if client is disconnected.

file	pt_crypto_api.h
	API for crypto operations and retrieving certificates and public keys from storage.

file	pt_device_object.h
	A utility header to contain the LwM2M device object ID:3 creation for mediated endpoints.

file	pt_devices_api.h
	Contains the interface to manage multiple devices.

file	pt_userdata_api.h
	Protocol translator API for client's data.

Data Structures
struct	cert_context_s

struct	cert_chain_context_s

struct	protocol_translator_callbacks
	A structure to hold the callbacks of the protocol translator. More...

struct	ptdo_device_object_data
	The device object data ID:3. More...

struct	pt_userdata_s
	Contains fields for client user data. More...

Macros
#define	CE_STATUS_RANGE_BASE 0x0500

#define	CE_STATUS_RANGE_END 0x0600

Typedefs
typedef pt_status_t(*	pt_resource_callback) (const connection_id_t connection_id, const char device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, const uint8_t operation, const uint8_t value, const uint32_t size, void *userdata)
	Callback function prototype for the device resource specific action on OPERATION_WRITE or OPERATION_EXECUTE. More...

typedef void(*	pt_resource_value_free_callback) (void *value)
	Callback function prototype for freeing the resource value. More...

typedef void(*	pt_device_response_handler) (const connection_id_t connection_id, const char device_id, void userdata)
	A function pointer type definition for callbacks given in the device API functions as an argument. This function definition is used for providing success and failure callback handlers. More...

typedef struct pt_certificate_list	pt_certificate_list_t

typedef void(*	pt_certificate_renewal_notification_handler) (const connection_id_t connection_id, const char name, int32_t initiator, int32_t status, const char description, void *userdata)
	Type definition for certificate renewal notification. This callback will be called to notify the status when a certificate renewal completes. More...

typedef void(*	pt_device_certificate_renew_response_handler) (const connection_id_t connection_id, const char device_id, const char name, int32_t status, struct cert_chain_context_s cert_chain, void userdata)
	Type definition for certificate renewal notification for device certificate. This callback will be called to notify the status when a certificate renewal completes for device certificate. More...

typedef pt_status_t(*	pt_device_certificate_renew_request_handler) (const connection_id_t connection_id, const char device_id, const char name, void *userdata)
	Type definition for certificate renewal request handler for device certificate. This callback will be called when the cloud requests a device certificate to be renewed. More...

typedef void(*	pt_certificates_set_response_handler) (const connection_id_t connection_id, void *userdata)
	Type definition for `pt_certificate_renewal_list_set` response success and failure handlers. More...

typedef void(*	pt_certificate_renew_response_handler) (const connection_id_t connection_id, void *userdata)
	Type definition for `pt_certificate_renew` response success and failure handlers.

typedef void(*	pt_response_handler) (void *userdata)
	A function pointer type definition for callbacks given in the protocol translator API functions as an argument. This function definition is used for providing success and failure callback handlers. More...

typedef void(*	pt_connection_ready_cb) (connection_id_t connection_id, const char name, void userdata)
	A function prototype for calling the client code when the connection is ready for passing messages. More...

typedef void(*	pt_disconnected_cb) (connection_id_t connection_id, void *userdata)
	A function prototype for calling the client code when the connection is disconnected. More...

typedef void(*	pt_connection_shutdown_cb) (connection_id_t connection_id, void *userdata)
	A function prototype for calling the client code when the connection is shutting down. More...

typedef struct protocol_translator_callbacks	protocol_translator_callbacks_t
	A structure to hold the callbacks of the protocol translator.

typedef void(*	pt_crypto_success_handler) (const connection_id_t connection_id, const uint8_t data, const size_t size, void userdata)
	Type definition for a generic success handler returning a single buffer. More...

typedef void(*	pt_crypto_failure_handler) (const connection_id_t connection_id, int error_code, void *userdata)
	Type definition for a generic failure response handler. More...

typedef pt_crypto_success_handler	pt_crypto_get_item_success_handler
	Type definition for `pt_crypto_get_item_success_handler` response success handler.

typedef void(*	pt_crypto_get_item_failure_handler) (const connection_id_t connection_id, void *userdata)
	Type definition for `pt_crypto_get_item_failure_handler` response failure handler. More...

typedef struct ptdo_device_object_data	ptdo_device_object_data_t
	The device object data ID:3. More...

typedef void(*	pt_devices_cb) (connection_id_t connection_id, void *userdata)
	A function prototype for calling the client code when devices operation (for example: write, register or unregister) is done. More...

typedef void(*	pt_userdata_free_cb_t) (void *data)
	The user-supplied memory deallocation function for userdata. More...

typedef struct pt_userdata_s	pt_userdata_t
	Contains fields for client user data. More...

Enumerations
enum	pt_ce_status_e { CE_STATUS_SUCCESS = 0, CE_STATUS_ERROR = CE_STATUS_RANGE_BASE, CE_STATUS_INVALID_PARAMETER, CE_STATUS_INSUFFICIENT_BUFFER, CE_STATUS_OUT_OF_MEMORY, CE_STATUS_ITEM_NOT_FOUND, CE_STATUS_DEVICE_BUSY, CE_STATUS_BAD_INPUT_FROM_SERVER, CE_STATUS_EST_ERROR, CE_STATUS_STORAGE_ERROR, CE_STATUS_RENEWAL_ITEM_VALIDATION_ERROR, CE_STATUS_BACKUP_ITEM_ERROR, CE_STATUS_ORIGINAL_ITEM_ERROR, CE_STATUS_RESTORE_BACKUP_ERROR, CE_STATUS_RENEWAL_STATUS_ERROR, CE_STATUS_FORBIDDEN_REQUEST, CE_STATUS_ITEM_IS_EMPTY, CE_STATUS_NOT_INITIALIZED, CE_STATUS_INIT_FAILED, CE_STATUS_PENDING = 0x5ff, CE_MAX_STATUS = CE_STATUS_RANGE_END }

Functions
pt_status_t	pt_device_create_with_userdata (const connection_id_t connection_id, const char device_id, const uint32_t lifetime, const queuemode_t queuemode, pt_userdata_t userdata)
	Creates the device structure. More...

pt_status_t	pt_device_create_with_feature_flags (const connection_id_t connection_id, const char device_id, const uint32_t lifetime, const queuemode_t queuemode, const uint32_t features, pt_userdata_t userdata)
	Creates the device structure and enables additional features. More...

pt_status_t	pt_device_create (const connection_id_t connection_id, const char *device_id, const uint32_t lifetime, const queuemode_t queuemode)
	Creates the device structure. More...

pt_status_t	pt_device_get_feature_flags (const connection_id_t connection_id, const char device_id, uint32_t features)
	Retrieves the feature flags of a device. More...

pt_status_t	pt_device_register (const connection_id_t connection_id, const char device_id, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void userdata)
	Endpoint device registration function. Every endpoint device must be registered with the protocol translator and Device Management Edge before reading and writing device values. More...

pt_status_t	pt_device_unregister (const connection_id_t connection_id, const char device_id, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void userdata)
	Endpoint device unregistration function. If the device unregistration succeeds, the device instance data will be freed from memory. More...

pt_status_t	pt_device_write_values (const connection_id_t connection_id, const char device_id, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void userdata)
	Writes changed values from the endpoint device to Edge Core. More...

pt_status_t	pt_device_set_resource_value (const connection_id_t connection_id, const char device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, const uint8_t value, uint32_t value_len, pt_resource_value_free_callback value_free_cb)
	Set a new value to resource in the device. More...

bool	pt_device_exists (const connection_id_t connection_id, const char *device_id)
	Utility function to check if device already exists for the connection. More...

bool	pt_device_resource_exists (const connection_id_t connection_id, const char *device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id)
	Utility function to check if resource already exists for the connection and device. More...

pt_status_t	pt_device_add_resource (const connection_id_t connection_id, const char device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, const char resource_name, const Lwm2mResourceType type, uint8_t *value, uint32_t value_size, pt_resource_value_free_callback value_free_cb)
	Adds a read-only resource to a device. More...

pt_status_t	pt_device_add_resource_with_callback (const connection_id_t connection_id, const char device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, const char resource_name, const Lwm2mResourceType type, const uint8_t operations, uint8_t *value, uint32_t value_size, pt_resource_value_free_callback value_free_cb, pt_resource_callback callback)
	Adds a resource to a device with a callback. More...

pt_status_t	pt_device_get_resource_value (connection_id_t connection_id, const char device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, uint8_t value_out, uint32_t value_len_out)
	Utility function to get the current value in a resource. More...

int32_t	pt_device_get_next_free_object_instance_id (connection_id_t connection_id, const char *device_id, uint16_t object_id)
	Get the id of first free object instance for given object. More...

pt_userdata_t *	pt_device_get_userdata (connection_id_t connection_id, const char *device_id)
	Retrieve the set user data in the device. More...

pt_userdata_t *	pt_resource_get_userdata (connection_id_t connection_id, const char *device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id)
	Retrieve the set user data in the resource. Client needs to provide the full path to the resource. More...

pt_status_t	pt_device_set_userdata (connection_id_t connection_id, const char device_id, pt_userdata_t userdata)
	Set the set user data to the device. This may be useful if the client needs to associate some extra data with the device. Create the userdata using the API function `pt_api_create_userdata()`. More...

pt_status_t	pt_resource_set_userdata (connection_id_t connection_id, const char device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, pt_userdata_t userdata)
	Set the set user data to the resource. This may be useful if the client needs to associate some extra data with the device. Create the userdata using the API function `pt_api_create_userdata()`. Client needs to provide the full path to the resource. More...

pt_certificate_list_t *	pt_certificate_list_create ()
	Creates a certificate list. More...

void	pt_certificate_list_destroy (pt_certificate_list_t *list)
	Destroys the certificate list. Frees all the certificates added to the list.

pt_status_t	pt_certificate_list_add (pt_certificate_list_t list, const char name)
	Adds a certificate to certificate list. More...

pt_status_t	pt_certificate_renewal_list_set (const connection_id_t connection_id, pt_certificate_list_t list, pt_certificates_set_response_handler success_handler, pt_certificates_set_response_handler failure_handler, void userdata)
	Sends the certificate list to Edge, triggering renewal subscriptions of the certificates in the list. More...

pt_status_t	pt_certificate_renew (const connection_id_t connection_id, const char name, pt_certificate_renew_response_handler success_handler, pt_certificate_renew_response_handler failure_handler, void userdata)
	Requests the renewal of the certificate specified by the `name` parameter. More...

pt_status_t	pt_device_certificate_renew (const connection_id_t connection_id, const char device_id, const char name, const char csr, const size_t csr_length, pt_device_certificate_renew_response_handler success_handler, pt_device_certificate_renew_response_handler failure_handler, void userdata)
	Requests the renewal of the certificate specified by the `name` parameter using the certificate signing request specified by the `csr` parameter. More...

pt_status_t	pt_device_certificate_renew_request_finish (const connection_id_t connection_id, const char *device_id, const pt_ce_status_e status)
	Finish device certificate renewal request. More...

void	pt_free_certificate_chain_context (struct cert_chain_context_s *context)
	Free a cert_chain_context_s structure passed to the certificate renewal notification callback.. More...

int	pt_api_init ()
	Use this function to initialize the PT API. More...

pt_client_t *	pt_client_create (const char socket_path, const protocol_translator_callbacks_t pt_cbs)
	Creates an instance of a PT API client. More...

void	pt_client_free (pt_client_t *client)
	Frees the PT API client. More...

connection_id_t	pt_client_get_connection_id (pt_client_t *client)
	May be used to get the connection ID from the client. More...

int	pt_client_start (pt_client_t client, pt_response_handler success_handler, pt_response_handler failure_handler, const char name, void *userdata)
	Starts the protocol translator client event loop and tries to connect to a local instance of Device Management Edge. When a connection is established, it tries to register the protocol translator. When registering succeeds the `success_handler` will be called. If registering fails the `failure_handler` will be called. This could happen for example, if the protocol translator name is already in use in Device Management Edge instance. More...

pt_status_t	pt_client_shutdown (pt_client_t *client)
	Gracefully shuts down the protocol translator client. More...

pt_status_t	pt_crypto_get_certificate (const connection_id_t connection_id, const char name, pt_crypto_get_item_success_handler success_handler, pt_crypto_get_item_failure_handler failure_handler, void userdata)
	Retrieve a certificate from secure storage. More...

pt_status_t	pt_crypto_get_public_key (const connection_id_t connection_id, const char name, pt_crypto_get_item_success_handler success_handler, pt_crypto_get_item_failure_handler failure_handler, void userdata)
	Retrieve a public key from secure storage. More...

pt_status_t	pt_crypto_generate_random (const connection_id_t connection_id, const size_t size, pt_crypto_success_handler success_handler, pt_crypto_failure_handler failure_handler, void *userdata)
	Generate and retrieve a random buffer from Device Management Edge. More...

pt_status_t	pt_crypto_asymmetric_sign (const connection_id_t connection_id, const char private_key_name, const char hash_digest, const size_t hash_digest_size, pt_crypto_success_handler success_handler, pt_crypto_failure_handler failure_handler, void *userdata)
	Perform asymmetric sign operation using given hash digest and private key stored in secure storage on Device Management Edge. More...

pt_status_t	pt_crypto_asymmetric_verify (const connection_id_t connection_id, const char public_key_name, const char hash_digest, const size_t hash_digest_size, const char signature, const size_t signature_size, pt_crypto_success_handler success_handler, pt_crypto_failure_handler failure_handler, void userdata)
	Perform asymmetric verify operation on given signature and hash digest using public key stored in secure storage on Device Management Edge. More...

pt_status_t	pt_crypto_ecdh_key_agreement (const connection_id_t connection_id, const char private_key_name, const char peer_public_key, const size_t peer_public_key_size, pt_crypto_success_handler success_handler, pt_crypto_failure_handler failure_handler, void *userdata)
	Perform ECDH key agreement using given peer public key and a private key stored in secure storage on Device Management Edge. More...

pt_status_t	ptdo_initialize_device_object (connection_id_t connection_id, const char device_id, const ptdo_device_object_data_t device_object_data)
	Create the device object ID:3. More...

pt_status_t	pt_devices_register_devices (const connection_id_t connection_id, pt_devices_cb devices_registration_success, pt_devices_cb devices_registration_failure, void *userdata)
	registers the devices that haven't been registered yet. More...

pt_status_t	pt_devices_unregister_devices (const connection_id_t connection_id, pt_devices_cb devices_unregistration_success, pt_devices_cb devices_unregistration_failure, void *userdata)
	Unregisters all the registered devices. More...

pt_status_t	pt_devices_update (const connection_id_t connection_id, pt_devices_cb success_handler, pt_devices_cb failure_handler, void *userdata)
	Updates the changed object structure from the endpoint device to Edge Core. More...

pt_userdata_t *	pt_api_create_userdata (void *data, pt_userdata_free_cb_t free_userdata_cb)
	Used to create the pt_userdata_s structure. More...

Detailed Description

Typedef Documentation

typedef void(* pt_certificate_renewal_notification_handler) (const connection_id_t connection_id, const char *name, int32_t initiator, int32_t status, const char *description, void *userdata)

Type definition for certificate renewal notification. This callback will be called to notify the status when a certificate renewal completes.

Parameters

connection_id	ID of the protocol translator connection.
name	The name of the certificate.
initiator	0 - device initiated the renewal 1 - cloud initiated the renewal
status	Status of the certificate renewal. 0 - for success. Non-zero if error happened. See error codes in `pt_ce_status_e` enum.
description	Description of the status in string form for human readability.
userdata.	The Userdata which was passed to `pt_client_start`.

typedef void(* pt_certificates_set_response_handler) (const connection_id_t connection_id, void *userdata)

Type definition for pt_certificate_renewal_list_set response success and failure handlers.

Parameters

connection_id	ID of the protocol translator connection.
userdata	User data given in `pt_certificate_renewal_list_set`.

typedef void(* pt_connection_ready_cb) (connection_id_t connection_id, const char *name, void *userdata)

A function prototype for calling the client code when the connection is ready for passing messages.

Parameters

[in]	connection_id	The ID of the connection which is ready.
[in]	name	The name of the protocol translator.
[in]	userdata	The user supplied data to pass back when the handler is called. The `userdata` was given to `pt_client_start()`.

typedef void(* pt_connection_shutdown_cb) (connection_id_t connection_id, void *userdata)

A function prototype for calling the client code when the connection is shutting down.

Parameters

[in]	connection_id	The ID of the protocol translator client connection.
[in]	userdata	The user supplied data to pass back when the handler is called. The `userdata` was given to `pt_client_start()`.

typedef void(* pt_crypto_failure_handler) (const connection_id_t connection_id, int error_code, void *userdata)

Type definition for a generic failure response handler.

Parameters

connection_id	ID of the protocol translator connection.
error_code	Error code indicating reason for failure.
userdata	The user-supplied context.

typedef void(* pt_crypto_get_item_failure_handler) (const connection_id_t connection_id, void *userdata)

Type definition for pt_crypto_get_item_failure_handler response failure handler.

Parameters

connection_id	ID of the protocol translator connection.
userdata	The user-supplied context.

typedef void(* pt_crypto_success_handler) (const connection_id_t connection_id, const uint8_t *data, const size_t size, void *userdata)

Type definition for a generic success handler returning a single buffer.

Parameters

connection_id	ID of the protocol translator connection.
data	Buffer containing the retrieved data.
size	Size of the retrieved data.
userdata	The user-supplied context.

typedef pt_status_t(* pt_device_certificate_renew_request_handler) (const connection_id_t connection_id, const char *device_id, const char *name, void *userdata)

Type definition for certificate renewal request handler for device certificate. This callback will be called when the cloud requests a device certificate to be renewed.

Parameters

connection_id	ID of the protocol translator connection.
device_id	The device ID.
name	The name of the certificate.
userdata.	The Userdata which was passed to `pt_client_start`.

Returns: The callback should return PT_STATUS_SUCCESS if the renewal process was started succesfully. If the renewal could not be started or there was some error, an error should be returned. See pt_status_t for possible error codes.

typedef void(* pt_device_certificate_renew_response_handler) (const connection_id_t connection_id, const char *device_id, const char *name, int32_t status, struct cert_chain_context_s *cert_chain, void *userdata)

Type definition for certificate renewal notification for device certificate. This callback will be called to notify the status when a certificate renewal completes for device certificate.

Parameters

connection_id	ID of the protocol translator connection.
device_id	The device ID.
name	The name of the certificate.
status	Status of the certificate renewal. 0 - for success. Non-zero if error happened. See error codes in `pt_ce_status_e` enum.
cert_chain	Structure containing the renewed certificate chain. This MUST be free'd using `pt_free_certificate_chain_context` function when callback is done with the data.
userdata.	The Userdata which was passed to `pt_client_start`.

typedef void(* pt_device_response_handler) (const connection_id_t connection_id, const char *device_id, void *userdata)

A function pointer type definition for callbacks given in the device API functions as an argument. This function definition is used for providing success and failure callback handlers.

The callbacks are run on the same thread as the event loop of the protocol translator client. If the related functionality of the callback is running a long process, you need to move it to a worker thread. If the process runs directly in the callback, it blocks the event loop, and thus the whole protocol translator.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID in context given as an argument.
[in]	userdata	The user-supplied context given as an argument in the protocol translator API function calls.

typedef void(* pt_devices_cb) (connection_id_t connection_id, void *userdata)

A function prototype for calling the client code when devices operation (for example: write, register or unregister) is done.

The callbacks are run on the same thread as the event loop of the protocol translator client. If the related functionality of the callback is running a long process, you need to move it to a worker thread. If the process runs directly in the callback, it blocks the event loop, and thus the whole protocol translator.

Parameters

[in]	connection_id	The connection ID of the protocol translator client connection.
[in]	userdata	The user supplied data to pass back when the handler is called.

typedef void(* pt_disconnected_cb) (connection_id_t connection_id, void *userdata)

A function prototype for calling the client code when the connection is disconnected.

Parameters

[in]	connection_id	The ID of the connection which disconnected.
[in]	userdata	The user supplied data to pass back the the handler is called. The `userdata` was given to `pt_client_start()`.

typedef pt_status_t(* pt_resource_callback) (const connection_id_t connection_id, const char *device_id, const uint16_t object_id, const uint16_t object_instance_id, const uint16_t resource_id, const uint8_t operation, const uint8_t *value, const uint32_t size, void *userdata)

Callback function prototype for the device resource specific action on OPERATION_WRITE or OPERATION_EXECUTE.

Note the value size for integers and floats which are received from Device Management Edge. This differs from the case when the protocol translator writes the value to Device Management Edge, where it is allowed to write different size binary values. When the write is coming from Device Management to Device Management Edge the value representation is text-format. Device Management Client does not store the original binary value and the original value size is lost. The interpretation of the value must be implemented in the callback function.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID targetted for this callback.
[in]	object_id	The object ID targetted.
[in]	object_instance_id	The object instance ID targetted.
[in]	resource_id	The resource ID targetted.
[in]	operation	The operation, for example OPERATION_WRITE.
[in]	value	A pointer to the value buffer. The ownership of the value buffer is within the `pt_resource_t` and the pointer is only valid for the duration of the function call. For different LwM2M data types there are byte-order restrictions as follows: String: UTF-8. Integer: A binary signed integer in network byte-order (64 bits). Float: IEEE 754-2008 floating point value in network byte-order (64 bits). Boolean: An 8 bit unsigned integer with value 0 or 1. Opaque: The sequence of binary data. Time: Same representation as integer. Objlnk: Two 16 bit unsigned integers one beside the other. The first one is the Object ID and the second is the Object Instance ID. Refer to: OMA Lightweight Machine to Machine Technical Specification for data type specifications.
[in]	size	The size of the value to write.
[in]	userdata	The user-supplied context.

Returns: Result of the resource callback function, should return PT_STATUS_SUCCESS when the operation was successful, see pt_status_t for possible error codes.

typedef void(* pt_resource_value_free_callback) (void *value)

Callback function prototype for freeing the resource value.

Parameters

[in] value Resource value to free.

typedef void(* pt_response_handler) (void *userdata)

A function pointer type definition for callbacks given in the protocol translator API functions as an argument. This function definition is used for providing success and failure callback handlers.

The callbacks are run on the same thread as the event loop of the protocol translator client. If the related functionality of the callback is running a long process, you need to move it to a worker thread. If the process runs directly in the callback, it blocks the event loop, and thus the whole protocol translator.

Parameters

[in] userdata The user-supplied context given as an argument in the protocol translator API functions.

typedef void(* pt_userdata_free_cb_t) (void *data)

The user-supplied memory deallocation function for userdata.

Parameters

[in] data The user-supplied data to free.

typedef struct pt_userdata_s pt_userdata_t

Contains fields for client user data.

If the client wants to associate data with the device or any object, this structure may be used. Create it using pt_api_create_userdata. The PT API will deallocate this structure and call the pt_free_userdata call-back when the object structure is destroyed. However the client is responsible to free the pt_userdata_t::data using the pt_userdata_t::pt_free_userdata call-back or in some other way.

typedef struct ptdo_device_object_data ptdo_device_object_data_t

The device object data ID:3.

NULL can be passed to optional values and no resource is generated for that field. The parameter strings must be NULL terminated.

Enumeration Type Documentation

enum pt_ce_status_e

Enumerator
CE_STATUS_SUCCESS	Operation completed successfully.
CE_STATUS_ERROR	Operation ended with an unspecified error.
CE_STATUS_INVALID_PARAMETER	A parameter provided to the function was invalid.
CE_STATUS_INSUFFICIENT_BUFFER	The provided buffer size was insufficient for the required output.
CE_STATUS_OUT_OF_MEMORY	An out-of-memory condition occurred.
CE_STATUS_ITEM_NOT_FOUND	The item was not found in the storage.
CE_STATUS_DEVICE_BUSY	The device is processing too many certificate renewals.
CE_STATUS_BAD_INPUT_FROM_SERVER	The server sent a TLV that is either unsupported or malformed.
CE_STATUS_EST_ERROR	An error during enrollment over secure transport (EST) occurred.
CE_STATUS_STORAGE_ERROR	The storage operation ended with an error.
CE_STATUS_RENEWAL_ITEM_VALIDATION_ERROR	Operation failed to validate renewal items.
CE_STATUS_BACKUP_ITEM_ERROR	Operation failed to create/read/validate backup items.
CE_STATUS_ORIGINAL_ITEM_ERROR	Operation failed to create/read/validate original items.
CE_STATUS_RESTORE_BACKUP_ERROR	Operation failed to restore backup items.
CE_STATUS_RENEWAL_STATUS_ERROR	Operation failed to create/validate/delete the renewal status file.
CE_STATUS_FORBIDDEN_REQUEST	The server asked for a forbidden operation (for example: the server is not allowed to renew the device's bootstrap certificate).
CE_STATUS_ITEM_IS_EMPTY	The item was found in the storage but its length is zero.
CE_STATUS_NOT_INITIALIZED	Called CertificateEnrollmentClient API before the initialization of the module.
CE_STATUS_INIT_FAILED	Initialization of the Certificate Enrollment module has failed. This error may be passed into MbedCloudClient::error callback.
CE_STATUS_PENDING	Operation will be complete asynchronously.

Function Documentation

pt_userdata_t* pt_api_create_userdata	(	void *	data,
		pt_userdata_free_cb_t	free_userdata_cb
	)

Used to create the pt_userdata_s structure.

Parameters

[in]	data	Pointer to client's data to associate.
[in]	free_userdata_cb	Pointer to function which will be called to free the data. NULL value is allowed. In this case no user data free function will be called. It's possible that there is no need to deallocate the data.

Returns: pointer to pt_userdata_t if memory allocation succeeds. NULL if memory allocation fails. In this case implementation calls free_userdata_cb immediately if applicable and frees the pt_userdata_t::data.

int pt_api_init ( )

Use this function to initialize the PT API.

This function should be called in the beginning in the PT API application's main thread and only once.

Returns: 0 if init succeeded 1 in case of an error.

pt_status_t pt_certificate_list_add	(	pt_certificate_list_t *	list,
		const char *	name
	)

Adds a certificate to certificate list.

Parameters

list	The certificate list. May not be NULL.
name	The name of the certificate. May not be NULL.

Returns: PT_STATUS_SUCCESS if certificate was added successfully.
Other error codes on failure.

pt_certificate_list_t* pt_certificate_list_create ( )

Creates a certificate list.

Returns: New certificate list. Delete it with pt_certificate_list_destroy.

pt_status_t pt_certificate_renew	(	const connection_id_t	connection_id,
		const char *	name,
		pt_certificate_renew_response_handler	success_handler,
		pt_certificate_renew_response_handler	failure_handler,
		void *	userdata
	)

Requests the renewal of the certificate specified by the name parameter.

Parameters

connection_id	ID of the protocol translator connection.
name	The name of the certificate. May not be NULL.
success_handler	This function is called if certificate renewal was successfully initiated. May not be NULL.
failure_handler	This function is called if certificate renewal failed. May not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if certificate renewal request was successfully sent.
Other error codes on failure.

pt_status_t pt_certificate_renewal_list_set	(	const connection_id_t	connection_id,
		pt_certificate_list_t *	list,
		pt_certificates_set_response_handler	success_handler,
		pt_certificates_set_response_handler	failure_handler,
		void *	userdata
	)

Sends the certificate list to Edge, triggering renewal subscriptions of the certificates in the list.

Parameters

connection_id	ID of the protocol translator connection.
list	The certificate list. Must be valid and may not be NULL.
success_handler	This function is called if certificate list was set successfully. May not be NULL.
failure_handler	This function is called if setting the certificate list failed. May not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if certificate setting request was successfully sent.
Other error codes on failure.

pt_client_t* pt_client_create	(	const char *	socket_path,
		const protocol_translator_callbacks_t *	pt_cbs
	)

Creates an instance of a PT API client.

Parameters

[in]	socket_path	The path to AF_UNIX domain socket to connect.
[in]	pt_cbs	A struct containing the callbacks to the customer side implementation.

Returns: Protocol translator client instance.

void pt_client_free ( pt_client_t * client )

Frees the PT API client.

Parameters

[in] client The protocol translator client structure to free.

connection_id_t pt_client_get_connection_id ( pt_client_t * client )

May be used to get the connection ID from the client.

Parameters

[in] client The client instance allocated using pt_client_create().

Returns: the id of the connection. PT_CONNECTION_ID_INVALID is returned if there is no active connection.

pt_status_t pt_client_shutdown ( pt_client_t * client )

Gracefully shuts down the protocol translator client.

Parameters

[in] client The client created using pt_client_create().

Returns: PT_STATUS_SUCCESS for successful initiation of the client shutdown. Other error codes for failure.

int pt_client_start	(	pt_client_t *	client,
		pt_response_handler	success_handler,
		pt_response_handler	failure_handler,
		const char *	name,
		void *	userdata
	)

Starts the protocol translator client event loop and tries to connect to a local instance of Device Management Edge. When a connection is established, it tries to register the protocol translator. When registering succeeds the success_handler will be called. If registering fails the failure_handler will be called. This could happen for example, if the protocol translator name is already in use in Device Management Edge instance.

Parameters

[in]	client	Client's data which can be created with `pt_client_create()`.
[in]	success_handler	A function pointer to be called when the protocol translator registration is successful.
[in]	failure_handler	A function pointer to be called when the protocol translator registration fails.
[in]	name	The protocol translator name, must be unique in the Device Management Edge instance.
[in]	userdata	The user-supplied context given as an argument to success and failure handler functions.

Returns: 1 if there is an error in configuring or starting the event loop.
The function returns when the event loop is shut down and the return value is 0.

pt_status_t pt_crypto_asymmetric_sign	(	const connection_id_t	connection_id,
		const char *	private_key_name,
		const char *	hash_digest,
		const size_t	hash_digest_size,
		pt_crypto_success_handler	success_handler,
		pt_crypto_failure_handler	failure_handler,
		void *	userdata
	)

Perform asymmetric sign operation using given hash digest and private key stored in secure storage on Device Management Edge.

Parameters

connection_id	ID of the protocol translator connection.
private_key_name	Name of the private key to use.
hash_digest	Hash digest to sign.
hash_digest_size	Size of the hash digest buffer.
success_handler	This function is called if the asymmetric sign operation was successful. Must not be NULL.
failure_handler	This function is called if the asymmetric sign operation failed. Must not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if the asymmetric sign request was sent successfully.
Other error codes on failure.

pt_status_t pt_crypto_asymmetric_verify	(	const connection_id_t	connection_id,
		const char *	public_key_name,
		const char *	hash_digest,
		const size_t	hash_digest_size,
		const char *	signature,
		const size_t	signature_size,
		pt_crypto_success_handler	success_handler,
		pt_crypto_failure_handler	failure_handler,
		void *	userdata
	)

Perform asymmetric verify operation on given signature and hash digest using public key stored in secure storage on Device Management Edge.

Parameters

connection_id	ID of the protocol translator connection.
public_key_name	Name of the public key to use.
hash_digest	Hash digest to verify.
hash_digest_size	Size of the hash digest buffer.
signature	Signature to verify.
signature_size	Size of the signature buffer.
success_handler	This function is called if the asymmetric verify operation was successful. Must not be NULL.
failure_handler	This function is called if the asymmetric verify operation failed. Must not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if the asymmetric verify request was sent successfully.
Other error codes on failure.

pt_status_t pt_crypto_ecdh_key_agreement	(	const connection_id_t	connection_id,
		const char *	private_key_name,
		const char *	peer_public_key,
		const size_t	peer_public_key_size,
		pt_crypto_success_handler	success_handler,
		pt_crypto_failure_handler	failure_handler,
		void *	userdata
	)

Perform ECDH key agreement using given peer public key and a private key stored in secure storage on Device Management Edge.

Parameters

connection_id	ID of the protocol translator connection.
private_key_name	Name of the private key to use.
peer_public_key	Peer public key in DER format.
peer_public_key_size	Size of the peer public key buffer.
success_handler	This function is called if the ECDH key agreement operation was successful. Must not be NULL.
failure_handler	This function is called if the ECDH key agreement operation failed. Must not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if the ECDH key agreement request was sent successfully.
Other error codes on failure.

pt_status_t pt_crypto_generate_random	(	const connection_id_t	connection_id,
		const size_t	size,
		pt_crypto_success_handler	success_handler,
		pt_crypto_failure_handler	failure_handler,
		void *	userdata
	)

Generate and retrieve a random buffer from Device Management Edge.

Parameters

connection_id	ID of the protocol translator connection.
size	Size of the random buffer to generate.
success_handler	This function is called if the random buffer is generated successfully. Must not be NULL.
failure_handler	This function is called if the random buffer generation fails. Must not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if random buffer was generation request was sent successfully.
Other error codes on failure.

pt_status_t pt_crypto_get_certificate	(	const connection_id_t	connection_id,
		const char *	name,
		pt_crypto_get_item_success_handler	success_handler,
		pt_crypto_get_item_failure_handler	failure_handler,
		void *	userdata
	)

Retrieve a certificate from secure storage.

Parameters

connection_id	ID of the protocol translator connection.
name	Name of the certificate to retrieve.
success_handler	This function is called if the certificate is retrieved successfully. Must not be NULL.
failure_handler	This function is called if the certificate retrieval fails. Must not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if certificate retrieval request was sent successfully.
Other error codes on failure.

pt_status_t pt_crypto_get_public_key	(	const connection_id_t	connection_id,
		const char *	name,
		pt_crypto_get_item_success_handler	success_handler,
		pt_crypto_get_item_failure_handler	failure_handler,
		void *	userdata
	)

Retrieve a public key from secure storage.

Parameters

connection_id	ID of the protocol translator connection.
name	Name of the public key to retrieve.
success_handler	This function is called if the public key is retrieved successfully. Must not be NULL.
failure_handler	This function is called if the public key retrieval fails. Must not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if public key retrieval request was sent successfully.
Other error codes on failure.

pt_status_t pt_device_add_resource	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id,
		const char *	resource_name,
		const Lwm2mResourceType	type,
		uint8_t *	value,
		uint32_t	value_size,
		pt_resource_value_free_callback	value_free_cb
	)

Adds a read-only resource to a device.

This function does not set any callbacks to the created resource. The created resource functions only as a read-only resource from the Pelion Cloud perspective. The value can be updated directly from the wrapping application. The read-only restriction applies only to requests coming from Pelion Cloud. The protocol translator application may write new values to the resource with `pt_device_set_resource_value()' function and in the end update the set value by calling pt_device_write_values() function.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to which to add the resource.
[in]	object_id	The object ID to which to add the resource.
[in]	object_instance_id	The object instance ID to which to add the resource.
[in]	resource_id	The resource ID for the added resource.
[in]	resource_name	The optional resource name for the added resource.
[in]	type	The resource type.
[in]	value	A pointer to the value buffer. The ownership of the value buffer is within the `pt_client_t`. When the resource is destroyed or a new value buffer is set by calling `pt_device_set_resource_value()` the `value_free_cb()` is called with the old value buffer as parameter. For different LwM2M data types there are byte-order restrictions as follows: String: UTF-8. Integer: A binary signed integer in network byte-order (8, 16, 32 or 64 bits). Float: IEEE 754-2008 floating point value in network byte-order (32 or 64 bits). Boolean: An 8 bit unsigned integer with value 0 or 1. Opaque: The sequence of binary data. Time: Same representation as integer. Objlnk: Two 16 bit unsigned integers one beside the other. The first one is the Object ID and the second is the Object Instance ID. Refer to: OMA Lightweight Machine to Machine Technical Specification for data type specifications.
[in]	value_size	The size of the value buffer.
[in]	value_free_cb	A callback function to free the value buffer that will be called when the resource is destroyed or a new value buffer is assigned.

Returns: PT_STATUS_SUCCESS on successful resource create.
See pt_status_t for possible error codes. Note: if there is an error, it will call the value_free_cb() to avoid a memory leak.

pt_status_t pt_device_add_resource_with_callback	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id,
		const char *	resource_name,
		const Lwm2mResourceType	type,
		const uint8_t	operations,
		uint8_t *	value,
		uint32_t	value_size,
		pt_resource_value_free_callback	value_free_cb,
		pt_resource_callback	callback
	)

Adds a resource to a device with a callback.

This function creates a resource with allowed operations specified by operations. The callback is set for the write and execute actions and are triggered when corresponding requests are received from Device Management.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to which to add the resource.
[in]	object_id	The object ID to which to add the resource.
[in]	object_instance_id	The object instance ID to which to add the resource.
[in]	resource_id	The resource ID for the added resource.
[in]	resource_name	The optional resource name for the added resource.
[in]	type	The resource type.
[in]	operations	The operations this resource will allow. For example, GET/OPERATION_READ and PUT/OPERATION_WRITE. The value is a bit field of allowed operations. If OPERATION_WRITE is set to flags, the parameter for `callback` must be populated. If OPERATION_EXECUTE is set to flags, the parameter for `callback` must be populated. Now, you can have a combination of OPERATION_EXECUTE and OPERATION_WRITE for the resource.

Note: Note the difference when writing a value from the protocol translator to Device Management Edge opposed to receiving a write from Device Management Edge. It is allowed to write different sized binary integers and float towards Device Management Edge. On the other hand, when receiving a write from Device Management Edge, the integer or float value is always 64 bit.

Parameters

[in]	value	The pointer to value buffer. The ownership of the value buffer is within the `pt_resource_t`. When the resource is destroyed or a new value buffer is set by calling `pt_device_set_resource_value()` the `value_free_cb` is called with the old value buffer as parameter. For different LwM2M data types there are byte-order restrictions as follows: String: UTF-8 Integer: A binary signed integer in network byte-order (8, 16, 32 or 64 bits). Float: IEEE 754-2008 floating point value in network byte-order (32 or 64 bits). Boolean: An 8 bit unsigned integer with value 0 or 1. Opaque: The sequence of binary data. Time: Same representation as integer. Objlnk: Two 16 bit unsigned integers one beside the other. The first one is the Object ID and the second is the Object Instance ID. Refer to: OMA Lightweight Machine to Machine Technical Specification for data type specifications.
[in]	value_size	The size of the value buffer.
[in]	value_free_cb	A callback function to free the value buffer that will be called when the resource is destroyed or a new value buffer is assigned.
[in]	callback	Optional callback for this resource. The callback can be given when the resource has OPERATION_WRITE and/or OPERATION_EXECUTE set to allowed operations.

Returns: PT_STATUS_SUCCESS on successful resource create.
See pt_status_t for possible error codes. Note: if there is an error, it will call the value_free_cb() to avoid a memory leak.

pt_status_t pt_device_certificate_renew	(	const connection_id_t	connection_id,
		const char *	device_id,
		const char *	name,
		const char *	csr,
		const size_t	csr_length,
		pt_device_certificate_renew_response_handler	success_handler,
		pt_device_certificate_renew_response_handler	failure_handler,
		void *	userdata
	)

Requests the renewal of the certificate specified by the name parameter using the certificate signing request specified by the csr parameter.

Parameters

connection_id	ID of the protocol translator connection.
device_id	The device ID.
name	The name of the certificate. May not be NULL.
csr	The certificate signing request. May not be NULL.
csr_length	Length of the certificate signing request.
success_handler	This function is called if the certificate renewal was successful. May not be NULL.
failure_handler	This function is called if the certificate renewal failed. May not be NULL.
userdata	The user-supplied context.

Returns: PT_STATUS_SUCCESS if certificate renewal request was successfully sent.
Other error codes on failure.

pt_status_t pt_device_certificate_renew_request_finish	(	const connection_id_t	connection_id,
		const char *	device_id,
		const pt_ce_status_e	status
	)

Finish device certificate renewal request.

Parameters

connection_id	ID of the protocol translator connection.
device_id	The ID of device.
status	The status of the certificate renewal process, CE_STATUS_SUCCESS for successful renewal, see `pt_ce_status_e` enum for possible error codes.

Returns: PT_STATUS_SUCCESS if certificate renewal was finished successfully.
Other error codes on failure.

pt_status_t pt_device_create	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint32_t	lifetime,
		const queuemode_t	queuemode
	)

Creates the device structure.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The unique device identifier.
[in]	lifetime	The expected lifetime for the device. The device registrations must be updated. This parameter is reserved and currently not used. The translated endpoints are tracked withing the parent Edge device lifetime.
[in]	queuemode	The queue mode before the time is elapsed. This parameter is reserved, but currently not used.

Returns: PT_STATUS_SUCCESS in case of success. Other error codes for failure.

pt_status_t pt_device_create_with_feature_flags	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint32_t	lifetime,
		const queuemode_t	queuemode,
		const uint32_t	features,
		pt_userdata_t *	userdata
	)

Creates the device structure and enables additional features.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The unique device identifier.
[in]	lifetime	The expected lifetime for the device. The device registrations must be updated. This parameter is reserved and currently not used. The translated endpoints are tracked withing the parent Edge device lifetime.
[in]	queuemode	The queue mode before the time is elapsed. This parameter is reserved, but currently not used.
[in]	features	The feature flags for enabling features this device supports. See `pt_device_feature_e` enum in `pt_common_api.h` for supported feature flags.
[in]	userdata	The user data to add to the `pt_device_t` structure. Create this structure with `pt_api_create_device_userdata()`.

Returns: PT_STATUS_SUCCESS in case of success. Other error codes for failure. Note! In case of an error where the status parameter returns something else than PT_STATUS_SUCCESS the userdata free function will NOT be called and the userdata should be freed by the user.

pt_status_t pt_device_create_with_userdata	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint32_t	lifetime,
		const queuemode_t	queuemode,
		pt_userdata_t *	userdata
	)

Creates the device structure.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The unique device identifier.
[in]	lifetime	The expected lifetime for the device. The device registrations must be updated. This parameter is reserved and currently not used. The translated endpoints are tracked withing the parent Edge device lifetime.
[in]	queuemode	The queue mode before the time is elapsed. This parameter is reserved, but currently not used.
[in]	userdata	The user data to add to the `pt_device_t` structure. Create this structure with `pt_api_create_device_userdata()`.

Returns: PT_STATUS_SUCCESS in case of success. Other error codes for failure. Note! In case of an error where the status parameter returns something else than PT_STATUS_SUCCESS the userdata free function will NOT be called and the userdata should be freed by the user.

bool pt_device_exists	(	const connection_id_t	connection_id,
		const char *	device_id
	)

Utility function to check if device already exists for the connection.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to find.

Returns: True if device is found. False if not.

pt_status_t pt_device_get_feature_flags	(	const connection_id_t	connection_id,
		const char *	device_id,
		uint32_t *	features
	)

Retrieves the feature flags of a device.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The unique device identifier.
[out]	features	Pointer to a uint32_t variable, On success it will contain the feature flags. On failure the value will be undefined. See `pt_device_feature_e` enum in `pt_common_api.h` for supported feature flags.

Returns: PT_STATUS_SUCCESS in case of success. Other error codes for failure.

int32_t pt_device_get_next_free_object_instance_id	(	connection_id_t	connection_id,
		const char *	device_id,
		uint16_t	object_id
	)

Get the id of first free object instance for given object.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID of the device.
[in]	object_id	The object ID of which next free object instance ID got.

Returns: Return the object instance id of the first free object instance in object. Returns -1 if the connection or device does not exist, if the object doesn't exist 0 is returned as that would be the first free object instance if the object was created.

pt_status_t pt_device_get_resource_value	(	connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id,
		uint8_t **	value_out,
		uint32_t *	value_len_out
	)

Utility function to get the current value in a resource.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID of device to get the resource value.
[in]	object_id	The object ID of the object which resource value to get.
[in]	object_instance_id	The object instance ID of the object instance which resource value to get.
[in]	resource_id	The resource ID of the resource which value to get.
[out]	value_out	On success it's updated to point at the value of the resource.
[out]	value_len_out	On success it returns the size of the resource.

Returns: PT_STATUS_SUCCESS in on success. Other error codes on failure.

pt_userdata_t* pt_device_get_userdata	(	connection_id_t	connection_id,
		const char *	device_id
	)

Retrieve the set user data in the device.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to find.

Returns: Pointer to the user data structure. If there's no such device or no user data for the existing device, a NULL is returned.

pt_status_t pt_device_register	(	const connection_id_t	connection_id,
		const char *	device_id,
		pt_device_response_handler	success_handler,
		pt_device_response_handler	failure_handler,
		void *	userdata
	)

Endpoint device registration function. Every endpoint device must be registered with the protocol translator and Device Management Edge before reading and writing device values.

Parameters

[in]	connection_id	The connection ID of the requesting application.
[in]	device_id	The device ID of the device to register.
[in]	success_handler	A function pointer that gets called when the device registration is successful.
[in]	failure_handler	A function pointer that gets called when the device registration fails.
[in]	userdata	The user-supplied context given as an argument to success and failure handler functions.

Returns: The status of the device registration operation.
PT_STATUS_SUCCESS on successful registration.
See pt_status_t for possible error codes.

bool pt_device_resource_exists	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id
	)

Utility function to check if resource already exists for the connection and device.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to find.
[in]	object_id	The object ID to find.
[in]	object_instance_id	The object instance ID to find.
[in]	resource_id	The resource ID to find.

Returns: True if resource is found. False if not.

pt_status_t pt_device_set_resource_value	(	const connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id,
		const uint8_t *	value,
		uint32_t	value_len,
		pt_resource_value_free_callback	value_free_cb
	)

Set a new value to resource in the device.

This function does not update the value to Edge Core. Call pt_device_write_values() to initiate messaging to Edge Core. This function can called multiple times for the device before updating the value to Edge Core.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID targetted for the write.
[in]	object_id	The object ID targetted.
[in]	object_instance_id	The object instance ID targetted.
[in]	resource_id	The resource ID targetted.
[in]	value	The value to write to the resource.
[in]	value_len	The size of the value to write.
[in]	value_free_cb	A callback function to free the value buffer that will be called when the resource is destroyed or a new value buffer is assigned.

Returns: PT_STATUS_SUCCESS in case of success. Other error codes for failure. Note! If this function returns any error, the value_free_cb will be called to avoid a memory leak.

pt_status_t pt_device_set_userdata	(	connection_id_t	connection_id,
		const char *	device_id,
		pt_userdata_t *	userdata
	)

Set the set user data to the device. This may be useful if the client needs to associate some extra data with the device. Create the userdata using the API function pt_api_create_userdata().

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to find.
[in]	userdata	Pointer to the user data structure.

Returns: PT_STATUS_SUCCESS if the device was found and the userdata was set successfully. Other error codes if setting userdata fails.

pt_status_t pt_device_unregister	(	const connection_id_t	connection_id,
		const char *	device_id,
		pt_device_response_handler	success_handler,
		pt_device_response_handler	failure_handler,
		void *	userdata
	)

Endpoint device unregistration function. If the device unregistration succeeds, the device instance data will be freed from memory.

Parameters

[in]	connection_id	The connection ID of the requesting application.
[in]	device_id	The device ID of the device to unregister.
[in]	success_handler	A function pointer that gets called when the device unregistration is successful.
[in]	failure_handler	A function pointer that gets called when the device unregistration fails.
[in]	userdata	The user-supplied context given as an argument to success and failure handler functions.

Returns: The status of the device unregistration operation.
PT_STATUS_SUCCESS on successful unregistration.
See pt_status_t for possible error codes.

pt_status_t pt_device_write_values	(	const connection_id_t	connection_id,
		const char *	device_id,
		pt_device_response_handler	success_handler,
		pt_device_response_handler	failure_handler,
		void *	userdata
	)

Writes changed values from the endpoint device to Edge Core.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device from which to write the value to Edge Core.
[in]	success_handler	A function pointer to be called when the value was written successfully.
[in]	failure_handler	A function pointer to be called when the writing fails.
[in]	userdata	The user-supplied context given as an argument to the success and failure handler functions.

Returns: The status of the write value operation.
PT_STATUS_SUCCESS on successful write.
See pt_status_t for possible error codes. Note: doesn't call the callbacks if PT_STATUS_INVALID_PARAMETERS or PT_STATUS_NOT_CONNECTED is returned.

pt_status_t pt_devices_register_devices	(	const connection_id_t	connection_id,
		pt_devices_cb	devices_registration_success,
		pt_devices_cb	devices_registration_failure,
		void *	userdata
	)

registers the devices that haven't been registered yet.

The callback is run on the same thread as the event loop of the protocol translator client. If the related functionality of the callback does some long processing the processing must be moved to worker thread. If the processing is run directly in the callback it will block the event loop and therefore it will block the whole protocol translator.

Parameters

[in]	connection_id	The connection ID of the protocol translator client connection.
[in]	devices_registration_success	The function to call if all the devices registered successfully.
[in]	devices_registration_failure	The function to call if some of the devices couldn't be registered.
[in]	userdata	Pointer to user's data. This will be passed back in the callback functions.

Returns: PT_STATUS_SUCCESS in case there is no error. Other error codes when it fails. See pt_status_t for possible error codes.

pt_status_t pt_devices_unregister_devices	(	const connection_id_t	connection_id,
		pt_devices_cb	devices_unregistration_success,
		pt_devices_cb	devices_unregistration_failure,
		void *	userdata
	)

Unregisters all the registered devices.

The callback is run on the same thread as the event loop of the protocol translator client. If the related functionality of the callback does some long processing the processing must be moved to worker thread. If the processing is run directly in the callback it will block the event loop and therefore it will block the whole protocol translator.

If unregistration succeeds, it deletes the device instances from memory. If unregistration fails the device instances remain in memory to allow retrying to unregister the devices.

Parameters

[in]	connection_id	The connection ID of the protocol translator client connection.
[in]	devices_unregistration_success	The function to call if all the devices unregistered successfully.
[in]	devices_unregistration_failure	The function to call if some of the devices couldn't be unregistered.
[in]	userdata	Pointer to user's data. This will be passed back in the callback functions.

Returns: PT_STATUS_SUCCESS in case there is no error. Other error codes when it fails. See pt_status_t for possible error codes.

pt_status_t pt_devices_update	(	const connection_id_t	connection_id,
		pt_devices_cb	success_handler,
		pt_devices_cb	failure_handler,
		void *	userdata
	)

Updates the changed object structure from the endpoint device to Edge Core.

The callback is run on the same thread as the event loop of the protocol translator client. If the related functionality of the callback does some long processing the processing must be moved to worker thread. If the processing is run directly in the callback it will block the event loop and therefore it will block the whole protocol translator.

Parameters

[in]	connection_id	The connection ID.
[in]	success_handler	A function pointer to be called when the object structure was updated successfully.
[in]	failure_handler	A function pointer to be called when the the object structure update failed.
[in]	userdata	The user-supplied context given as an argument to the success and failure handler functions.

Returns: The status of the write value operation.
PT_STATUS_SUCCESS on successful write.
See pt_status_t for possible error codes.

void pt_free_certificate_chain_context ( struct cert_chain_context_s * context )

Free a cert_chain_context_s structure passed to the certificate renewal notification callback..

Parameters

context Pointer to the cert_chain_context_s structure to free.

pt_userdata_t* pt_resource_get_userdata	(	connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id
	)

Retrieve the set user data in the resource. Client needs to provide the full path to the resource.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to find.
[in]	object_id	The object ID to find.
[in]	object_instance_id	The object instance ID to find.
[in]	resource_id	The resource ID to find.

Returns: Pointer to the user data structure. If there's no such resource or no user data for the existing resource, a NULL is returned.

pt_status_t pt_resource_set_userdata	(	connection_id_t	connection_id,
		const char *	device_id,
		const uint16_t	object_id,
		const uint16_t	object_instance_id,
		const uint16_t	resource_id,
		pt_userdata_t *	userdata
	)

Set the set user data to the resource. This may be useful if the client needs to associate some extra data with the device. Create the userdata using the API function pt_api_create_userdata(). Client needs to provide the full path to the resource.

Parameters

[in]	connection_id	The ID of the connection of the requesting application.
[in]	device_id	The device ID to find.
[in]	object_id	The object ID to find.
[in]	object_instance_id	The object instance ID to find.
[in]	resource_id	The resource ID to find.
[in]	userdata	Pointer to the user data structure.

Returns: PT_STATUS_SUCCESS if the resource was found and the userdata was set successfully. Other error codes if setting userdata fails.

pt_status_t ptdo_initialize_device_object	(	connection_id_t	connection_id,
		const char *	device_id,
		const ptdo_device_object_data_t *	device_object_data
	)

Create the device object ID:3.

The following mandatory resources are always generated:

Reboot, executable resource ID:4.
Error code, readable resource ID:11. Supports only one instance.

The LwM2M mandatory resource for binding mode ID:16 is not created. Future implementations may create the resource.

Parameters

[in]	connection_id	The connection ID to associate the device objects.
[in]	device_id	The device ID to initialize with `\3` object and resources.
[in]	device_object_data	The struct containing the values and function pointer for the `\3` object and resources. This function assumes that device_object_data structure is initialized. The function copies the string resource values from the `device_object_data` structure into internal buffers which allows passing in static, stack allocated or heap allocated values.

Returns: The status of the device object initialization operation.
PT_STATUS_SUCCESS on successful initialize.
See pt_status_t for possible error codes.

Documentation

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation