Mistake on this page? Email us
pt_api.h
Go to the documentation of this file.
1 /*
2  * ----------------------------------------------------------------------------
3  * Copyright 2018 ARM Ltd.
4  *
5  * SPDX-License-Identifier: Apache-2.0
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  * ----------------------------------------------------------------------------
19  */
20 
21 #ifndef PT_API_VERSION
22 #define PT_API_VERSION 2
23 #endif
24 #if PT_API_VERSION != 2
25 #error "Including mixed versions of Protocol API"
26 #endif
27 
28 #ifndef PT_API_H_
29 #define PT_API_H_
30 
36 #include <stdbool.h>
37 
42 
43 #ifdef MBED_EDGE_SUBDEVICE_FOTA
44 #include "pt-client-2/pt_firmware_download_api_internal.h"
45 #endif // MBED_EDGE_SUBDEVICE_FOTA
46 
182 typedef pt_status_t (*pt_resource_callback)(const connection_id_t connection_id,
183  const char *device_id,
184  const uint16_t object_id,
185  const uint16_t object_instance_id,
186  const uint16_t resource_id,
187  const uint8_t operation,
188  const uint8_t *value,
189  const uint32_t size,
190  void *userdata);
191 
197 typedef void (*pt_resource_value_free_callback)(void *value);
198 
211 typedef void (*pt_device_response_handler)(const connection_id_t connection_id, const char *device_id, void *userdata);
212 
229 pt_status_t pt_device_create_with_userdata(const connection_id_t connection_id,
230  const char *device_id,
231  const uint32_t lifetime,
232  const queuemode_t queuemode,
233  pt_userdata_t *userdata);
234 
235 #ifdef MBED_EDGE_SUBDEVICE_FOTA
236 
237 pt_status_t pt_device_add_manifest_callback(const connection_id_t connection_id,
238  manifest_metadata_handler cb);
239 
240 pt_status_t pt_download_asset(const connection_id_t connection_id,
241  const char *device_id,
242  uint64_t size,
243  pt_download_cb success_handler,
244  pt_download_cb failure_handler,
245  void *userdata);
246 
247 #endif // MBED_EDGE_SUBDEVICE_FOTA
248 
267 pt_status_t pt_device_create_with_feature_flags(const connection_id_t connection_id,
268  const char *device_id,
269  const uint32_t lifetime,
270  const queuemode_t queuemode,
271  const uint32_t features,
272  pt_userdata_t *userdata);
273 
286 pt_status_t pt_device_create(const connection_id_t connection_id,
287  const char *device_id,
288  const uint32_t lifetime,
289  const queuemode_t queuemode);
290 
302 pt_status_t pt_device_get_feature_flags(const connection_id_t connection_id,
303  const char *device_id,
304  uint32_t *features);
305 
321 pt_status_t pt_device_register(const connection_id_t connection_id,
322  const char *device_id,
323  pt_device_response_handler success_handler,
324  pt_device_response_handler failure_handler,
325  void *userdata);
326 
342 pt_status_t pt_device_unregister(const connection_id_t connection_id,
343  const char *device_id,
344  pt_device_response_handler success_handler,
345  pt_device_response_handler failure_handler,
346  void *userdata);
347 
363 pt_status_t pt_device_write_values(const connection_id_t connection_id,
364  const char *device_id,
365  pt_device_response_handler success_handler,
366  pt_device_response_handler failure_handler,
367  void *userdata);
368 
388 pt_status_t pt_device_set_resource_value(const connection_id_t connection_id,
389  const char *device_id,
390  const uint16_t object_id,
391  const uint16_t object_instance_id,
392  const uint16_t resource_id,
393  const uint8_t *value,
394  uint32_t value_len,
395  pt_resource_value_free_callback value_free_cb);
396 
405 bool pt_device_exists(const connection_id_t connection_id, const char *device_id);
406 
418 bool pt_device_resource_exists(const connection_id_t connection_id,
419  const char *device_id,
420  const uint16_t object_id,
421  const uint16_t object_instance_id,
422  const uint16_t resource_id);
423 
464 pt_status_t pt_device_add_resource(const connection_id_t connection_id,
465  const char *device_id,
466  const uint16_t object_id,
467  const uint16_t object_instance_id,
468  const uint16_t resource_id,
469  const char *resource_name,
470  const Lwm2mResourceType type,
471  uint8_t *value,
472  uint32_t value_size,
473  pt_resource_value_free_callback value_free_cb);
474 
526 pt_status_t pt_device_add_resource_with_callback(const connection_id_t connection_id,
527  const char *device_id,
528  const uint16_t object_id,
529  const uint16_t object_instance_id,
530  const uint16_t resource_id,
531  const char *resource_name,
532  const Lwm2mResourceType type,
533  const uint8_t operations,
534  uint8_t *value,
535  uint32_t value_size,
536  pt_resource_value_free_callback value_free_cb,
537  pt_resource_callback callback);
538 
552 pt_status_t pt_device_get_resource_value(connection_id_t connection_id,
553  const char *device_id,
554  const uint16_t object_id,
555  const uint16_t object_instance_id,
556  const uint16_t resource_id,
557  uint8_t **value_out,
558  uint32_t *value_len_out);
559 
571 int32_t pt_device_get_next_free_object_instance_id(connection_id_t connection_id,
572  const char *device_id,
573  uint16_t object_id);
574 
584 pt_userdata_t *pt_device_get_userdata(connection_id_t connection_id, const char *device_id);
585 
598 pt_userdata_t *pt_resource_get_userdata(connection_id_t connection_id,
599  const char *device_id,
600  const uint16_t object_id,
601  const uint16_t object_instance_id,
602  const uint16_t resource_id);
603 
615 pt_status_t pt_device_set_userdata(connection_id_t connection_id, const char *device_id, pt_userdata_t *userdata);
616 
632 pt_status_t pt_resource_set_userdata(connection_id_t connection_id,
633  const char *device_id,
634  const uint16_t object_id,
635  const uint16_t object_instance_id,
636  const uint16_t resource_id,
637  pt_userdata_t *userdata);
638 
644 #endif /* PT_API_H_ */
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.
Lwm2mResourceType
LwM2M resource type enumeration constants.
Definition: constants.h:48
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.
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 d...
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.
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.
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 tra...
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...
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 d...
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.
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.
Contains the interface to manage multiple devices.
void(* pt_resource_value_free_callback)(void *value)
Callback function prototype for freeing the resource value.
Definition: pt_api.h:197
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.
Protocol translator API for client&#39;s data.
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...
Contains common structures and definitions for the protocol translator client.
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...
Definition: pt_api.h:211
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.
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_E...
Definition: pt_api.h:182
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.
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.
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.
pt_userdata_t * pt_device_get_userdata(connection_id_t connection_id, const char *device_id)
Retrieve the set user data in the device.
pt_status_t
Enumeration containing the possible return status codes for Protocol API functions.
Definition: pt_common_api.h:51
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.
Contains fields for client user data.
Definition: pt_userdata_api.h:62
Contains the interface to create, connect, register, unregister and shut down the protocol translator...