APIs Device to Cloud One M2 M CIN - ContentInstance
The contentInstance resource (resourceType=4) represents a data instance in the container
resource.
Unlike other resources, the contentInstance resource shall not be modified once created. This pertains to its attributes, but not to the creation of child resources. An AE shall be able to delete a contentInstance resource explicitly or it may be deleted by the platform based on policies. If the platform has policies for contentInstance retention, these shall be represented by the attributes maxByteSize, maxNrOfInstances and/or maxInstanceAge attributes in the container
resource. If multiple policies are in effect, the strictest policy shall apply.
The contentInstance resource inherits the same access control policies of the parent container
resource, and does not have its own accessControlPolicyIDs attribute.
Universal and common attributes
| Name | Full Name | Type | Multiplicity | Mode |
|---|---|---|---|---|
| ty | resourceType | m2m:resourceType / integer | 1 | RO |
| ri | resourceID | m2m:ID / string | 1 | RO |
| rn | resourceName | string | 1 | WO |
| pi | parentID | m2m:ID / string | 1 | RO |
| lbl | labels | m2m:labels / list of string | 0..1(L) | RW |
| ct | creationTime | m2m:timestamp | 1 | RO |
| lt | lastModifiedTime | m2m:timestamp | 1 | RO |
| announcedAttribute | 0..1(L) | RW | ||
| announceSyncType | 0..1 | RW | ||
| holder | 0..1 | RW |
Mode: RW = Read/Write, RO = Read Only, WO = Write Once
latest and oldest child resources : A container automatically registers two virtual child resource called latest and oldest. These resources allow to access the oldest resp. newest contentInstance resource that the container
contains.
Resource specific attributes
| Name | Full Name | Multiplicity | Mode | Create | Update |
|---|---|---|---|---|---|
| st | stateTag | 1 | RO | NP | - |
| cnf | contentInfo | 0..1 | WO | O | - |
| cs | contentSize | 0..1 | WO | NP | - |
| conr | contentRef | 0..1 | WO | O | - |
| con | content | 0..1 | WO | O | - |
| dcnt | deletionCnt | 0..1 | WO | O | - |
Mode: RW = Read/Write, RO = Read Only, WO = Write Once
Request Optionality: NP = not provisioned, O = optional, M = Mandatory
Attribute: st (stateTag)
The stateTag attribute of the parent resource should be incremented first and copied into this stateTag attribute when a new instance is added to the parent resource.
Attribute: cnf (contentInfo)
This attribute contains information to understand the content s of content attribute. It shall be composed of two mandatory components consisting of Internet Media Type (as defined in the IETF RFC 6838) and an encoding type. In addition, an optional content security component may also be included. The format of this attribute is defined below. This attribute should be used so that AEs can understand the content. If the value of contentInfo is a supported representation of semantic information, the value of content shall be handled as semantic information with respect to the supported semantic oneM2M functionalities.
Attribute: cs (contentSize)
Size in bytes of the content attribute.
Attribute: conr (contentRef)
This attribute contains a list of name-value pairs. Each entry expresses and associative reference to a contentInstance resource. The name of the entry indicates the relationship and the value of the entry the indicates reference (URI) to the resource. See also below.
Attribute: con (content)
Actual content of a contentInstance. This content may be opaque data for understandable with the help of the contentInfo. This may, for example, be an image taken by a security camera, or a temperature measurement taken by a temperature sensor.
Attribute: dcnt (deletionCnt)
A decremental counter used to indicate that the resource shall be deleted by the Hosting CSE when the value becomes 0. If configured, initial value for this attribute shall be greater than 0 and it shall be decremented on every successful retrieval of the resource. This attribute is optional. A successful RETRIEVE operation to the contentInstance resource decrements the counter by 1.
m2m:contentInfo
This data type provides information about the media type in the content attribute.
It is a string consisting of a media type followed by a m2m:encodingType and optional m2m:contentSecurity, each separated by ‘:’ character. If the m2m:contentSecurity value is not present, then the preceding ‘:’ shall also be not present. If the m2m:contentSecurity value is not present then this has the same interpretation as a value of 0 for m2m:contentSecurity.
The media type and m2m:encodingType in m2m:contentInfo describe the content data to which the End-to-End Security of Data (ESData) processing, if any, was applied as indicated by m2m:contentSecurity. The m2m:contentInfo indicates a sequence of processes to be applied to the content after being obtained from the CSE. First, the ESData processing (if any) as indicated by m2m:contentSecurity is applied. The result of this processing then has transfer decoding (if any) applied as indicated by m2m:encodingType. The result of this processing is then processed according to the media type.
Note 1: Though the encoding of JSON data would be possible directly withouth extra encoding (ie. just add the JSON structure to the content attribute) this will not be done for the DMO. This means that even JSON structure will be encoded as a base64 string and stored in the content attribute.
The reason for this is that this might later cause problems when other content serializations are supported by the CSE, e.g. XML or CBOR. There are also some discussions going on to explicitly forbid the encoding other than in a string (and using one of the encoding types).
Note 2: Though ESData (end2end security of data) is currently not directly supported by the DMO CSE implementation it is also not removed or rejected (since it is between AE’s and does not involvde the CSE). The data in the contentInfo and content attributes is stored as it is.
The format of the media-type follows this BNF definition:
media-type = type "/" subtype *( OWS ";" OWS parameter )
type = token
subtype = token
parameter = token "=" ( token / quoted-string )
token = 1*tchar
OWS = *( SP / HTAB ) ; optional whitespace
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ; any VCHAR, except delimiters
quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text
quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
obs-text = %x80-FF
HTAB = %x09 ; horizontal tab
SP = %x20
DQUOTE = %x22
VCHAR = %x21-7E ; visible (printing) characters
DIGIT = %x30-39 ; 0-9
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
m2m:encodingType
Used to describe the encoding type that applies to the content attribute of the contentInstance resource.
- 0 = Plain - no transfer encoding is applied
- 1 = base64 encoding (see IETF RFC 4648) is applied on string data
- 2 = base64 encoding (see IETF RFC 4648) is applied on binary data
JSON representation example
The following example shows a contentInstance resource with an additional set contentRef attribute with two entries:
{
"m2m:cin": {
"con": "hello",
"conr": [
{
"nm": "someRelation",
"uri": "someResourceID"
},
{
"nm": "anotherRelation",
"uri": "anotherResourceID"
}
],
"ri": "cin5560611703140855173",
"rn": "cin_mSObBR4BGn",
"ct": "20210301T154849,455241",
"lt": "20210301T154849,455241",
"et": "20220301T154849,455288",
"pi": "cnt1754851499051457459",
"st": 2,
"ty": 4,
"cs": 5
}
}