Data Sink
IID: [1:{0225}]
This interface is used by a data source to advertise data, events, and topology to a configured data sink. In addition to defining methods, this interface also defines types that are used as the specification for various persistent storage formats. These storage formats are associated with the IID of this interface and identified with '[storage]' in their descriptions. Further, there are unused types defined that correspond to the formatting data blocks before compression. In this case the compressed field is passed on the wire, and the unused type defines the format and contents of the block before compression. These types are identified by putting '[formatting]' in their descriptions.Associated Interfaces
> Type Definitions
Property Aggregation MethodType ID: 11
[formatting] A number that identifies the aggregation method used for this property. The following values are defined; any other values are not defined and must be rejected. RAW(0) - No aggregation is done. AVEDEV(1) - The average of the absolute deviations from the mean. AVERAGE(2) - The average (arithmetic mean). GEOMEAN(3) - The geometric mean. MAX(4) - The maximum value. MEDIAN(5) - The number in the middle of the values. MIN(6) - The minimum value. STDDEV(7) - The standard deviation. VAR(8) - The variance. FIRST(9) - The first value in the sequence. LAST(10) - The last value in the sequence.
MAX:
MIN:
Unit:
Type: uint8
Detail Request StatusType ID: 36
A code indicating the completion status of the detail request. The following values are defined, other values are illegal and should be treated as errors. COMPLETE(0) - success; COMPLETE_NO_DATA(1) - no data was found for the requested time and duration; FAILED(2) - general error; CANCELLED(3) - request cancelled; TIMEOUT(4) -- The request timed out before completing.
MAX:
MIN:
Unit:
Type: uint8
PositionType ID: 17
The logical position of the device relative to the parent. The parent defines the context/meaning of the positions for its children. A parent may have multiple children with the same position, which may indicate a grouping or relationship between those children. The position is meta-data associated with the device itself, and not related directly to data or an event.
MAX:
MIN:
Unit:
Type: uint16
Property Item IDType ID: 10
[formatting] A property item ID.
MAX: 32767
MIN: 0
Unit:
Type: uint16
Event Item IDType ID: 25
[formatting] An event item ID.
MAX: 32767
MIN: 0
Unit:
Type: uint16
Value Set IDType ID: 1
An identifier for the advertised value set, unique to the sink and source involved in the transfer. When used to either request or acknowledge the value set (using the Data Source interface) this identifier uniquely identifies the value set and the sink it is being transferred to.
MAX:
MIN:
Unit:
Type: uint32
Event IDType ID: 20
An identifier for a signaled event, unique to the sink and source involved in the transfer. When used to acknowledge the event (using the Data Source interface) this identifier uniquely identifies the event and the sink the event is being transferred to.
MAX:
MIN:
Unit:
Type: uint32
Topology IDType ID: 22
An identifier for a topology update, unique to the sink and source involved in the transfer. When used to acknowledge the update (using the Data Source interface) this identifier uniquely identifies the update and the sink the event is being transferred to.
MAX:
MIN:
Unit:
Type: uint32
Time QuantumType ID: 5
The number of milliseconds in each quantum of time used in the value transfer.
MAX:
MIN:
Unit:
Type: uint32
Value Set Definition AliasType ID: 7
An alias for the Value Set Definition, assigned by the sink and optionally used by the source.
MAX:
MIN:
Unit:
Type: uint32
Detail Request IDType ID: 35
An identifier provided by the sink to a request for detail data made to the source.
MAX:
MIN:
Unit:
Type: uint32
TimeType ID: 4
The timestamp used throughout to reference start and end times. Time is always in UTC, as required by the type.
Type: datetime
Property Definition ArrayType ID: 14
[formatting] An variable-length array of property definitions.
Min Length: 0
Length: 32767
Type: array ( 13 - Property Definition ) Property DefinitionType ID: 13
[formatting] The definition of a property that will be exchanged.
Type: structure { 9 - iid , 10 - itemID , 11 - aggregation , 10 - type }
Uncompressed Value Set DefinitionType ID: 16
[formatting] A structure containing the uncompressed version of the entire value set definition for transfer. Note that this type is never used, but it defines the uncompressed format of a block that is passed on the wire.
Type: structure { 14 - properties , 15 - types }
Range MetadataType ID: 23
This structure defines metadata for data over a range of time.
Type: structure { 0 - deviceID , 32 - parentID , 30 - position , 4 - blockStartTime , 5 - blockQuantum , 4 - blockEndTime }
Discrete MetadataType ID: 24
This structure defines metadata for data at a single point in time.
Type: structure { 0 - deviceID , 32 - parentID , 30 - position , 4 - time }
Event DefinitionType ID: 27
[formatting] The definition of an event that will be exchanged.
Type: structure { 9 - iid , 25 - itemID , 25 - type , 15 - types }
Uncompressed EventType ID: 29
[formatting] A structure containing the entire event for transfer. Note that this type is never used, but it defines the uncompressed format of a block that is passed on the wire.
Type: structure { 27 - event , 28 - values }
Value Set Definition StorageType ID: 19
[storage] This structure defines the peristence storage definition for the value set definition. Note that the format defined in this interface will always use an IID of [1:{0225}]. When reading the stored format the reader must check the version field and read the contents according to the correct IID.
Type: structure { 18 - version , 3 - valueSetDefinition }
Value Set StorageType ID: 8
[storage] This type describes the peristent storage format for data sets. All future versions of this interface must maintain the first field (version). Note that the format defined in this interface will always use an IID of [1:{0225}]. When reading the stored format the reader must check the version field and read the contents according to the correct IID.
Type: structure { 18 - version , 23 - metaData , 34 - dataDefinition , 31 - sourceVersion , 33 - sourceData }
Event StorageType ID: 2
[storage] This type describes the peristent storage format for an event. All future versions of this interface must maintain the first field (version). All versions of the storage will start with the same version type, and a generic reader can read the version and identify the format that follows. This definition uses the value [1:{0225}].
Type: structure { 18 - version , 24 - metaData , 21 - event }
Topology StorageType ID: 6
[storage] This type describes the peristent storage format for a topology update. All future versions of this interface must maintain the first field (version). All versions of the storage will start with the same version type, and a generic reader can read the version and identify the format that follows. This definition uses the value [1:{0225}].
Type: structure { 18 - version , 24 - metaData }
Value Set DefinitionType ID: 3
A compressed block that defines the properties that are being transferred in the advertisement. The compression algorithm is DEFLATE (RFC 1951). The uncompressed block is an EMIT-marshalled instance of the 'Uncompressed Value Set Definition' type defined in this interface.
Min Length: 0
Length: 65535
Type: blob
EventType ID: 21
A compressed block that describes both the event definition that is being transferred in the signal and the event parameters. The compression algorithm is DEFLATE (RFC 1951). The uncompressed block is an EMIT-marshalled instance of the 'Uncompressed Event' type defined in this interface.
Min Length: 0
Length: 65535
Type: blob
Reference Interface DefinitionType ID: 15
[formatting] A blob containing an interface definition. The interface definition is defined in the OAP protocol specification, PDU OAP.13.2, as everything that follows the opcode byte of the response to the Define PDU.
Min Length: 5
Length: 65535
Type: blob
Event ValuesType ID: 28
[formatting] A list of marshalled DOFValues matching the parameters of the event being signaled.
Min Length: 0
Length: 65535
Type: blob
Source Value Set BlockType ID: 33
[storage] This value set is defined by the source IID and corresponds to the information transferred to the sink.
Min Length: 0
Length: 1048576
Type: blob
Optional IDType ID: 32
An optional ID that is used in cases (for example, parent) where the ID may not exist. NULL indicates that there is no ID.
Type: nullable ( ID ) Optional PositionType ID: 30
An optional position is used in cases where the position may not exist. NULL indicates that there is no position.
Type: nullable ( Position ) Optional Value Set DefinitionType ID: 34
[storage] Either a value set definition or a NULL if the definition is not present.
Type: nullable ( Value Set Definition ) IDType ID: 0
An identifier for an actor in the data exchange (device, source, sink, parent).
Type: oid
Sink VersionType ID: 18
[storage] An IID used to identify the version of stored information related to the sink API. Future versions of this interface will need to differentiate between versions. All stored data defined by this interface will begin with this type, allowing it to be read to identify the data format that follows.
Type: iid
Source VersionType ID: 31
[storage] An IID used to identify the version of stored information related to the source IID associated with this sink IID. Future versions of this interface will need to differentiate between versions. All stored data defined by the source interface will begin with this type, allowing it to be read to identify the data format that follows.
Type: iid
Element IIDType ID: 9
[formatting] The IID of a property or event (collectively, element) that can be passed.
Type: iid
MAX:
MIN:
Unit:
Type: uint8
Detail Request StatusType ID: 36
MAX:
MIN:
Unit:
Type: uint8
PositionType ID: 17
MAX:
MIN:
Unit:
Type: uint16
Property Item IDType ID: 10
MAX: 32767
MIN: 0
Unit:
Type: uint16
Event Item IDType ID: 25
MAX: 32767
MIN: 0
Unit:
Type: uint16
Value Set IDType ID: 1
MAX:
MIN:
Unit:
Type: uint32
Event IDType ID: 20
MAX:
MIN:
Unit:
Type: uint32
Topology IDType ID: 22
MAX:
MIN:
Unit:
Type: uint32
Time QuantumType ID: 5
MAX:
MIN:
Unit:
Type: uint32
Value Set Definition AliasType ID: 7
MAX:
MIN:
Unit:
Type: uint32
Detail Request IDType ID: 35
MAX:
MIN:
Unit:
Type: uint32
TimeType ID: 4
Type: datetime
Property Definition ArrayType ID: 14
Min Length: 0
Length: 32767
Type: array ( 13 - Property Definition ) Property DefinitionType ID: 13
Type: structure { 9 - iid , 10 - itemID , 11 - aggregation , 10 - type }
Uncompressed Value Set DefinitionType ID: 16
Type: structure { 14 - properties , 15 - types }
Range MetadataType ID: 23
Type: structure { 0 - deviceID , 32 - parentID , 30 - position , 4 - blockStartTime , 5 - blockQuantum , 4 - blockEndTime }
Discrete MetadataType ID: 24
Type: structure { 0 - deviceID , 32 - parentID , 30 - position , 4 - time }
Event DefinitionType ID: 27
Type: structure { 9 - iid , 25 - itemID , 25 - type , 15 - types }
Uncompressed EventType ID: 29
Type: structure { 27 - event , 28 - values }
Value Set Definition StorageType ID: 19
Type: structure { 18 - version , 3 - valueSetDefinition }
Value Set StorageType ID: 8
Type: structure { 18 - version , 23 - metaData , 34 - dataDefinition , 31 - sourceVersion , 33 - sourceData }
Event StorageType ID: 2
Type: structure { 18 - version , 24 - metaData , 21 - event }
Topology StorageType ID: 6
Type: structure { 18 - version , 24 - metaData }
Value Set DefinitionType ID: 3
Min Length: 0
Length: 65535
Type: blob
EventType ID: 21
Min Length: 0
Length: 65535
Type: blob
Reference Interface DefinitionType ID: 15
Min Length: 5
Length: 65535
Type: blob
Event ValuesType ID: 28
Min Length: 0
Length: 65535
Type: blob
Source Value Set BlockType ID: 33
Min Length: 0
Length: 1048576
Type: blob
Optional IDType ID: 32
Type: nullable ( ID ) Optional PositionType ID: 30
Type: nullable ( Position ) Optional Value Set DefinitionType ID: 34
Type: nullable ( Value Set Definition ) IDType ID: 0
Type: oid
Sink VersionType ID: 18
Type: iid
Source VersionType ID: 31
Type: iid
Element IIDType ID: 9
Type: iid
> Methods
Advertise DataItem ID: 1
Advertise a value set that the sink may get and must acknowledge. This method may return 'Value Set Definition Not Understood' if the particular data definition cannot be understood, which would prevent any data transfer for that definition.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the value set.
1 - valueSetID - An identifier associated with the advertised value set and the sink, that is used to uniquely identify the value set/sink combination.
23 - metaData - The meta-data associated with the value set.
3 - valueSetDefinition - The full value set definition associated with the advertised information.
Outputs:
7 - valueSetDefinitionAlias - The alias that the sink wants the source to use to refer to this particular value set definition.
Advertise Data With AliasItem ID: 2
Advertise a value set using an alias that the sink may get and must acknowledge. This method may cause a Data Definition Alias Not Understood exception.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the data.
1 - valueSetID - An identifier associated with the advertised value set and sink, that is used to uniquely identify the value set/sink combination.
23 - metaData - The meta-data associated with the value set.
7 - valueSetDefinitionAlias - An alias that represents the value set definition that the sink has associated for the source.
Signal EventItem ID: 4
Signal and event that the sink must acknowledge. This method does not cause any provider exceptions.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the event.
20 - eventID - An identifier associated with the signaled event and the sink, that is used to uniquely identify the event/sink combination.
24 - metaData - The meta-data associated with the event.
21 - eventDefinition - The event being signaled, including both definition and values.
Update TopologyItem ID: 5
Update the topology of a node. This method does not cause any provider exceptions.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the update.
22 - topologyID - An identifier associated with the update and the sink, that is used to uniquely identify the update/sink combination.
24 - metaData - The meta-data associated with the update.
Detail Request CompleteItem ID: 6
Notify the sink that a request for detail data has been completed.
Inputs:
35 - id - The ID of the request for detail data.
36 - status - The status of the request for detail data.
Advertise a value set that the sink may get and must acknowledge. This method may return 'Value Set Definition Not Understood' if the particular data definition cannot be understood, which would prevent any data transfer for that definition.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the value set.
1 - valueSetID - An identifier associated with the advertised value set and the sink, that is used to uniquely identify the value set/sink combination.
23 - metaData - The meta-data associated with the value set.
3 - valueSetDefinition - The full value set definition associated with the advertised information.
Outputs:
7 - valueSetDefinitionAlias - The alias that the sink wants the source to use to refer to this particular value set definition.
Advertise Data With AliasItem ID: 2
Advertise a value set using an alias that the sink may get and must acknowledge. This method may cause a Data Definition Alias Not Understood exception.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the data.
1 - valueSetID - An identifier associated with the advertised value set and sink, that is used to uniquely identify the value set/sink combination.
23 - metaData - The meta-data associated with the value set.
7 - valueSetDefinitionAlias - An alias that represents the value set definition that the sink has associated for the source.
Signal EventItem ID: 4
Signal and event that the sink must acknowledge. This method does not cause any provider exceptions.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the event.
20 - eventID - An identifier associated with the signaled event and the sink, that is used to uniquely identify the event/sink combination.
24 - metaData - The meta-data associated with the event.
21 - eventDefinition - The event being signaled, including both definition and values.
Update TopologyItem ID: 5
Update the topology of a node. This method does not cause any provider exceptions.
Inputs:
0 - sourceID - The ID of the node responsible for transferring the update.
22 - topologyID - An identifier associated with the update and the sink, that is used to uniquely identify the update/sink combination.
24 - metaData - The meta-data associated with the update.
Detail Request CompleteItem ID: 6
Notify the sink that a request for detail data has been completed.
Inputs:
35 - id - The ID of the request for detail data.
36 - status - The status of the request for detail data.
> Exceptions
Value Set Definition Alias Not UnderstoodItem ID: 3
Returned by the sink if the value set definition alias received is not understood. This indicates that the advertise should be resent including the value set definition and a new alias obtained. Value Set Definition Not UnderstoodItem ID: 7
Returned by the sink if the value set definition received is not understood. This indicates some formatting issue on the source, or a programming error on the sink. Resubmitting the same definition will likely resultin the same exception, so this can be considered fatal for the definition in question and would prevent any data transfer.
Returned by the sink if the value set definition alias received is not understood. This indicates that the advertise should be resent including the value set definition and a new alias obtained. Value Set Definition Not UnderstoodItem ID: 7
Returned by the sink if the value set definition received is not understood. This indicates some formatting issue on the source, or a programming error on the sink. Resubmitting the same definition will likely resultin the same exception, so this can be considered fatal for the definition in question and would prevent any data transfer.