User Tools

Site Tools


common_resources

Common Properties

Every resource when responded has a common resource properties which is specified in the most of the response.

The common properties in the response structure includes:

  1. Name
  2. Resource Identity
  3. Resource Type
  4. Resource Interface

These properties are unique among all resources and are not to be used as values.

Name

This is the human readable form of the resource. This is not mandatory field and only application that set the value, will have this value set in the response sent.

This value is not set as part of OCCreateResource and has to be set explicitly to enable. Once this value is set it appears in reponse for /oic/res and /oic/d.

C API

To set device name in the C Stack, the below API is used:

  OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);

OCDeviceInfo can include following information :

  • Device Name,
  • Resource Types
  • Specification version
  • Data model version

All above fields can be set via OCSetDeviceInfo. Device name is mandatory to be included if this API is used, and all other values are optional.

Example : https://github.com/iotivity/iotivity/blob/master/resource/csdk/stack/samples/linux/SimpleClientServer/ocserver.cpp

Above example uses the above API and how to set the value using this API.

C++ API

C++ API uses registerDeviceInfo to set the device name, resource types, specification version anda data model version. As in C API, deviceName is the only one mandatory and all other fields are optional.

 
  OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);

It is a wrapper and uses OCSetDeviceInfo internally to store device information.

Example : https://github.com/iotivity/iotivity/blob/master/resource/examples/devicediscoveryserver.cpp

Resource Identity

It is a unique instance identifier for a specific instance of the resource.

Currently there is no API and is not generated. This value can be a unique ordinal number, or a unique string, or a UUID. This is currently only used in the Resource Directory functionality.

Resource Type

Resource type defines the category or class of resources. The resource will be part of one or more of the resource type. Each resource will belong to one or more resource type. It is a mandatory field and every resource should include this information.

OCF standard specifies a pre-defined resource type. OCF defines a RAML and JSON schema, all device OCF supporte device have access to these RAML and JSON, and can interpret the types.

Resouce type can be custom defined too and requires out of band communication or RAML/JSON schema to describe endpoint to interpret the resource type.

Resource type is assigned when resource is created. It is in lowercase separated by '.' to include namespace information.

In IoTivity resource type is assigned to the resource when it is created. CreateResource includes a field to include all resource type the resource will include.

IoTivity supports following resource type:

Resource Type Name Resource type value
Device oic.wk.d
Platform oic.wk.p
Discovery oic.wk.res
Presence oic.wk.ad

There resource are created by IoTivity stack and are mandatory resource types and are present in all OCF certified devices.

* Please note there are resource type for security resources and resource directory too.

Resource type value are returned in form of string array i.e. [“oic.wk.d”].

C API

  • There are 2 ways resource type can be specified for the resource.
    • Using OCCreateResource API, where it can take only one resource type.
  OCStackResult OCCreateResource(OCResourceHandle *handle,** const char *resourceTypeName**, ...);
  • To add more resource type, OCBindResourceTypeToResource can be used:
  OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle, const char *resourceTypeName);
  • To access the number of resourcetype a resource has OCGetNumberOfResourceTypes can be used:
  OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);
  • To retrieve a resource type, OCGetResourceTypeName
  const char* OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);
  • To delete a resource type ther eis no, OCDeleteResource can be used:
  OCStackResult OCDeleteResource(OCResourceHandle* handle);

C++ API

C++ API has more API to add and retrieve resource type. Please note all API internally rely on C API to handle all the functionality. C++ API are wrapper on top of C APIs.

  • To add resource type to the resource
    • Using registerResource API.
  OCStackResult registerResource(OCResourceHandle &handle,** std::string &resourceTypeName**, ...);
  • To add more resource type, bindTypeToResource, setResourceTypes and addResourceType can be used:
  OCStackResult bindTypeToResource(OCResourceHandle& handle, const std::string& resourceTypeName);
  • To retrieve a resource type, getResourceTypes
  const std::vector<std::string>& getResourceTypes() const;
  • To delete a resource type there is no API, but a resource can be deleted using unregisterResource API.
  OCStackResult unregisterResource(const OCResourceHandle &resourceHandle);

Resource Interface

Interface is a combination of two things:

  • It provides view about how the response will appear.
  • It provides read/write permission details for the resource.

OCF has defined a few interfaces and can be defined by vendor or different verticals too. Interface field includes all the type supported. Default interface is defined by OCF and has to be included for the resource.

All resource support baseline interface (oic.if.baseline) and is a default interface. There is only one exception, /oic/res default interface is linked list (oic.if.ll) interface.

Interface is passed as part of the query request. If the request does not include interface, the IoTivity uses default interface to respond back to the query.

Below are the interfaces that specify how the response will returned by the server. These interface by the client to retrieve information from the server.

Name Interface
Baselineoic.if.baseline It includes all the information about the resource including meta-data and collection information about the resources. This is the default interface type.
Linked Listoic.if.ll It includes only the collection information about the resources. This is the default interface type for /oic/res.
Batch oic.if.b It allows aggregating interaction with all resources. Each resource will be interacted separately, and response from them will be aggregated.

The other interface type are related to permissions. These are relevant for retrieve and update requests.

Read oic.if.r It allows only permission to read.
Read Write oic.if.rw It allows to both read and write.
Actuator oic.if.a It includes creating, updating and retrieving actuator values.
Sensor oic.if.s It allows only reading the sensor values.

C API

The API used for declaring interface type resembles how resource type is created.

There are 2 ways resource type can be specified for the resource.

  • Using OCCreateResource API, where it can take only one interface.
  OCStackResult OCCreateResource(OCResourceHandle *handle, const char *resourceTypeName, ** const char *interfaceType *);
  • To add more interface type, OCBindResourceInterfaceTypeToResource can be used:
  OCStackResult OCBindResourceInteraceTypeToResource(OCResourceHandle handle, const char *interfaceTypeName);
  • To access the number of interfaceType, a resource has OCGetNumberOfResourceInterfaces can be used:
  OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);
  • To retrieve a interface type, OCGetResourceInterfaceName
  const char* OCGetResourceIntefaceName(OCResourceHandle handle, uint8_t index);
  • To delete a interface type there is no API, but OCDeleteResource can be used which deletes the whole resource:
  OCStackResult OCDeleteResource(OCResourceHandle* handle);

C++ API

C++ API has more API to add and retrieve interface type. Please note all API internally rely on C API to handle all the functionality. C++ API are wrapper on top of C APIs.

  • To add interface type to the resource. Using registerResource API.
  OCStackResult registerResource(OCResourceHandle &handle, std::string &resourceTypeName, ** std::string interfaceName, **…);
  • To add more interface type, bindInterfaceToResource can be used:
  OCStackResult bindInterfaceToResource(OCResourceHandle& handle, const std::string& interfaceTypeName);
  • To retrieve a interface type,
  const std::vector<std::string>& getResourceInterfaces() const;
  • To delete a resource type there is no API, but a resource can be deleted using unregisterResource API.
  OCStackResult unregisterResource(const OCResourceHandle &resourceHandle);
common_resources.txt · Last modified: 2016/10/07 13:55 by Phil Coval