pt_api.h File Reference
**Deprecated** Protocol translator client for API v1. More...
#include "ns_list.h"#include "common/constants.h"#include "common/default_message_id_generator.h"#include "edge-rpc/rpc.h"Go to the source code of this file.
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... | |
Macros | |
| #define | PT_API_H_ |
| #define | DEPRECATED(func) func |
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 |
Functions | |
| 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... | |
Detailed Description
**Deprecated** Protocol translator client for API v1.
- Deprecated:
- The protocol translator API v1 is deprecated. The API will exist until end of 2019.
The protocol translator is used for bridging the non-LwM2M endpoint devices with the help of Edge to Pelion Cloud.
The protocol translator client start function is defined in this header. It is the main entry point to initiate the communication between the protocol translator and Edge. It starts up the event loop and keeps it running. The pt_client_start() function does not return until the event loop is shut down.
#include <stdio.h>
#include <stdint.h>
#include "pt-client/pt_api.h"
void connection_ready_handler(connection_t *connection, void *userdata)
{
printf("Connection between protocol translator and Core service ready.\n");
}
int received_write_handler(connection_t *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)
{
printf("Received write from the Edge Core.\n");
}
void shutdown_cb_handler(connection_t **connection, void* userdata)
{
printf("Received shutdown from the Edge Core, closing down.\n");
}
int main(int argc, char **argv)
{
if (argc != 3) {
fprintf(stderr, "Usage: pt-client <protocol translator name>\n");
return 1;
}
connection_t *connection = NULL;
protocol_translator_callbacks_t pt_cbs;
pt_cbs.connection_ready_cb = connection_ready_handler;
pt_cbs.received_write_cb = received_write_handler;
pt_cbs.connection_shutdown_cb = shutdown_cb_handler;
char *name = argv[1];
void *userdata = (void*) "example_userdata";
pt_client_start('/tmp/edge.sock', name, &pt_cbs, userdata, connection);
return 0;
}
The API functions define the success and failure callback handlers that are called from an internal event loop. Therefore, make sure that the operations in the callbacks do not block the event loop. All API functions must have the connection as first argument. This is the connection to write the requests. Callbacks will have an userdata argument, which is the application user data set in the protocol translator API calls. Blocking the event loop blocks the protocol translator and it cannot continue until the control is given back to the event loop from customer callbacks. If there is a long running operation for the responses in the callback handlers, you should move that into a thread.
An example of registering the protocol translator with the customer callbacks:
struct user_context
{
char *data;
};
static void registration_success(void *userdata)
{
printf("Protocol translator registration successful.\n");
struct user_context *user_context = (struct user_context*) userdata;
// work with the user_context->data
}
static void registration_failure(void *userdata)
{
printf("Protocol translator registration failed.\n");
struct user_context *user_context = (struct user_context*) userdata;
free(user_context->data);
free(user_context);
}
static void device_registered_successfully(const char* device_id, void *userdata)
{
//device_id would be 'test-device'
// work with the userdata
}
static void device_register_failed(const char* device_id, void *userdata)
{
//device_id would be 'test-device'
// work with the userdata
}
struct user_context *user_context = malloc(sizeof(struct user_context));
user_context->data = "Data...";
pt_register_protocol_translator(connection, registration_success, registration_failure, user_context);
pt_device_t device = pt_create_device(strdup("test-device")...);
pt_register_device(connection, device, device_registered_successfully,
device_register_failed, user_context);
Refer to pt-client/client_example.c for the example use of full protocol translator API.