pt_api.h File Reference
Protocol translator external API V2. More...
#include <stdbool.h>#include "pt-client-2/pt_common_api.h"#include "pt-client-2/pt_client_api.h"#include "pt-client-2/pt_userdata_api.h"#include "pt-client-2/pt_devices_api.h"Go to the source code of this file.
Macros | |
| #define | PT_API_VERSION 2 |
| #define | PT_API_H_ |
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... | |
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... | |
Detailed Description
Protocol translator external API V2.
The protocol translator is used for bridging the non-LwM2M endpoint devices with the help of Device Management Edge to Device Management.
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 Device Management 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.
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_id as first argument. This specifies the connection to write the requests. Callbacks will have a userdata argument, which is the user data that the application 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 the customer callbacks. If there is a long running operation for the responses in the callback handlers, you should move that into another thread.
An example of registering the protocol translator with the customer callbacks:
#include <stdio.h>
#include "pt-client-2/pt_api.h"
struct user_context {
char *data;
};
void connection_ready_handler(connection_id_t connection_id, const char *name, void *userdata)
{
struct user_context *user_context = (struct user_context *) userdata;
printf("Connection between protocol translator and Core service ready ('%s').\n", user_context->data);
}
void protocol_translator_register_success(void *userdata)
{
struct user_context *user_context = (struct user_context *) userdata;
printf("Protocol translator registration success ('%s').\n", user_context->data);
}
void protocol_translator_register_failed(void *userdata)
{
struct user_context *user_context = (struct user_context *) userdata;
printf("Protocol translator registration failed ('%s').\n", user_context->data);
}
void shutdown_cb_handler(connection_id_t connection_id, void *userdata)
{
struct user_context *user_context = (struct user_context *) userdata;
printf("Received shutdown from the Edge Core, closing down ('%s').\n", user_context->data);
// ... some data processing with the connection and devices ...
}
void disconnected_handler(connection_id_t connection_id, void *userdata)
{
struct user_context *user_context = (struct user_context *) userdata;
printf("Disconnected from Edge Core ('%s').\n", user_context->data);
// ... some data processing with the connection and devices ...
}
int main(int argc, char **argv)
{
if (argc != 2) {
fprintf(stderr, "Usage: pt-client <protocol translator name>\n");
return 1;
}
// Initialize the protocol translator API.
pt_api_init();
protocol_translator_callbacks_t pt_cbs;
pt_cbs.connection_ready_cb = connection_ready_handler;
pt_cbs.disconnected_cb = disconnected_handler;
pt_cbs.connection_shutdown_cb = shutdown_cb_handler;
char *name = argv[1];
struct user_context user_context;
user_context.data = "example-userdata";
pt_client_t *client;
client = pt_client_create("/tmp/edge.sock", &pt_cbs);
pt_client_start(client,
protocol_translator_register_success,
protocol_translator_register_failed,
name,
&user_context);
pt_client_free(client);
return 0;
}
Refer to pt-example/client_example.c in the https://github.com/PelionIoT/mbed-edge-examples repository for the example use of full protocol translator API.