User Tools

Site Tools


common_resources

Common Properties

Every resource has common properties that are specified in the majority of their responses.

The common properties in the response structure include

  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; it's a mandatory field and only applications that set the value will have this value set in the responses they receive from the server.

This value is not set as part of OCCreateResource, but rather must be set explicitly to enable it. Once the value is set, it appears in reponses for /oic/res and /oic/d.

C API

Here is the relevant function.

From iotivity/resource/csdk/stack/include/ocstack.h:

  • OCSetDeviceInfo - A function that sets device information

It is used like this:

  OCStackResult OCSetDeviceInfo(OCDeviceInfo deviceInfo);

OCDeviceInfo can include

  • Device name,
  • Resource types,
  • Specification version, and
  • Data model version

The device name is mandatory when this API is used, all other values are optional.

For Example: iotivity/resource/csdk/stack/samples/linux/SimpleClientServer/ocserver.cpp

This example demonstrates the API and how to set values using it.

C++ API

The C++ API uses OC::OCPlatform::registerDeviceInfo to set the

  • Device name,
  • Resource types,
  • Specification version, and
  • Data model version.

Like the C API, the device name is the only mandatory field, all others are optional. It's a wrapper that uses OCSetDeviceInfo internally to store the device information. Here's an example of how it is used:

 
  OCStackResult registerDeviceInfo(const OCDeviceInfo deviceInfo);

Here is an example that demonstrates this API: iotivity/resource/examples/devicediscoveryserver.cpp

Resource Identity

The resource identity is a unique instance identifier for a specific instance of a resource. This value can be a unique ordinal number, a unique string, or a UUID.

Currently, there is no API to modify it, and it isn't generated. This is currently only used in the resource directory functionality.

Resource Type

Resource type defines the category or class of resources, each resource will be part of one or more of the resource types. It's a mandatory field and every resource should include this information.

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

Resource types can also be custom defined and require an out of band communication or RAML/JSON schema to describe to endpoints how to interpret the resource type.

In IoTivity resource type is assigned to the resource when it is created; It's in lowercase separated by '.' to include namespace information. CreateResource includes a field to include all resource types the resource will include.

IoTivity supports the following resource types:

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

These resources are created by the IoTivity stack and are mandatory resource types that are present in all OCF certified devices.

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

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

C API

OCCreateResource - A single interface type can be added to the resource when it's initially created:

  OCStackResult OCCreateResource(OCResourceHandle *handle,** const char *resourceTypeName**, ...);

OCBindResourceTypeToResource - add more resource types:

  OCStackResult OCBindResourceTypeToResource(OCResourceHandle handle, const char *resourceTypeName);

OCGetNumberOfResourceTypes - access the number of resource types a resource has:

  OCStackResult OCGetNumberOfResourceTypes(OCResourceHandle handle, uint8_t *numResourceTypes);

OCGetResourceTypeName - retrieve a resource type:

  const char* OCGetResourceTypeName(OCResourceHandle handle, uint8_t index);

OCDeleteResource - delete a resource. Please note: there is no API available to delete only an interface type, it's only possible to delete the entire resource:

  OCStackResult OCDeleteResource(OCResourceHandle* handle);

C++ API

The C++ API has more functions to add and retrieve resource types. Please note: all API rely on the C API internally to handle all functionality. The C++ API functions are wrappers on top of C APIs.

OCPlatform::registerResource - A single interface type can be added to the resource when it's initially created:

  OCStackResult registerResource(OCResourceHandle &handle,** std::string &resourceTypeName**, ...);

OCPlatform::bindTypeToResource, OCPlatform::setResourceTypes and OCPlatform::addResourceType - add more resource types:

  OCStackResult bindTypeToResource(OCResourceHandle& handle, const std::string& resourceTypeName);

OCPlatform::getResourceTypes - retrieve a resource type:

  const std::vector<std::string>& getResourceTypes() const;

OCPlatform::unregisterResource - delete a resource. Please note: there is no API available to delete only an interface type, it's only possible to delete the entire resource:

  OCStackResult unregisterResource(const OCResourceHandle &resourceHandle);

Resource Interface

The 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. The interface field includes all the types that are supported. The default interface is defined by the OCF and must be included for the resource.

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

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

The table below shows the interfaces that specify how the response will be returned by the server. These interfaces can be used by the client to retrieve information from the server.

Name Interface Explanation
Baselineoic.if.baseline Includes all information about the resource, including meta-data and collection information. This is the default interface type.
Linked Listoic.if.ll Includes only the collection information about the resource. This is the default interface type for /oic/res.
Batch oic.if.b Allows for the aggregation of interaction with all resources. Each resource will be interacted with separately, but their responses will be aggregated.

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

Name Interface Explanation
Read oic.if.r Allows values to be read.
Read Write oic.if.rw Allows values to be read and written.
Actuator oic.if.a Allows creating, updating, and retrieving actuator values.
Sensor oic.if.s Allows the sensor values to be read.

C API

The API used for declaring and modifying interface types is similar to resource types.

OCCreateResource - A single interface type can be added to the resource when it's initially created:

  OCStackResult OCCreateResource(OCResourceHandle *handle, const char *resourceTypeName, ** const char *interfaceType *);

OCBindResourceInterfaceTypeToResource - add more interface types to a resource:

  OCStackResult OCBindResourceInteraceTypeToResource(OCResourceHandle handle, const char *interfaceTypeName);

OCGetNumberOfResourceInterfaces - access the number of interface types a resource has:

  OCStackResult OCGetNumberOfResourceInterfaces(OCResourceHandle handle, uint8_t *numResourceInterfaces);

OCGetResourceInterfaceName - retrieve an interface type:

  const char* OCGetResourceIntefaceName(OCResourceHandle handle, uint8_t index);

OCDeleteResource - delete a resource. Please note: there is no API available to delete only an interface type, it's only possible to delete the entire resource.

  OCStackResult OCDeleteResource(OCResourceHandle* handle);

C++ API

The C++ API has additional API to add and retrieve interface types. Please note: all API rely on the C API internally to handle functionality. The C++ API is a wrapper on top of the C API.

OCPlatform::registerResource - A single interface type can be added to the resource when it's initially created:

  OCStackResult registerResource(OCResourceHandle &handle, std::string &resourceTypeName, ** std::string interfaceName, **…);

OCPlatform::bindInterfaceToResource - add more interface types:

  OCStackResult bindInterfaceToResource(OCResourceHandle& handle, const std::string& interfaceTypeName);

OCPlatform::getResourceInterfaces - retrieve a interface type:

  const std::vector<std::string>& getResourceInterfaces() const;

OCPlatform::unregisterResource - delete a resource. Please note: there is no API available to delete only an interface type, it's only possible to delete the entire resource:

  OCStackResult unregisterResource(const OCResourceHandle &resourceHandle);

Next Steps

Once you've completed this section of the guide, continue to the section on the collection resource

common_resources.txt · Last modified: 2017/08/04 15:11 by Mats Wichmann