The protocol translator API v1 is deprecated. The API will exist until end of 2019. More...
Files | |
file | client.h |
**Deprecated** Protocol translator client for API v1. | |
file | pt_api.h |
**Deprecated** Protocol translator client for API v1. | |
file | pt_device_object.h |
**Deprecated** A utility header to contain the LwM2M device object ID:3 creation for mediated endpoints. | |
Data Structures | |
struct | pt_resource |
struct | pt_object_instance |
struct | pt_object |
struct | pt_device_userdata_s |
Contains fields for client user data. More... | |
struct | pt_device |
struct | client_data_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... | |
Typedefs | |
typedef struct pt_resource | pt_resource_t |
typedef struct pt_resource | pt_resource_opaque_t |
typedef struct pt_object_instance | pt_object_instance_t |
typedef struct pt_object | pt_object_t |
typedef struct pt_device | pt_device_t |
typedef void(* | pt_device_free_userdata_cb_t) (void *data) |
typedef struct pt_device_userdata_s | pt_device_userdata_t |
Contains fields for client user data. More... | |
typedef struct client_data_s | client_data_t |
typedef struct protocol_translator_callbacks | protocol_translator_callbacks_t |
A structure to hold the callbacks of the protocol translator. | |
typedef struct connection | connection_t |
typedef struct ptdo_device_object_data | ptdo_device_object_data_t |
The device object data ID:3. More... | |
Functions | |
DEPRECATED (struct connection *connection_init(struct context *ctx, client_data_t *client_data, const protocol_translator_callbacks_t *pt_cbs, void *userdata)) | |
Initializes the connection structure between Device Management Edge and the connected protocol translator. More... | |
DEPRECATED (void pt_client_set_msg_id_generator(generate_msg_id generate_msg_id)) | |
Set the message id generation function. More... | |
DEPRECATED (void pt_client_final_cleanup()) | |
This function cleans used memory, e.g. unhandled requests. More... | |
DEPRECATED (typedef void(*pt_resource_callback)(const pt_resource_t *resource, 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... | |
DEPRECATED (typedef void(*pt_connection_ready_cb)(struct connection *connection, void *userdata)) | |
A function prototype for calling the client code when the connection is ready for passing messages. More... | |
DEPRECATED (typedef void(*pt_connection_shutdown_cb)(struct connection **connection, void *userdata)) | |
A function prototype for calling the client code when the connection is shutting down. More... | |
DEPRECATED (typedef int(*pt_received_write_handler)(struct connection *connection, const char *device_id, const uint16_t object_id, const uint16_t instance_id, const uint16_t resource_id, const unsigned int operation, const uint8_t *value, const uint32_t value_size, void *userdata)) | |
Function pointer type definition for handling received message from Edge Core. More... | |
typedef | NS_LIST_HEAD (pt_resource_t, link) pt_resource_list_t |
typedef | NS_LIST_HEAD (pt_object_instance_t, link) pt_object_instance_list_t |
typedef | NS_LIST_HEAD (pt_object_t, link) pt_object_list_t |
DEPRECATED (typedef void(*pt_response_handler)(void *userdata)) | |
A function pointer type definition for callbacks given in the protocol translator API functions as an argument. More... | |
DEPRECATED (typedef void(*pt_device_response_handler)(const char *device_id, void *userdata)) | |
A function pointer type definition for callbacks given in the device API functions as an argument. More... | |
DEPRECATED (pt_status_t pt_register_protocol_translator(connection_t *connection, pt_response_handler success_handler, pt_response_handler failure_handler, void *userdata)) | |
Protocol translator registration function. Every protocol translator must register itself with Edge before starting to handle endpoint related functions. More... | |
DEPRECATED (pt_status_t pt_register_device(connection_t *connection, pt_device_t *device, 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 Edge before reading and writing device values. More... | |
DEPRECATED (pt_status_t pt_unregister_device(connection_t *connection, pt_device_t *device, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void *userdata)) | |
Endpoint device unregistration function. More... | |
DEPRECATED (pt_device_userdata_t *pt_api_create_device_userdata(void *data, pt_device_free_userdata_cb_t free_userdata_cb)) | |
Used to create the pt_device_userdata_s structure. More... | |
DEPRECATED (pt_device_t *pt_create_device_with_userdata(char *device_id, const uint32_t lifetime, const queuemode_t queuemode, pt_status_t *status, pt_device_userdata_t *userdata)) | |
Creates the device structure. More... | |
DEPRECATED (pt_device_t *pt_create_device(char *device_id, const uint32_t lifetime, const queuemode_t queuemode, pt_status_t *status)) | |
Creates the device structure. More... | |
DEPRECATED (void pt_device_free(pt_device_t *device)) | |
Deallocates the reserved memory for the device structure. More... | |
DEPRECATED (pt_object_t *pt_device_add_object(pt_device_t *device, uint16_t id, pt_status_t *status)) | |
Adds an object to a device. More... | |
DEPRECATED (pt_object_t *pt_device_find_object(pt_device_t *device, uint16_t id)) | |
Finds an object from the device. More... | |
DEPRECATED (pt_object_instance_t *pt_object_add_object_instance(pt_object_t *object, uint16_t id, pt_status_t *status)) | |
Adds an object instance to an object. More... | |
DEPRECATED (pt_object_instance_t *pt_object_find_object_instance(pt_object_t *object, uint16_t id)) | |
Finds an object instance from object. More... | |
DEPRECATED (pt_resource_t *pt_object_instance_add_resource(pt_object_instance_t *object_instance, uint16_t id, Lwm2mResourceType type, uint8_t *value, uint32_t value_size, pt_status_t *status)) | |
Adds a read-only resource to an object instance. More... | |
DEPRECATED (pt_resource_t *pt_object_instance_add_resource_with_callback(pt_object_instance_t *object_instance, uint16_t id, Lwm2mResourceType type, uint8_t operations, uint8_t *value, uint32_t value_size, pt_status_t *status, pt_resource_callback callback)) | |
Adds a resource to an object instance with callbacks. More... | |
DEPRECATED (pt_resource_t *pt_object_instance_find_resource(pt_object_instance_t *instance, uint16_t id)) | |
Finds a resource from an object instance. More... | |
DEPRECATED (pt_status_t pt_write_value(connection_t *connection, pt_device_t *device, pt_object_list_t *objects, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void *userdata)) | |
Writes the value from the endpoint device to Edge Core. More... | |
DEPRECATED (int pt_receive_write_value(json_t *request, json_t *json_params, json_t **result, void *userdata)) | |
The function to handle the received write calls from Edge Core. More... | |
DEPRECATED (int pt_client_start(const char *socket_path, const char *name, const protocol_translator_callbacks_t *pt_cbs, void *userdata, connection_t **connection)) | |
Starts the protocol translator client event loop and tries to connect to a local instance of Edge. More... | |
DEPRECATED (void pt_client_shutdown(connection_t *connection)) | |
Gracefully shuts down the protocol translator client. More... | |
DEPRECATED (pt_status_t ptdo_initialize_device_object(pt_device_t *device, ptdo_device_object_data_t *device_object_data)) | |
Create the device object ID:3. More... | |
The protocol translator API v1 is deprecated. The API will exist until end of 2019.
typedef struct pt_device_userdata_s pt_device_userdata_t |
Contains fields for client user data.
If the client wants to associate data with the device, this structure may be used. Create this structure using pt_api_create_device_userdata. The PT API will deallocate this structure and call the pt_device_free_userdata call-back when the pt_device_t structure is destroyed. However the client is responsible to free the pt_device_userdata_t::data using the pt_device_userdata_t::pt_device_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.
DEPRECATED | ( | struct connection * | connection_initstruct context *ctx, client_data_t *client_data, const protocol_translator_callbacks_t *pt_cbs, void *userdata | ) |
Initializes the connection structure between Device Management Edge and the connected protocol translator.
ctx | The program context. |
protocol_translator | The protocol translator context. |
pt_cbs | The protocol translator user supplied callback functions. |
DEPRECATED | ( | void | pt_client_set_msg_id_generatorgenerate_msg_id generate_msg_id | ) |
Set the message id generation function.
generate_msg_id | The function pointer or NULL. If NULL is given, a default implementation is selected. |
DEPRECATED | ( | void | pt_client_final_cleanup() | ) |
This function cleans used memory, e.g. unhandled requests.
DEPRECATED | ( | pt_status_t | ptdo_initialize_device_objectpt_device_t *device, ptdo_device_object_data_t *device_object_data | ) |
Create the device object ID:3.
The following mandatory resources are always generated:
The LwM2M mandatory resource for binding mode ID:16 is not created. Future implementations may create the resource.
device | The device object to initialize with \3 object and resources. |
device_object_data | The struct containing the values and function pointer for the \3 object and resources. |
PT_STATUS_SUCCESS
on successful initialize.DEPRECATED | ( | typedef void(*)(const pt_resource_t *resource, const uint8_t *value, const uint32_t size, void *userdata) | pt_resource_callback | ) |
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 Edge Core. This differs from the case when the protocol translator writes the value to Edge Core where it is allowed to write different size binary values. When the write is coming from Device Management to Edge Core 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.
resource | The resource that the action was triggered on. |
value | A pointer to the value buffer. The ownership of the value buffer is within the pt_resource_t . For different LwM2M data types there are byte-order restrictions as follows:
|
size | The size of the value to write. |
userdata | The user-supplied context. |
DEPRECATED | ( | typedef void(*)(struct connection *connection, void *userdata) | pt_connection_ready_cb | ) |
A function prototype for calling the client code when the connection is ready for passing messages.
A function prototype for calling the client code when the connection is disconnected.
connection | The connection which is ready. |
userdata | The user supplied data to pass back when the handler is called. |
connection | The connection which disconnected. |
userdata | The user supplied data to pass back the the handler is called. |
DEPRECATED | ( | typedef void(*)(struct connection **connection, void *userdata) | pt_connection_shutdown_cb | ) |
A function prototype for calling the client code when the connection is shutting down.
connection | The connection reference of the protocol translator client connection. |
userdata | The user supplied data to pass back when the handler is called. |
DEPRECATED | ( | typedef int(*)(struct connection *connection, const char *device_id, const uint16_t object_id, const uint16_t instance_id, const uint16_t resource_id, const unsigned int operation, const uint8_t *value, const uint32_t value_size, void *userdata) | pt_received_write_handler | ) |
Function pointer type definition for handling received message from Edge Core.
The callbacks are 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.
connection | The connection which this write originates. |
device_id | The device ID to write the data. |
object_id | The object ID to write the data. |
instance_id | The instance ID to write the data. |
resource_id | The resource ID to write the data. |
operation | The operation of the write. |
value | The pointer to byte data to write. |
value_size | The length of the data. |
userdata | The pointer to user supplied data from pt_client_start . |
DEPRECATED | ( | typedef void(*)(void *userdata) | pt_response_handler | ) |
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.
userdata | The user-supplied context given as an argument in the protocol translator API functions. |
DEPRECATED | ( | typedef void(*)(const char *device_id, void *userdata) | pt_device_response_handler | ) |
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.
device_id | The device ID in context given as an argument. |
userdata | The user-supplied context given as an argument in the protocol translator API functions. |
DEPRECATED | ( | pt_status_t | pt_register_protocol_translatorconnection_t *connection, pt_response_handler success_handler, pt_response_handler failure_handler, void *userdata | ) |
Protocol translator registration function. Every protocol translator must register itself with Edge before starting to handle endpoint related functions.
connection | The connection of the requesting application. |
success_handler | A function pointer to be called when the protocol translator registration is successful. |
failure_handler | A function pointer to be called when the protocol translator registration fails. |
userdata | The user-supplied context given as an argument to success and failure handler functions. |
PT_STATUS_SUCCESS
on successful registration.DEPRECATED | ( | pt_status_t | pt_register_deviceconnection_t *connection, pt_device_t *device, 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 Edge before reading and writing device values.
connection | The connection of the requesting application. |
device | The structure containing structured information of the device to be registered. |
success_handler | A function pointer that gets called when the device registration is successful. |
failure_handler | A function pointer that gets called when the device registration fails. |
userdata | The user-supplied context given as an argument to success and failure handler functions. |
PT_STATUS_SUCCESS
on successful registration.DEPRECATED | ( | pt_status_t | pt_unregister_deviceconnection_t *connection, pt_device_t *device, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void *userdata | ) |
Endpoint device unregistration function.
connection | The connection of the requesting application. |
device | The structure containing structured information of the device to be unregistered. |
success_handler | A function pointer that gets called when the device unregistration is successful. |
failure_handler | A function pointer that gets called when the device unregistration fails. |
userdata | The user-supplied context given as an argument to success and failure handler functions. |
PT_STATUS_SUCCESS
on successful unregistration.DEPRECATED | ( | pt_device_userdata_t * | pt_api_create_device_userdatavoid *data, pt_device_free_userdata_cb_t free_userdata_cb | ) |
Used to create the pt_device_userdata_s structure.
data | Pointer to client's data to associate with the device. |
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. |
pt_device_userdata_t
if memory allocation succeeds. NULL if memory allocation fails. In this case calls free_userdata_cb
immediately if applicable. DEPRECATED | ( | pt_device_t * | pt_create_device_with_userdatachar *device_id, const uint32_t lifetime, const queuemode_t queuemode, pt_status_t *status, pt_device_userdata_t *userdata | ) |
Creates the device structure.
device_id | The unique device identifier. The ownership of the device_id is transferred to returned pt_device_t |
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. |
queuemode | The queue mode before the time is elapsed. |
status | A pointer to user provided variable for the operation status output. If a device was created, the status will be set to PT_STATUS_SUCCESS . |
userdata | The user data to add to the pt_device_t structure. Create this structure with pt_api_create_device_userdata . Note! If memory allocation fails in this function, userdata free function call-back will be called immediately. |
DEPRECATED | ( | pt_device_t * | pt_create_devicechar *device_id, const uint32_t lifetime, const queuemode_t queuemode, pt_status_t *status | ) |
Creates the device structure.
device_id | The unique device identifier. The ownership of the device_id is transferred to returned pt_device_t |
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. |
queuemode | The queue mode before the time is elapsed. |
status | A pointer to user provided variable for the operation status output. If a device was created, the status will be set to PT_STATUS_SUCCESS . |
DEPRECATED | ( | void | pt_device_freept_device_t *device | ) |
Deallocates the reserved memory for the device structure.
The structure is iterated and all lists and reserved data structures are freed.
pt_device | The structure to deallocate for. |
DEPRECATED | ( | pt_object_t * | pt_device_add_objectpt_device_t *device, uint16_t id, pt_status_t *status | ) |
Adds an object to a device.
device | The device to which the object list is added. |
id | The object ID of the added object. |
status | A pointer to user provided variable for the operation status output. If a device was created, the status is set to PT_STATUS_SUCCESS . |
pt_device_t
. DEPRECATED | ( | pt_object_t * | pt_device_find_objectpt_device_t *device, uint16_t id | ) |
Finds an object from the device.
device | The device object. |
id | The object ID to find from the device. |
pt_device_t
DEPRECATED | ( | pt_object_instance_t * | pt_object_add_object_instancept_object_t *object, uint16_t id, pt_status_t *status | ) |
Adds an object instance to an object.
object | The object to which to add the object instance. |
id | The object instance ID of the added object instance. |
status | A pointer to user provided variable for the operation status output. If a device was created, the status is set to PT_STATUS_SUCCESS . |
pt_object_t
. DEPRECATED | ( | pt_object_instance_t * | pt_object_find_object_instancept_object_t *object, uint16_t id | ) |
Finds an object instance from object.
object | The object. |
id | The object instance ID to find from the object. |
pt_object_t
. DEPRECATED | ( | pt_resource_t * | pt_object_instance_add_resourcept_object_instance_t *object_instance, uint16_t id, Lwm2mResourceType type, uint8_t *value, uint32_t value_size, pt_status_t *status | ) |
Adds a read-only resource to an object instance.
This function does not set any callbacks to the created resource. The created resource functions only as a read-only resource. The value can be updated directly from the wrapping application. The read-only restriction applies only to requests coming from Device Management.
object_instance | The object instance to which to add the resource. |
id | The resource ID for the added resource. |
type | The resource type. |
value | A pointer to the value buffer. The ownership of the value buffer is within the pt_resource_t . For different LwM2M data types there are byte-order restrictions as follows:
|
value_size | The size of the value buffer. |
status | A pointer to user provided variable for the operation status output. If a device was created, the status is set to PT_STATUS_SUCCESS |
pt_object_instance_t
. DEPRECATED | ( | pt_resource_t * | pt_object_instance_add_resource_with_callbackpt_object_instance_t *object_instance, uint16_t id, Lwm2mResourceType type, uint8_t operations, uint8_t *value, uint32_t value_size, pt_status_t *status, pt_resource_callback callback | ) |
Adds a resource to an object instance with callbacks.
This function creates a resource with allowed operations specified by operations
. The callbacks are set for the read and execute actions and are triggered when corresponding requests are received from Device Management.
object_instance | The object instance to which to add the resource. |
id | The resource ID of the added resource. |
type | The resource type. |
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.
|
value | The pointer to value buffer. The ownership of the value buffer is within the pt_resource_t . For different LwM2M data types there are byte-order restrictions as follows:
|
value_size | The size of the value buffer. |
status | A pointer to the user provided variable for the operation status output. If a device was created, the status is set to PT_STATUS_SUCCESS |
callback | The callbacks for this resource. The callbacks can be given when the resource has OPERATION_WRITE and/or OPERATION_EXECUTE set to allowed operations. |
pt_object_instance_t
DEPRECATED | ( | pt_resource_t * | pt_object_instance_find_resourcept_object_instance_t *instance, uint16_t id | ) |
Finds a resource from an object instance.
instance | The object instance. |
id | The resource ID to find from the object instance. |
pt_object_instance_t
. DEPRECATED | ( | pt_status_t | pt_write_valueconnection_t *connection, pt_device_t *device, pt_object_list_t *objects, pt_device_response_handler success_handler, pt_device_response_handler failure_handler, void *userdata | ) |
Writes the value from the endpoint device to Edge Core.
connection | The connection of the requesting application. |
device | The device from which to write the value to Edge Core. |
objects | The full object structure of the objects, object instances and resources to write. |
success_handler | A function pointer to be called when the value was written successfully. |
failure_handler | A function pointer to be called when the writing fails. |
userdata | The user-supplied context given as an argument to the success and failure handler functions. |
PT_STATUS_SUCCESS
on successful write.DEPRECATED | ( | int | pt_receive_write_valuejson_t *request, json_t *json_params, json_t **result, void *userdata | ) |
The function to handle the received write calls from Edge Core.
request | The request object. |
json_params | The params object from JSON request. |
result | The output parameter to return the result of the function. |
userdata | The internal RPC supplied context. |
DEPRECATED | ( | int | pt_client_startconst char *socket_path, const char *name, const protocol_translator_callbacks_t *pt_cbs, void *userdata, connection_t **connection | ) |
Starts the protocol translator client event loop and tries to connect to a local instance of Edge.
socket_path | The path to AF_UNIX domain socket to connect. |
name | The protocol translator name, must be unique in the Edge instance. The protocol translator API cleans the reserved memory for the name when closing down. |
pt_cbs | A struct containing the callbacks to the customer side implementation. |
userdata | The user data |
connection | Reference to running connection. Must be passed to protocol translator API functions. |
DEPRECATED | ( | void | pt_client_shutdownconnection_t *connection | ) |
Gracefully shuts down the protocol translator client.