Albert 的筆記本: ONVIF event handling

ONVIF Event 主要基於Web Service的兩份標準 [WS-BaseNotification] 和 [WS-Topics] 而制定，分別提供了 PUSH 與 PULL 的方式，讓使用者可取得系統資訊。參考 ONVIF-Core-Specification-v211.pdf chapter9 的內容，整理如後：

一、基本定義

** Event 定義

Event是設備上主動發生或被動產生的事件，IPCam 設備會偵測系統上發生了哪些事件(Event)，並讓用戶能夠訂閱此資訊。

An event is an action or occurrence detected by a device that a client can subscribe to.
** Property 定義

Property是許多值(name value pairs)的結合，並且以 Event 的方式封裝。

A Property is a collection of name and value pairs representing a unique and addressable set of data. They are uniquely identified by the combination of their Topic, Source and Key values and are packaged like ordinary events. A Property also contains an additional flag, stating whether it is newly created, has changed or has been deleted.

二、透過 PUSH 的方式接收Event

此部分需參考 wsn-ws_base_notification-1.3-spec-os.pdf ，實作 Basic Notification Interface。Basic Notification Interface 架構中存在三種元件：

Client: implements the NotificationConsumer interface.

Event Service: implements the NotificationProducer interface.

Subscription Manager: implements the BaseSubscriptionManager interface.

IPCam 本身需要同時實作 Event Service 與 Subscription Manager，至於這兩個軟體元件如何溝通方式，則沒有明確定義。參考下圖

當Client subscribe某個event後，IPCam才會啟動 Subscription Manager，並且在 Client 與 IPCam 之間建立另一條連線(For event push)。當對應的event發生時，Event Service 便會主動將 event 送給 Client。

三、透過 PULL 的方式接收Event

IPCam 需實作 Real-time Pull-Point Notification Interface (firewall friendly notification interface)，此介面會進行下列溝通：

Client 發出 CreatePullPointSubscriptionRequest，　此訊息內可以設定 termination time，並且設定 Filter，若沒有設定Filter，則Device將會回覆Client所有events.

Device 回復 CreatePullPointSubscriptionResponse，裏頭包含 WS-EndpointReference，用來指定對應的 SubscriptionManager

Client 可以與 WS-Endpoint 進行 PullMessages 的溝通，包含三種運算。PullMessages, Renew and Unsubscribe，參考下圖：

Client 送出 PullMessages request，若 Device端已經存放 event，則會立刻回 PullMessages Response，並且盡可能回復最多的訊息，訊息總大小則限制在 MessageLimit 之內。若 Device端沒有屬於此 Client 的event，則等待至 timeout

如果 CreatePullPointSubscriptionRequest 沒有設定 timeout，或是只設定 relative timeout，那麼這個 PullMessagesRequest 會被當成是針對此 PullPoint 的 keep-alive 訊息，用來避免此 PullPoint 被 Device 刪除。Device 會根據本身的預設值，重新設定此 Subscription timeout 時間。當 Client 使用此方法來 keep-alive，那麼就不需要再使用 RenewRequest了。

四、Notification Streaming Interface

此介面藉由 ONVIF Media service 的 Metadata Configuration 來完成 Notification Streaming Interface的功能。用戶透過 profile 內 metadata configuration 中的 subscriptions 資料建立 RTP stream。

When a metadata configuration containing subscriptions has been assigned to a profile,
a client uses that profile to get an RTP stream that includes the configured notifications
as metadata.

五、Notification Structure

[WS-BaseNotification] 定義了一個元素　wsnt:NotificationMessage ，用來封裝 Message Payload, the Topic and the ProducerReference。
其 schema 如下
<xs:complexType name="NotificationMessageHolderType" >
<xs:sequence>
<xs:element ref="wsnt:SubscriptionReference" minOccurs="0" />
<xs:element ref="wsnt:Topic" minOccurs="0" />
<xs:element ref="wsnt:ProducerReference" minOccurs="0" />
<xs:element name="Message">
<xs:complexType>
<xs:sequence>
<xs:any namespace="##any" processContents="lax" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:element name="NotificationMessage"
type="wsnt:NotificationMessageHolderType"/>

對應的 XML 如下
<wsnt:NotificationMessage>
<wsnt:SubscriptionReference>
wsa:EndpointReferenceType
</wsnt:SubscriptionReference>
<wsnt:Topic Dialect="xs:anyURI">
…
</wsnt:Topic>
<wsnt:ProducerReference>
wsa:EndpointReferenceType
</wsnt:ProducerReference>
<wsnt:Message>
…
</wsnt:Message>
</wsnt:NotificationMessage>

其中 wsnt:Message 便包含了 notification payload，主要包含了三種item，Source, Key, and Data，其 Schema 定義如下：
<xs:element name="Message" type="Message">
<xs:element name="Message">
<xs:complexType>
<xs:sequence>
<xs:element name="Source" type="tt:ItemList" minOccurs="0"/>
<xs:element name="Key" type="tt:ItemList" minOccurs="0"/>
<xs:element name="Data" type="tt:ItemList" minOccurs="0"/>
...
</xs:sequence>
<xs:attribute name="UtcTime" type="xs:time" use="required"/>
<xs:attribute name="PropertyOperation" type="tt:PropertyOperationType"/>
</xs:complexType>
</xs:element>
<xs:complexType name="ItemList">
<xs:sequence>
<xs:element name="SimpleItem" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="Name" type="xs:string" use="required"/>
<xs:attribute name="Value" type="xs:anySimpleType" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="ElementItem" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:any namespace="##any"/>
</xs:sequence>
<xs:attribute name="Name" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="PropertyOperationType">
<xs:restriction base="xs:string">
<xs:enumeration value="Initialized"/>
<xs:enumeration value="Deleted"/>
<xs:enumeration value="Changed"/>
</xs:restriction>
</xs:simpleType>

六、定期更新資訊的方法

若想要一次取得所有欲查詢的屬性，Client可以先發出SetSynchronizationPoint ， Device，接著 Device 可以使用 SubscriptionResponse 或CreatePullPointSubscriptionResponse 回復資訊。

When a client wants to synchronize its properties with the properties of the device, it can request a synchronization point which repeats the current status of all properties to which a client has subscribed.The PropertyOperation of all produced notifications is set to “Initialized” (see Section 9.5). The Synchronization Point is requested directly from the SubscriptionManager which was returned in either the SubscriptionResponse or in the CreatePullPointSubscriptionResponse.

七、ONVIF 測試工具封包

Event-2-1-15 Basic Notification Interface -- Notify