4 Messaging

This section documents the messaging and message handling protocols defined in SIF. A messaging protocol consists of sending a SIF_Message to initiate an operation, receiving back a SIF_Ack; a message handling protocol consists of processing an incoming SIF_Message and responding with a SIF_Ack and possibly sending follow-up SIF_Messages. This section is independent of transport layer details, aside from encryption and authentication level impacts associated with individual messages. Unless otherwise noted, all protocols assume successful communication over the appropriate transport layer; agent and ZIS implementations should also be prepared to handle transport layer errors and exceptions, directly or wrapped in a SIF_Ack/SIF_Error by underlying code.

4.1 Agent Protocols

4.1.1 Agent Messaging Protocols

This section documents how Agents should send individual messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take. These correspond to each of the operations an Agent can initiate.

4.1.1.1 SIF_Register

An Agent must register with the ZIS to participate in a Zone. To do so, it sends a SIF_Register message. An Agent may at any time re-register by sending another SIF_Register message. The ZIS updates the Agent's registered settings accordingly.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Register message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place your Agent's name, supported versions and maximum buffer size for receiving messages into SIF_Name, SIF_Version and SIF_MaxBufferSize, respectively. Specify whether your Agent is Push- or Pull-mode in SIF_Mode. If SIF_Mode is Push, specify the protocol information for the ZIS to use when delivering messages to your agent in SIF_Protocol; optional compression settings may be included in the Accept-Encoding SIF_Protocol/SIF_Property. If desired, supply optional information regarding your Agent and/or application in SIF_NodeVendor, SIF_NodeVersion, SIF_Application and SIF_Icon. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is now registered in the Zone. The Access Control settings for your agent (SIF_AgentACL are in SIF_Status/SIF_Data). Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Note particularly category 5. If an Accept-Encoding  SIF_Protocol/SIF_Property was specified, the ZIS may return error code 10 (ZIS does not support the requested Accept-Encoding value). Your agent SHOULD re-attempt registration without, or with another, Accept-Encoding value. Messaging protocol complete (failure).
Table 4.1.1.1-1: SIF_Register Protocol

4.1.1.2 SIF_Unregister

An Agent removes itself from a Zone by sending a SIF_Unregister message to the ZIS. Successful completion of this operation removes all settings associated with the Agent, including the objects it is currently providing and subscribed to in the zone; the Agent's message queue is also deleted. Note that a successful SIF_Unregister message may, depending on the ZIS implementation, remove access control settings that have been manually configured by a Zone administrator and that may need to be re-configured for a subsequent successful SIF_Register.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Unregister message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is now removed from the Zone. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.2-1: SIF_Unregister Protocol

4.1.1.3 SIF_Provide

An Agent registers with the ZIS to be the default Responder, or Provider, for one or more SIF objects in one or more contexts by sending a SIF_Provide message to the ZIS. The Agent must have access control rights at the ZIS to successfully register as a Provider for an object.

Note that upon successful completion of SIF_Provide that your Agent is still the Provider of any objects for which it was previously registered as the Provider. To unregister as the Provider of given objects, use SIF_Unprovide. To replace all objects your Agent provides in one operation, use SIF_Provision.

As of version 2.0 of this specification, SIF_Provision is the preferred method for registering an Agent as a Provider, and provisioning an Agent in general. Support for SIF_Provide may be removed in a future major release of this specification.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Provide message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. For each object your Agent would like to provide, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent's support for SIF_ExtendedQuery can be specified in SIF_ExtendedQuerySupport for each object. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is now the Provider of each of the objects specified in the SIF_Provide message, in the applicable context(s). Any request sent by an Agent for one of these objects without explicitly specifying a particular Responder in SIF_Header/SIF_DestinationId will be placed in your Agent's message queue. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Note particularly category 4, code 3 (no permission to provide) and category 6, code 4 (object already has a Provider). Messaging protocol complete (failure).
Table 4.1.1.3-1: SIF_Provide Protocol

4.1.1.4 SIF_Unprovide

Your Agent unregisters with the ZIS as the default Responder, or Provider, for one or more SIF objects in one or more contexts by sending a SIF_Unprovide message to the ZIS. Note that any SIF_Requests for these objects already pending in your Agent's queue will still be delivered.

As of version 2.0 of this specification, SIF_Provision is the preferred method for unregistering an Agent as a Provider, and provisioning an Agent in general. Support for SIF_Unprovide may be removed in a future major release of this specification.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Unprovide message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. For each object your Agent would like to provide, include a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is no longer the Provider of each of the objects specified in the SIF_Unprovide message, in the applicable context(s). SIF_Requests will no longer be routed to your Agent by default, but this does not prevent other Agents from sending requests directly to your Agent (if permitted by access control rights). Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.4-1: SIF_Unprovide Protocol

4.1.1.5 SIF_Subscribe

An Agent registers with the ZIS to receive SIF_Events for one or more SIF objects in one or more contexts by sending a SIF_Subscribe message to the ZIS. The Agent must have access control rights at the ZIS to successfully subscribe to events for an object.

Note that upon successful completion of SIF_Subscribe that your Agent is still subscribed to objects to which it had previously subscribed. To unregister as a Subscriber of given objects, use SIF_Unsubscribe. To replace all objects to which your Agent subscribes in one operation, use SIF_Provision.

As of version 2.0 of this specification, SIF_Provision is the preferred method for registering an Agent as a Subscriber, and provisioning an Agent in general. Support for SIF_Subscribe may be removed in a future major release of this specification.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Subscribe message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. For each object your Agent would like to subscribe to, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is now subscribed to each of the objects specified in the SIF_Subscribe message, in the specified context(s) if included. Any SIF_Events for these objects will be placed in your Agent's queue. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Note particularly category 4, code 4 (no permission to subscribe). Messaging protocol complete (failure).
Table 4.1.1.5-1: SIF_Subscribe Protocol

4.1.1.6 SIF_Unsubscribe

To stop receiving SIF_Events for one or more objects in one or more contexts, an Agent sends a SIF_Unsubscribe message to the ZIS. Note that if there are events already pending in your Agent's queue for these objects, they will still be delivered after a successful SIF_Unsubscribe.

As of version 2.0 of this specification, SIF_Provision is the preferred method for unregistering an Agent as a Subscriber, and provisioning an Agent in general. Support for SIF_Unsubscribe may be removed in a future major release of this specification.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Unsubscribe message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. For each object your Agent would like to cease receiving events, include a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is now unsubscribed from each of the objects specified in the SIF_Unsubscribe message, in the applicable context(s). SIF_Events for these objects will cease to be placed in your Agent's queue. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.6-1: SIF_Unsubscribe Protocol

4.1.1.7 SIF_Provision

The SIF_Provision message provides an Agent the ability to register the objects it provides and to which it subscribes in a single operation, replacing whatever settings the ZIS has on record for the Agent. In effect it is an alternative to SIF_Provide, SIF_Unprovide, SIF_Subscribe and SIF_Unsubscribe, though an Agent may choose to use this message or those, or a combination of these messages.

This message also allows the Agent to fully describe the operations it will perform in a Zone beyond those that can be communicated with SIF_Provide and SIF_Subscribe, including the types of events it will publish, the requests to which it will respond with or without being the Provider for requested objects, and the objects for which it sends requests.

The Agent must have the appropriate access control settings to successfully register any of the corresponding information included in SIF_Provision. Note that the list of access control settings can be determined by examining the SIF_AgentACL object returned in the SIF_Register or SIF_GetAgentACL message protocols.

Note that SIF_Provision will also fail if the Agent is attempting to provide an object that is already provided by another Agent in the applicable Zone Context. The list of Providers in a Zone can be found in SIF_ZoneStatus.

As of version 2.0 of this specification, SIF_Provision is the preferred method for provisioning an Agent. Support for SIF_Subscribe, SIF_Unsubscribe, SIF_Provide and SIF_Unprovide may be removed in a future major release of this specification.

Step Process Flow Control
1

Prepare a SIF_Message/SIF_Provision message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply.

Include SIF_ProvideObjects and for each object your Agent would like to provide, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent can also state its support for SIF_ExtendedQuery in SIF_ExtendedQuerySupport, which defaults to false.

Include SIF_SubscribeObjects and for each object to which your Agent would like to subscribe, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted).

Include SIF_PublishAddObjects, SIF_PublishChangeObjects and SIF_PublishDeleteObjects elements and include a SIF_Object element with an ObjectName in the respective sections for each event type your agent publishes with regard to that object. Optionally specify for each object one or more SIF_Context names (which default to SIF_Default if omitted).

Include SIF_RequestObjects and for each object your Agent requests, place a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent can also state its support for SIF_ExtendedQuery in SIF_ExtendedQuerySupport, which defaults to false.

Include SIF_RespondObjects and for each object for which your Agent processes requests (including those listed in SIF_ProvideObjects), include a SIF_Object element with an ObjectName and optionally one or more SIF_Context names (which default to SIF_Default if omitted). Your Agent can also state its support for SIF_ExtendedQuery in SIF_ExtendedQuerySupport, which defaults to false.

Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent is now registered with the corresponding settings in the Zone. Any previously recorded settings with regard to the operations your Agent performs have been replaced. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.7-1: SIF_Provision Protocol

4.1.1.8 SIF_Event

When an application adds, changes or deletes data represented in one or more Zone Contexts, its Agent SHOULD publish the corresponding Add, Change or Delete SIF_Event to the Zone. Upon successful delivery of a SIF_Event to the ZIS, the ZIS places the event in the queue for any Agents subscribed to events for the object, including your Agent if it is a subscriber.

Step Process Flow Control
1

Prepare a SIF_Message/SIF_Event message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp. If your Agent would like to indicate minimum encryption and/or authentication requirements for Agents receiving this SIF_Event; supply SIF_Security with the appropriate settings; use an equally secure channel when communicating with the ZIS, if desired. If this event specifically applies to one or more contexts, place them in SIF_Contexts; if omitted, the context is SIF_Default.

Specify the name of the object that is being added, changed or deleted in SIF_EventObject/@ObjectName. Place the type of event in SIF_EventObject/@Action and place the object in SIF_EventObject. For an Add event, this MUST be the complete object with all mandatory elements present. If the agent wishes to indicate that a particular optional element is supported but has no value, the element MAY be included as empty, with xsi:nil set to true if necessary.

For a Change event, all unchanged elements, whether mandatory or optional SHOULD be omitted from the object. Optional elements that have been deleted MAY be included as empty, with xsi:nil set to true if necessary. For each list of repeatable elements in the object that has changed, include the whole list if the list type indicated is List. If the list type is ActionList, the agent MAY include only those elements in the list that have been added, changed or deleted. If an element has been deleted from an ActionList, the element MUST be included with at least its key attribute(s) and/or element(s) specified, and include a SIF_Action attribute value of Delete on the deleted child element in the list. Omitting an element in an ActionList indicates that it has been unchanged in the event. Refer to the Data Model section of the specification, Lists/Repeatable Elements, for more details on ActionLists and Lists.

For a Delete event, only elements/attributes that identify the object sufficiently for deletion SHOULD be included. This set of identifying elements/attributes are typically communicated by the mandatory root attributes of an object, which MUST be included.

Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 The event has been successfully received by the ZIS. It will be placed in the queue of any Agents registered as subscribers to events for the given object. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.8-1: SIF_Event Protocol

4.1.1.9 SIF_Request

An Agent can request data from another Agent at any time by sending a SIF_Request message. Agents use one of two query mechanisms in requests. SIF's default query mechanism, SIF_Query, is used to request objects of a given type, matching optional query conditions, optionally returning a subset of object elements. SIF_ExtendedQuery is used to select elements from one or more objects, joined together, if necessary, on RefId-based conditions. Before delivering a request with a SIF_ExtendedQuery to a Responder, the ZIS checks that the Responder supports SIF_ExtendedQuery for all referenced objects.

Step Process Flow Control
1

Prepare a SIF_Message/SIF_Request message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp. If your Agent would like to indicate minimum encryption and/or authentication requirements for Agents receiving this SIF_Request, supply SIF_Security with the appropriate settings; use an equally secure channel when communicating with the ZIS, if desired. If this request is associated with a context, specify a single SIF_Context in SIF_Contexts; if omitted, the context is SIF_Default. If your Agent would like to explicitly route this request to a given Agent, specify the Agent's Id in SIF_DestinationId. Specify the SIF versions the responder may choose from when returning data in SIF_Version. Each version specified MUST be registered at the ZIS as supported by your Agent. Specify the maximum buffer size the Responder must respect when sending SIF_Response packets; this MUST be less than or equal to the SIF_MaxBufferSize with which your Agent registered with the ZIS.

If using SIF_ExtendedQuery, go to step 3; otherwise go to step 2.

2 In SIF_Query, specify the object name being requested in SIF_QueryObject/@ObjectName. Optionally specify the subset of elements/attributes to be returned from each object in SIF_QueryObject/SIF_Element; note that parent elements of specified elements/attributes are returned as well. If your Agent would like to specify query matching conditions, include SIF_ConditionGroup. Alternately an example of an object allowed for use in query-by-example can be placed in SIF_Example. Send SIF_Message to ZIS over appropriate transport. Go to step 4.
3 Include a SIF_ExtendedQuery. If your Agent did not specify SIF_DestinationId, the SIF_Request will be routed to the Provider for SIF_From/@ObjectName. If your Agent would like to override this routing mechanism, include SIF_DestinationProvider set to the object name for which the ZIS will determine the Provider and route the request accordingly. Send SIF_Message to ZIS over appropriate transport.
4 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 8.
5 Is SIF_Status/SIF_Code 0? If no, go to Step 7.
6 The request has been successfully received by the ZIS. It will be placed in the queue of the appropriate Responder as specified in SIF_Header/SIF_DestinationId or determined by SIF_ExtendedQuery/SIF_From/@ObjectName or SIF_ExtendedQuery/SIF_DestinationProvider. Messaging protocol complete (success).
7 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
8 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.9-1: SIF_Request Protocol

4.1.1.10 SIF_Ping

An agent can "ping" the ZIS or check that it's online and/or "awake" by sending a SIF_Ping message to the ZIS. If the agent receives a successful acknowledgement, the ZIS is awake; the ZIS may also reply that it is asleep. As a ZIS may be offline completely, Agents should be prepared to handle transport errors directly or wrapped in a SIF_Ack/SIF_Error by underlying code.

Step Process Flow Control
1 Prepare a SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_Ping element in SIF_SystemControlData. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 8.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 The ZIS is awake. Messaging protocol complete (success).
5 Is SIF_Status/SIF_Code 8 (ZIS is asleep)? If no, go to Step 7.
6 The ZIS is asleep. Messaging protocol complete (success).
7 Messaging protocol has failed due to a SIF_Status/SIF_Code of 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
8 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.10-1: SIF_Ping Protocol

4.1.1.11 SIF_Sleep

A Push-mode Agent can send a SIF_Sleep message to the ZIS to change its state to "asleep," indicating that the ZIS should not send the Agent messages until it "wakes up" by sending a SIF_Wakeup message or re-registering with SIF_Register. A Pull-mode Agent can also changes it state to "sleeping," but this has no effect other than indicating to other Agents via SIF_ZoneStatus that it is "sleeping" and not processing messages in its queue. Sending a SIF_Wakeup or SIF_GetMessage will indicate that the Agent is "awake," as will re-registering with SIF_Register.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_Sleep element in SIF_SystemControlData. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent's state has been set to "asleep" in the ZIS. This is reflected to other Agents in SIF_ZoneStatus and if your Agent is a Push-mode Agent, the ZIS will stop delivering messages to your Agent. To "wake up," send a SIF_Wakeup message, or re-register with SIF_Register. Pull-mode Agents may also send SIF_GetMessage. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.11-1: SIF_Sleep Protocol

4.1.1.12 SIF_Wakeup

An Agent can send a SIF_Wakeup message to the ZIS to change its state to "awake," whether sleeping or not; this state is available to other Agents via SIF_ZoneStatus. Upon success, the ZIS may begin delivering messages to a Push-mode Agent again, if previously sleeping.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_Wakeup element in SIF_SystemControlData. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 Your Agent's state has been set to "awake" in the ZIS. This is reflected to other Agents in SIF_ZoneStatus and if your Agent is a Push-mode Agent and it was previously asleep, the ZIS will resume delivering messages to your Agent. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.12-1: SIF_Wakeup Protocol

4.1.1.13 SIF_GetZoneStatus

To retrieve the current status of the Zone (SIF_ZoneStatus), send a SIF_GetZoneStatus message to the ZIS.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_GetZoneStatus element in SIF_SystemControlData. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 SIF_Status/SIF_Data contains the current status of the Zone in SIF_ZoneStatus. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.13-1: SIF_GetZoneStatus Protocol

4.1.1.14 SIF_GetAgentACL

To retrieve your Agent's current access control list settings from the ZIS (SIF_AgentACL), send a SIF_GetAgentACL message to the ZIS.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_GetAgentACL element in SIF_SystemControlData. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 SIF_Status/SIF_Data contains your Agent's current access control list settings in the Zone in SIF_AgentACL. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.14-1: SIF_GetAgentACL Protocol

4.1.1.15 SIF_CancelRequests

Agents can request that a ZIS cancel SIF_Requests, pending or in process, by sending a list of SIF_RequestMsgIds in a SIF_CancelRequests message. If an Agent abandons or restarts a data collection using SIF_Requests, whether or not the response stream has started, it is RECOMMENDED that the Agent send one or more SIF_CancelRequests messages to the ZIS. Such data collections can place a heavy load on responding Agents, where often all data of a specific object type is requested, and cancelling requests may spare Zone resources. Cancelling of responses can also reduce the number of response packets the receiving/cancelling agent needs to process and discard.

If the cancelling Agent wishes to receive a "final" SIF_Response from the ZIS for each cancelled message, it can specify Standard in SIF_CancelRequests/SIF_NotificationType. If the cancelling Agent does not desire or require "final" SIF_Responses, the Agent can specify None in SIF_NotificationType.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Add a SIF_CancelRequests element in SIF_SystemControlData.  
2 Specify Standard in NotificationType if your Agent desires or requires a "final" SIF_Response be returned by the ZIS for each cancelled message (SIF_Response/SIF_MorePackets = No). Otherwise specify None.  
3 Add a SIF_RequestMsgIds element and add a child SIF_RequestMsgId element for each SIF_Request that the Agent wishes to cancel. Send SIF_Message to ZIS over appropriate transport.
4 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 8.
5 Is SIF_Status/SIF_Code 0? If no, go to Step 7.
6 The ZIS has accepted the SIF_CancelRequests message. Your Agent will receive or not receive "final" SIF_Responses per the specified NotificationType. Messaging protocol complete (success).
7 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
8 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.15-1: SIF_CancelRequests Protocol

4.1.1.16 SIF_GetMessage (Pull-Mode only)

Pull-mode Agents retrieve the next message in their queue by sending a SIF_GetMessage message to the ZIS. Note that as individual messages may have specific minimum encryption/authentication levels attached to them by senders, a Pull-Mode Agent should always use the highest encryption/authentication levels it supports when contacting the ZIS to avoid individual messages being discarded when contacting the ZIS using lower encryption/authentication levels than might be required for receipt of a given message.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_GetMessage element in SIF_SystemControlData. Send SIF_Message to ZIS over appropriate transport. Always use the highest encryption/authentication levels that your Agent supports to maximize the number of messages that can be returned to your Agent.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 7.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 SIF_Status/SIF_Data contains the next SIF_Message in your agent's queue. Messaging protocol complete (success). Process the returned SIF_Message according to Agent Message Handling Protocols below.
5 Is SIF_Status/SIF_Code 9? If yes, there are no messages available for your Agent. Message processing complete (success).
6 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
7 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. If a Push-mode Agent sends SIF_GetMessage, note particularly category 5, code 9 (agent registered in Push mode). Messaging protocol complete (failure).
Table 4.1.1.16-1: SIF_GetMessage Protocol

4.1.1.17 SIF_Ack (Push-Mode)

Push-Mode Agents end Selective Message Blocking (SMB) by sending a final SIF_Ack to the ZIS.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. From the message being unblocked/removed from the queue, place the SIF_Header/SIF_SourceId value into SIF_OriginalSourceId and place the SIF_Header/SIF_MsgId value into SIF_OriginalMsgId. Place 3 (final SIF_Ack) into SIF_Code/SIF_Data. Send SIF_Message to ZIS over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 0? If no, go to Step 5.
4 The referenced message has been unblocked and removed from your Agent's queue. The ZIS resumes delivery of events to your Agent. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.17-1: SIF_Ack Protocol (Push-Mode)

4.1.1.18 SIF_Ack (Pull-Mode)

Pull-mode Agents acknowledge messages received in response to SIF_GetMessage and remove them from their queue by sending a SIF_Ack message to the ZIS. SIF_Ack is also sent by Pull-Mode Agents to invoke and end Selective Message Blocking (SMB).

Step Process Flow Control
1 Prepare a SIF_Message/SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. If your Agent is invoking SMB, go to Step 3. If your Agent is ending SMB, go to Step 4.
2 From the message being acknowledged/the message to be removed from the queue, place the SIF_Header/SIF_SourceId value into SIF_OriginalSourceId and place the SIF_Header/SIF_MsgId value into SIF_OriginalMsgId. Place 1 (immediate SIF_Ack) into SIF_Code/SIF_Data or an appropriate error description in SIF_Error. If your Agent indicates a transport error or places 8 (receiver is sleeping) into SIF_Code/SIF_Data, the message will be acknowledged but remain in your Agent's queue. Send SIF_Message to ZIS over appropriate transport. Go to Step 5.
3 From the SIF_Event being blocked, place the SIF_Header/SIF_SourceId value into SIF_OriginalSourceId and place the SIF_Header/SIF_MsgId value into SIF_OriginalMsgId. Place 2 (intermediate SIF_Ack) into SIF_Code/SIF_Data. Send SIF_Message to ZIS over appropriate transport. Go to Step 5.
4 From the SIF_Event being unblocked, place the SIF_Header/SIF_SourceId value into SIF_OriginalSourceId and place the SIF_Header/SIF_MsgId value into SIF_OriginalMsgId. Place 3 (final SIF_Ack) into SIF_Code/SIF_Data. Send SIF_Message to ZIS over appropriate transport.
5 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 9.
6 Is SIF_Status/SIF_Code 0? If no, go to Step 8.
7

If your Agent did not invoke or end SMB for a SIF_Event, the referenced message has been removed from your Agent's queue, unless your agent indicated a transport error or that it was sleeping (in which case the message has been acknowledged but remains in your Agent's queue).

If your Agent invoked SMB by sending an intermediate SIF_Ack, delivery of events is blocked until your Agent removes the SIF_Event from its queue by sending a final SIF_Ack. Your Agent will continue to receive SIF_Responses and SIF_Requests.

If your Agent ended SMB by sending a final SIF_Ack, the ZIS has removed the blocked event from your Agent's queue and resumes delivery of events to your Agent.

Messaging protocol complete (success).
8 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
9 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.18-1: SIF_Ack Protocol (Pull-Mode)

4.1.1.19 SIF_ServiceNotify

SIF_ServiceNotify is a message definition used to deliver service notification messages.

When a SIF Zone service wishes to emit a notification message defined by the SIF Zone Service definition to interested subscribers, the Agent that provides the service publishes the corresponding SIF_ServiceNotify message to the Zone. Upon successful delivery of a SIF_ServiceNotify to the ZIS, the ZIS places the event in the queue for any Agents subscribed to events for the service operations, including the agent that provides the service if the Agent is a subscriber to the notification.

SIF_ServiceNotify messages that relate to a SIF Zone service may only be transmitted by the agent that is registered in the zone as the default provider of the service. Unlike Event messages, SIF_ServiceNotify messages may be packetized. This means a subcribing client must support the demuiltiplexing of simultaneously arriving service packets from multiple Zone Service Notification messages.

Step Process Flow Control
1

Initialize Current Packet Number to 1.

Initialize ServiceMsgId to a new GUID. The SIF_ServiceMsgId MUST be the same for all packets.

2

Prepare a new SIF_ServiceNotify message.

Initialize the SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp.

If the agent would like to indicate minimum encryption and/or authentication requirements for agents receiving this SIF_ServiceNotify, supply SIF_Security with the appropriate settings. Use an equally secure channel when communicating with the Zone, if desired.

If this SIF_ServiceNotify specifically applies to one or more contexts, place them in SIF_Contexts; if omitted, the context is SIF_Default.

Set SIF_PacketNumber to the Current Packet Number.

Set SIF_Service to the name of the SIF Zone Service.

Set SIF_Operation to the name of the operation.

Set SIF_ServiceMsgId to the ServiceMsgId created in Step 1.

3

Initialize SIF Zone Service operation SIF_Body and set the appropriate values for the operation call.

If the operation SIF_Body supports packets, add records to the SIF_Body while the SIF_Message + SIF_Body is less than either the default SIF Zone Service buffer size or the stated buffer size within the SIF Zone Service documentation. If a record cannot be added under the maximum buffer size abort processing the operation.

Add the SIF_Body to the SIF_ServiceNotify.

If a record could not be added go to step 8.
4 If all data records has been added to the SIF_Body set SIF_MorePackets to No. If there is more data to be added in a new SIF_ServiceNotify message set SIF_MorePackets to Yes.
5 Send SIF_Message/SIF_ServiceNotify to Zone over appropriate communication channel. If Zone returns SIF_Ack/SIF_Error go to step 9
6 If more data to send increment Current Packet Number +1 and go to step 2 Go to step 2 if more data to send.
7 Processing is complete if no more data left to send. Stop
8 If a record could not be added to the SIF_ServiceNotify:
  • Set SIF_MorePackets to No.
  • Create a new SIF_Error with the SIF_Error/SIF_Code and SIF_Error/SIF_Desc set to "Responder does not support requested SIF_MaxBufferSize."
  • Send the SIF_ServiceNotify to the Zone. If the first SIF_ServiceNotify packet was not sent, the agent may not have to send the error to the Zone. It may abort the SIF_ServiceNotify.
  • The agent should log the error.
Stop
9 Processing terminated by the Zone.
Stop
Table 4.1.1.19-1: SIF_ServiceNotify Protocol

4.1.1.20 SIF_ServiceInput

This message is used to invoke a method that is exposed by a SIF Zone Service.

An Agent can invoke an operation on a service published by another Agent at any time by sending a SIF_ServiceInput message.

Step Process Flow Control
1

Initialize Current Packet Number to 1

Initialize ServiceMsgId to a new GUID. The SIF_ServiceMsgId MUST be the same for all packets.

2

Prepare a new SIF_ServiceInput message.

Initialize the SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp.

If your Agent would like to explicitly route this service operation to a given Agent, specify the Agent's Id in SIF_DestinationId.

If the agent would like to indicate minimum encryption and/or authentication requirements for agents receiving this SIF_ServiceNotify, supply SIF_Security with the appropriate settings. Use an equally secure channel when communicating with the Zone, if desired.

Since a SIF_ServiceInput applies only to the default context, it is not necessary to specify a value for SIF_Contexts.

Set SIF_PacketNumber to the Current Packet Number.

Set SIF_Service to the name of the SIF Zone Service.

Set SIF_Operation to the name of the operation.

Set SIF_ServiceMsgId to the ServiceMsgId created in Step 1.

Specify the SIF versions the responder may choose from when returning data in SIF_Version. Each version specified MUST be registered in the ZIS as supported by your Agent. It is RECOMMENDED to use 2.*.

Specify the maximum buffer size the Responder must respect when sending SIF_ServiceOutput packets; this MUST be less than or equal to the SIF_MaxBufferSize with which your Agent registered with the Zone.

3

Initialize SIF Zone Service operation SIF_Body and set the appropriate values for the operation call.

If the operation SIF_Body supports packets, add records to the SIF_Body while the SIF_Message + SIF_Body is less than either the default SIF Zone Service buffer size or the stated buffer size within the SIF Zone Service documentation. If a record cannot be added under the maximum buffer size, abort processing the operation.

Add the SIF_Body to the SIF_ServiceInput.

If a record could not be added go to step 8.
4 If all data records has been added to the SIF_Body set SIF_MorePackets to No. If there is more data to be added in a new SIF_ServiceInput message set SIF_MorePackets to Yes.
5 Send SIF_Message/SIF_ServiceInput to Zone over appropriate communication channel. If Zone returns SIF_Ack/SIF_Error go to step 9.
6 If more data to send increment Current Packet Number +1 and go to step 2. Go to step 2 if more data to send.
7 Processing is complete if no more data left to send. Stop
8 If a record could not be added to the SIF_ServiceInput:
  • Set SIF_MorePackets to No.
  • Create a new SIF_Error with the SIF_Error/SIF_Code and SIF_Error/SIF_Desc set to "Responder does not support requested SIF_MaxBufferSize."
  • Send the SIF_ServiceNotify to the Zone. If the first SIF_ServiceInput packet was not sent, the agent may not have to send the error to the Zone. It may abort the SIF_ServiceInput.
  • The agent should log the error.
Stop
9 Processing terminated by the Zone.
Stop
Table 4.1.1.20-1: SIF_ServiceInput Protocol

4.1.1.21 SIF_CancelServiceInputs

Agents can request that a ZIS cancel SIF_ServiceInputs pending or in process, by sending a list of SIF_ServiceInMsgIds in a SIF_CancelServiceInputs message. If an Agent abandons or restarts a process choreography which issued SIF_ServiceInputs, whether or not the SIF_ServiceOutput response stream has started, it is RECOMMENDED that the Agent send one or more SIF_CancelServiceInputs messages to the ZIS. Supporting such process choreographies can place a heavy load on responding Agents, and cancelling requests may spare Zone resources. Cancelling of responses can also reduce the number of Zone Service output packets the receiving/cancelling agent needs to process and discard.

If the cancelling Agent wishes to receive a "final" SIF_ServiceOutput from the ZIS for each cancelled message, it can specify Standard in SIF_CancelServiceInputs/SIF_NotificationType. If the cancelling Agent does not desire or require "final" SIF_ServiceOutputs, the Agent can specify “None” in SIF_NotificationType.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId, and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Add a SIF_CancelServiceInputs element in SIF_SystemControlData.

2 Specify Standard in NotificationType if your Agent desires or requires a "final" SIF_ServiceOut be returned by the ZIS for each cancelled message (SIF_ServiceOut/SIF_MorePackets = No). Otherwise specify None.
3 Add a SIF_ServiceMsgIds element and add a child SIF_ServiceMsgId element for each SIF_ServiceInput that the Agent wishes to cancel. Send SIF_Message to ZIS over appropriate transport.
4 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 8.
5 Is SIF_Status/SIF_Code 0? If no, go to Step 7.
6 The ZIS has accepted the SIF_CancelServiceInputs message. Your Agent will receive or not receive "final" SIF_ServiceOutputs per the specified NotificationType. Messaging protocol complete (success).
7 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (ZIS is asleep) or 7 (your Agent sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
8 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.1.1.21-1: SIF_CancelServiceInputs Protocol

4.1.2 Agent Message Handling Protocols

This section documents how Agents should respond to incoming messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take.

Note that in handling any SIF_Message, an Agent may return a SIF_Ack with SIF_Status/SIF_Code 8 (receiver is sleeping) or 7 (already have this SIF_MsgId from you) if a duplicate message is detected. These responses are typically omitted from the handling protocols below.

4.1.2.1 SIF_Message

Upon receipt of a generic message from the ZIS, in most cases it may be safely assumed that the message XML is well-formed, and perhaps even valid, but the Agent should take the following steps to determine whether the XML is well-formed, optionally validate the message, and check that the message is of a valid type before handing the message off to the respective message handling protocol below.

Step Process Flow Control
1 If your transport layer implementation rejects XML that is not well-formed and optionally that is invalid, go to Step 3, 5, 7 or 9 depending on the extent of that implementation. Otherwise, is the XML message well-formed? If yes, go to step 3.
2 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. If your Agent can scan the incoming message as UTF-8 encoded text to locate SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId, these values can be placed in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Otherwise include these elements with empty values, including an xsi:nil attribute value of true on SIF_OriginalMsgId. Include a SIF_Error element with a SIF_Category of 1 (XML Validation) and a SIF_Code of 2 (message is not well-formed). Go to step 12.
3 Is the root element of the message unprefixed with a local name of SIF_Message? If yes, go to step 5.
4 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Error element with a SIF_Category of 1 (XML Validation) and a SIF_Code of 3 (generic validation error). Go to step 12.
5 Is the namespace for SIF_Message a namespace of a major version of SIF your Agent supports? Is SIF_Message/@Version present with a value that your Agent supports? (If omitted, interpret SIF_Message/@Version as 1.1.) If yes, go to step 7.
6 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Error element with a SIF_Category of 12 (Generic Message Handling) and a SIF_Code of 3 (version not supported). Go to step 12.
7 If your Agent does not validate messages, go to step 9. Otherwise choose a validation schema based on the value of SIF_Message/@Version. Does the message validate? If yes, go to step 9.
8 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Error element with a SIF_Category of 1 (XML Validation) and an appropriate SIF_Code from the corresponding choices in Error Codes. Go to step 12.
9 If the namespace for SIF_Message is for a previous major version of SIF, handle according to the specification for SIF_Message/@Version. Otherwise, is the message type (the child element of SIF_Message) SIF_Event, SIF_Request, SIF_Response, SIF_Ping (Push-mode only), SIF_Sleep (Push-mode only), SIF_Wakeup (Push-mode only), or SIF_CancelRequests (Push-mode only and your Agent chooses to support this optional message)? If yes, go to step 11.
10 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Error element with a SIF_Category of 12 (Generic Message Handling) and a SIF_Code of 2 (message not supported). Go to step 12.
11 Process per the corresponding message handling protocol below. Message handling is complete.
12 If your Agent is a Push-mode Agent, return the SIF_Ack to the ZIS. If your Agent is a Pull-mode Agent send the SIF_Ack to the ZIS per SIF_Ack (Pull-Mode) above. Message handling is complete.
Table 4.1.2.1-1: SIF_Message Handling

4.1.2.2 SIF_Event

A ZIS places a SIF_Event in your Agent's queue when an event occurs in a Zone Context with regard to an object for which your agent has subscribed to receive events. A SIF_Event is delivered when it is the next message pending delivery in the queue.

An event may apply to one or more contexts; these are listed in SIF_Header/SIF_Contexts. If SIF_Contexts is not present, the context for the event is SIF_Default. The type of event is specified in SIF_EventObject/@Action, the corresponding data object is in SIF_EventObject. A Change or Delete event may contain a partial object, but it must include the necessary attribute(s) and element(s) to uniquely identify the object being changed or deleted. These keys/identifiers are typically communicated in the root attributes of an object.

Step Process Flow Control
1 Does your Agent invoke Selective Message Blocking (SMB) for all events, or does this event indicate to your Agent that it will invoke SMB? If no, go to Step 3.
2

Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 2 (intermediate SIF_Ack) in SIF_Status/SIF_Code.

If your Agent is a Push-Mode Agent, return the SIF_Ack to the ZIS and commence sending the necessary requests as described in the SIF_Request protocol above to complete processing of the event per your Agent's business rules. When complete or if an error occurs, end SMB as described in the SIF_Ack (Push-Mode) protocol above.

If your Agent is a Pull-Mode Agent, send the SIF_Ack to the ZIS per SIF_Ack (Pull-Mode) above and commence sending the necessary requests as described in the SIF_Request protocol above to complete processing of the event per your Agent's business rules. When complete or if an error occurs, end SMB as described in the SIF_Ack (Pull-Mode) protocol above.

If an error occurs, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

Message handling complete.
3

If your Agent is a Pull-Mode Agent, process the event per your Agent's business rules. When complete or if an error occurs, acknowledge the message and remove it from your Agent's queue per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent, it has one of two options: process the event, then acknowledge it; or acknowledge the event, then process it. The advantage of first processing the event is the ability to return a descriptive error, if necessary, to the ZIS when acknowledging the message. The disadvantage of first processing is that if the processing is long running, the connection from the ZIS to your Agent may time out, which will lead to the event being redelivered to your Agent in another delivery attempt, to possibly run into another time-out. To avoid the latter, it is RECOMMENDED that your Push-Mode Agent first acknowledge the event, then process it, unless event processing is known to always occur within a reasonable amount of time. Agents that first acknowledge then process SHOULD persist the event locally until processing is complete, as the event is removed from your Agent's queue upon successful acknowledgement, otherwise the event will be lost in the case of an application or system error that affects your Agent's ability to complete processing of the event.

Choose an option and process the event according to your Agent's business rules. When acknowledging: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data in the case of successful processing, and return the SIF_Ack to the ZIS. If an error has occurred, include a SIF_Error element with an appropriate SIF_Category and SIF_Code and describe the error as needed in SIF_Desc and optionally SIF_ExtendedDesc. Note that indicating a transport error will not remove the message from your Agent's queue, only acknowledge it. The same action can be accomplished indicating 8 (receiver is sleeping) in SIF_Status/SIF_Code.

If an error occurs regardless of the option chosen, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

Message handling complete
Table 4.1.2.2-1: SIF_Event Handling

4.1.2.3 SIF_Request

A ZIS places a SIF_Request in your Agent's queue when an Agent sends a request directly to your Agent, or when an Agent sends a request without a SIF_DestinationId and your agent is registered as the Provider for the object requested in SIF_Query, or in the case of SIF_ExtendedQuery when your agent is registered as the Provider of the object specified by the Requester in SIF_ExtendedQuery/SIF_DestinationProvider or SIF_ExtendedQuery/SIF_From/@ObjectName. The ZIS will not send your Agent a SIF_ExtendedQuery unless your Agent has registered its support for that query type using SIF_Provide or SIF_Provision. A SIF_Request is delivered when it is the next message pending delivery in your Agent's queue.

Any error that occurs while generating SIF_Responses during SIF_Request handling MUST be sent to the Requester with SIF_MorePackets set to No, at which point the response stream ends.

Step Process Flow Control
1 Examine SIF_Header/SIF_Contexts to determine the context for the request; if none is specified, the context is SIF_Default. Go to Step 3 if the context is supported.
2

Prepare a SIF_Response message with a copy of SIF_Contexts, SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate General Message Handling and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the requested context is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Message handling complete.
3 Examine the SIF_Version element or elements specified in the SIF_Request message. If more than one version is supported, select the highest version number supported. Go to Step 5 if a version is supported.
4

Prepare a SIF_Response message with a copy of SIF_Contexts, SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the requested SIF_Versions are not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Message handling complete.
5 Examine the SIF_MaxBufferSize specified in the SIF_Request message. Go to Step 7 if it is greater than or equal to the minimum buffer size your Agent can support. (The buffer size of individual packets will be handled below).
6

Using the SIF version selected in Step 1, prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_MaxBufferSize cannot be honored.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Message handling complete.
7 Is SIF_ExtendedQuery specified? If yes, go to Step 12.
8 The query type is SIF_Query. Examine the object name being queried in SIF_QueryObject/@ObjectName. Go to Step 10 if the object is supported.
9

Prepare a SIF_Response message using the version chosen in Step 1 with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the object is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Stop processing the message.
10 Examine the query represented, if any, by SIF_ConditionGroup, or SIF_Example in the case of objects that support query-by-example, and determine whether it is supported. Go to Step 14 if neither SIF_ConditionGroup nor SIF_Example is present, or if the query represented by SIF_ConditionGroup or SIF_Example is supported.
11

Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the query is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Stop processing the message.
12 Examine the query represented by SIF_ExtendedQuery, and determine whether it is supported. Go to Step 14 if the query is supported.
13

Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the query is not supported.

Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No.

Send the SIF_Response to the original requester and acknowledge the error to the ZIS.

Stop processing the message.
14

Note that Push-Mode Agents should acknowledge receipt of the SIF_Request as response generation is typically a long-running operation that will typically lead to HTTP time-outs. As the request will be removed from the Agent's queue, it is RECOMMENDED that the Push-Mode Agent persist the request and its SIF_PacketNumber while generating responses, in case of an application or system failure that prevents it from completing the request processing; upon restarting, the Agent can end the response stream with a SIF_Error, SIF_PacketNumber set to the last successfully transmitted SIF_PacketNumber + 1 and SIF_MorePackets set to No.

If a Push-Mode Agent elects to successfully acknowledge the request before processing, it can do so. Otherwise it should acknowledge receipt of the request upon completion of response generation.

Pull-Mode Agents can choose to acknowledge receipt of the request here or at the end of response generation.

Initialize packet counter to 1.

15 Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message. When handling SIF_ExtendedQuery, copy the requested columns into SIF_ExtendedQueryResults/SIF_ColumnHeaders.
16 Add one or more of the matching objects into SIF_ObjectData, for SIF_Query, or rows into SIF_ExtendedQueryResult, for SIF_ExtendedQuery, until no more will fit within the specified buffer size. If no objects or rows will fit within SIF_MaxBufferSize, go to Step 15 with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that SIF_MaxBufferSize cannot be honored. Otherwise, note that only requested columns are returned when processing SIF_ExtendedQuery. When processing SIF_Query, if the requester specified only certain elements be returned, that the Responder needs to return only those elements and their parent elements and attributes. Not supporting a requested element/attribute does not exclude the object from the response stream; include the parent elements/attributes of any missing elements, including the object itself. If no errors occur in retrieving/adding matching objects, go to step 18.
17 Set SIF_PacketNumber to the current packet counter and SIF_MorePackets to No. Add an appropriate SIF_Error element to the SIF_Response and send the SIF_Response to the ZIS. Go to Step 21.
18 Set SIF_PacketNumber to the current packet counter value and set SIF_MorePackets appropriately. Send the SIF_Response to the ZIS.
19 Examine the SIF_Ack returned by the ZIS. If an error occurred, stop processing the SIF_Request message. Go to Step 21.
20 Determine if more objects or rows match the specified conditions. If yes, increment the packet counter and go to Step 15; otherwise, go to Step 21.
21 If your Agent has not yet acknowledged receipt of the incoming request, acknowledge successful receipt of the request, or return a descriptive error to the ZIS. Message handling complete.
Table 4.1.2.3-1: SIF_Request Handling

4.1.2.4 SIF_Response

A ZIS places a SIF_Response in your Agent's queue when a responder sends a response packet to your Agent per a SIF_Request previously sent by your Agent. It is delivered when it is the next message available for delivery to your Agent.

Step Process Flow Control
1 SIF_RequestMsgId indicates which of your SIF_Requests this packet is in response to. Is SIF_Error present? If no, go to Step 3.
2

The Responder's handling of your Agent's SIF_Request has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. This is the last packet your Agent will receive associated with that request.

If your Agent is a Pull-Mode Agent, acknowledge the message per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data, and return the SIF_Ack to the ZIS.

Message handling complete. Any resources associated with the request can be released.
3

If your Agent is a Pull-Mode Agent, process the response per your Agent's business rules. When complete or if an error occurs, acknowledge the message and remove it from your Agent's queue per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent, it has one of two options: process the response, then acknowledge it; or acknowledge the response, then process it. The advantage of first processing the response is the ability to return a descriptive error, if necessary, to the ZIS when acknowledging the message. The disadvantage of first processing is that if the processing is long running, the connection from the ZIS to your Agent may time out, which will lead to the response being redelivered to your Agent in another delivery attempt, to possibly run into another time-out. To avoid the latter, it is RECOMMENDED that your Push-Mode Agent first acknowledge the response, then process it, unless response processing is known to always occur within a reasonable amount of time. Agents that first acknowledge then process SHOULD persist the response locally until processing is complete, as the response is removed from your Agent's queue upon successful acknowledgement, otherwise the response will be lost in the case of an application or system error that affects your Agent's ability to complete processing of the response.

Choose an option and process the response according to your Agent's business rules. When acknowledging: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data in the case of successful processing, and return the SIF_Ack to the ZIS. If an error has occurred, include a SIF_Error element with an appropriate SIF_Category and SIF_Code and describe the error as needed in SIF_Desc and optionally SIF_ExtendedDesc. Note that indicating a transport error will not remove the message from your Agent's queue, only acknowledge it. The same action can be accomplished indicating 8 (receiver is sleeping) in SIF_Status/SIF_Code.

If an error occurs regardless of the option chosen, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

Message handling complete. If SIF_MorePackets is No, this is the last packet associated with the request your Agent will receive; any resources associated with the request can be released.
Table 4.1.2.4-1: SIF_Response Handling

4.1.2.5 SIF_Ping (Push-Mode only)

The ZIS is pinging your Agent to see if it is reachable, "awake" and/or processing messages.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. If your Agent is "awake," include a SIF_Status element with a SIF_Code of 1 (immediate SIF_Ack). Otherwise you may optionally notify the ZIS that your Agent is asleep by returning a SIF_Code of 8 (receiver is sleeping).  
2 Return the SIF_Ack to the ZIS. Message processing complete (success).
Table 4.1.2.5-1: SIF_Ping Handling

4.1.2.6 SIF_Sleep (Push-Mode only)

The ZIS has changed its state to "asleep" and is either not processing incoming messages or all incoming messages will be acknowledged with a SIF_Ack/SIF_Status/SIF_Code value of 8 (receiver is sleeping); delivery of queued messages to your Agent is halted. Your Agent SHOULD avoid sending messages to the ZIS until receipt of a SIF_Wakeup message, or be prepared to handle transport errors or the aforementioned acknowledgement.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 1 (immediate SIF_Ack). Change your Agent's ZIS state to "asleep."  
2 Return the SIF_Ack to the ZIS. Message processing complete (success).
Table 4.1.2.6-1: SIF_Sleep Handling

4.1.2.7 SIF_Wakeup (Push-Mode only)

The ZIS has changed its state to "awake" and is processing incoming messages and delivering queued messages again.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 1 (immediate SIF_Ack). Change your Agent's ZIS state to "awake."  
2 Return the SIF_Ack to the ZIS. Message processing complete (success).
Table 4.1.2.7-1: SIF_Wakeup Handling

4.1.2.8 SIF_CancelRequests (Push-Mode only) (optional)

A ZIS is requesting that your Agent cancel processing of one or more SIF_Request messages. Support for handling of this message is currently optional for Push-Mode Agents. If your Agent does not support SIF_CancelRequests, it returns a Generic Message Handling error upon receipt of the SIF_SystemControl message, error code "Message not supported," per the SIF_Message handling protocol.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 1 (immediate SIF_Ack).  
2 If your Agent is currently preparing SIF_Response packets for any of the SIF_Request messages specified in the SIF_RequestMsgId element(s), stop processing the request(s). If your Agent has any of the specified SIF_Requests queued locally, remove them from the agent local queue.  
3 Return the SIF_Ack to the ZIS. Message processing complete (success).
Table 4.1.2.8-1: SIF_CancelRequests Handling

4.1.2.9 SIF_CancelServiceInputs (Push-Mode only) (optional)

A ZIS is requesting that your Agent cancel processing of one or more SIF_ServiceInput messages. Support for handling of this message is currently optional for Push-Mode Agents. If your Agent does not support SIF_CancelServiceInputs, it returns a Generic Message Handling error upon receipt of the SIF_SystemControl message, error code "Message not supported," per the SIF_Message handling protocol.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 1 (immediate SIF_Ack).  
2 If your Agent is currently preparing SIF_ServiceOutput packets for any of the SIF_ServiceInput messages specified in the SIF_ServiceMsgId element(s), stop processing the request(s). If your Agent has any of the specified SIF_ServiceInput queued locally, remove them from the agent local queue.  
3 Return the SIF_Ack to the ZIS. Message processing complete (success).
Table 4.1.2.9-1: SIF_CancelServiceInputs Handling

4.1.2.10 SIF_ServiceNotify

SIF_ServiceNotify is a message definition used to deliver service events.

A ZIS places a SIF_ServiceNotify in your Agent's queue when a service notification event occurs in the zone and your agent has previously provisioned itself as a subscriber to that event. A SIF_ServiceNotify is delivered when it is the next message pending delivery in the queue.

A service event may only apply to the SIF_Default context. If SIF_Contexts is not present, the context for the event is SIF_Default. The Service that created the event is specified in the SIF_Service element. The name of the notification event is specified in the SIF_Operation element.

Note that unlike SIF_Event messages, SIF_ServiceNotify does not support SMB and can be delivered in more than one packet.

Step Process Flow Control
1

If your Agent is a Pull-Mode Agent, process the service event per your Agent's business rules. When complete or if an error occurs, acknowledge the message and remove it from your Agent's queue per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent, it has one of two options: process the service event, then acknowledge it; or acknowledge the service event, then process it. The advantage of first processing the event is the ability to return a descriptive error, if necessary, to the ZIS when acknowledging the message. The disadvantage of first processing is that if the processing is long running, the connection from the ZIS to your Agent may time out, which will lead to the event being redelivered to your Agent in another delivery attempt, to possibly run into another time-out. To avoid the latter, it is RECOMMENDED that your Push-Mode Agent first acknowledge the event, then process it, unless event processing is known to always occur within a reasonable amount of time. Agents that first acknowledge then process SHOULD persist the event locally until processing is complete, as the event is removed from your Agent's queue upon successful acknowledgement, otherwise the event will be lost in the case of an application or system error that affects your Agent's ability to complete processing of the service event.

Choose an option and process the service event according to your Agent's business rules. When acknowledging: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data in the case of successful processing, and return the SIF_Ack to the ZIS.

If an error has occurred, include a SIF_Error element with an appropriate SIF_Category and SIF_Code and describe the error as needed in SIF_Desc and optionally SIF_ExtendedDesc. Note that indicating a transport error will not remove the message from your Agent's queue, only acknowledge it. The same action can be accomplished indicating 8 (receiver is sleeping) in SIF_Status/SIF_Code.

If an error occurs regardless of the option chosen, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

Message handling complete.

Table 4.1.2.10-1: SIF_ServiceNotify Handling

4.1.2.11 SIF_ServiceInput

This message is used to invoke a method that is exposed by a SIF Zone Service.

A ZIS places a SIF_ServiceInput in your Agent's queue when an Agent sends a directed service request to your Agent, or when an Agent sends a request without a SIF_DestinationId and your agent is registered as the provider of the service specified in SIF_Operation. A SIF_ServiceInput is delivered when it is the next message pending delivery in your Agent's queue.

Any error that occurs while generating SIF_ServiceOutputs during SIF_ServiceInput handling MUST be sent to the Requester with SIF_MorePackets set to No, at which point the response stream ends.

An Agent may wait until all SIF_ServiceInput packets have been received before processing the SIF_ServiceInput. This will impact the type of SIF_Ack returned per packet received.

Step Process Flow Control
1

Since a SIF_ServiceInput can apply only to the default context, it is not necessary to specify a value for SIF_Header/SIF_Contexts.

Go to step 3.
2

Specify the maximum buffer size the Zone Service must respect when sending SIF_ServiceOutput packets; this MUST be less than or equal to the SIF_MaxBufferSize with which your Agent registered with the ZIS.

3

Examine the SIF_Version element or elements specified in the SIF_ServiceInput message. If more than one version is supported, select the highest version number supported. If a wildcard * anywhere in a version was specified, choose the maximum matching version supported by your agent or the version appropriate for the Service operation.

Go to step 5 if the version is supported.

4

Prepare a SIF_ServiceOutput message with SIF_DestinationId set to SIF_SourceId and SIF_ServiceMsgId set to SIF_ServiceMsgId from the SIF_ServiceInput message. Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate registration and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the version is not supported. Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No. Send the SIF_ServiceOutput to the Zone and acknowledge the error to the Zone via a SIF_Ack if a SIF_Ack has not already been returned.

Stop processing the message

5

Examine the SIF_MaxBufferSize specified in the SIF_ServiceInput message if it is greater than the minimum buffer size supported by your agent.

Go to step 7 if the buffer size is greater than the minimum buffer size in your agent.

6

Prepare a SIF_ServiceOutput message with SIF_DestinationId set to SIF_SourceId and SIF_ServiceMsgId set to SIF_ServiceMsgId from the SIF_ServiceInput message. Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Zone Services and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_MaxBufferSize is not supported. Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No. Send the SIF_ServiceOutput to the Zone and acknowledge the error to the Zone via a SIF_Ack if a SIF_Ack has not already been returned.

Stop processing the message

7

Examine the SIF_ServiceInput/SIF_Service and SIF_ServiceInput/SIF_Operation if they are supported.

Go to step 9 if they are supported
8

Prepare a SIF_ServiceOutput message with SIF_DestinationId set to SIF_SourceId and SIF_ServiceMsgId set to SIF_ServiceMsgId from the SIF_ServiceInput message. Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Zone Services and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_Service and/or SIF_Operation is invalid. Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No. Send the SIF_ServiceOutput to the Zone and acknowledge the error to the Zone via a SIF_Ack if a SIF_Ack has not already been returned.

Stop processing the message

9

Process the service operation accordingly.

If the processing is complete go to step 11.
10

Prepare a SIF_ServiceOutput message with SIF_DestinationId set to SIF_SourceId and SIF_ServiceMsgId set to SIF_ServiceMsgId from the SIF_ServiceInput message. Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Zone Services and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_Service and/or SIF_Operation failed. Add SIF_PacketNumber with a value of 1 and set SIF_MorePackets to No. Send the SIF_ServiceOutput to the Zone and acknowledge the error to the Zone via a SIF_Ack if a SIF_Ack has not already been returned.

Stop processing the message

11 Prepare to return the results
12

Initialize Current Packet Number to 1
Collect sender's SIF_SourceId from SIF_ServiceInput/SIF_Header/SIF_SourceId
Collect Maximum Buffer Size from SIF_ServiceInput/SIF_MaxBufferSize
Collect SIF_Version(s) from SIF_ServiceInput/SIF_Version

13 Prepare a new SIF_ServiceOutput message.
Initialize the SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp.
If the agent would like to indicate minimum encryption and/or authentication requirements for agents receiving this SIF_ServiceNotify, supply SIF_Security with the appropriate settings. Use an equally secure channel when communicating with the Zone, if desired.
Since SIF_ServiceOutput can apply to only one context, the value in SIF_Contexts is always SIF_Default.
Set SIF_ServiceOutput/SIF_Header/SIF_DestinationId to the value from SIF_ServiceInput/SIF_Header/SIF_SourceId
Set SIF_PacketNumber to the Current Packet Number.
Set SIF_Service to the name of the SIF Zone Service.
Set SIF_Operation to the name of the operation.
Set SIF_ServiceMsgId to the SIF_ServiceMsgId of the original SIF_ServiceInput/SIF_ServiceMsgId

14 Initialize SIF Zone Service operation SIF_Body and set the appropriate values for the operation call.
If the operation SIF_Body supports packets add records to the SIF_Body while the SIF_Message + SIF_Body is less than either the default SIF Zone Service buffer size or the stated buffer size within the SIF Zone Service documentation. If a record cannot be added under the maximum buffer size abort processing the operation.
Add the SIF_Body to the SIF_ServiceOutput
If a record could not be added go to step 19.
15 If all data records has been added to the SIF_Body set SIF_MorePackets to No. If there is more data to be added in a new SIF_ServiceOutput message set SIF_MorePackets to Yes.
16 Send SIF_Message/SIF_ServiceOutput to Zone over appropriate communication channel. If Zone returns SIF_Ack/SIF_Error go to step 20
17 If more data to send increment Current Packet Number +1 and go to step 2 Go to step 13 if more data to send.
18 Processing is complete if no more data left to send. Stop
19 If a record could not be added to the SIF_ServiceOutput
Set SIF_MorePackets to No
Create a new SIF_Error with the SIF_Error/SIF_Code and SIF_Error/SIF_Desc set appropriately.
Send the SIF_ServiceOutput to the Zone. If the first SIF_ServiceOutput packet was not sent, the agent may not have to send the error to the Zone. It may abort the SIF_ServiceOutput.
The agent should log the error.
Stop
20 Processing terminated by the Zone.
Stop
Table 4.1.2.11-1: SIF_ServiceInput Handling

4.1.2.12 SIF_ServiceOutput

A ZIS places a SIF_ServiceOut in your Agent's queue when a responder sends a response packet to your Agent per a SIF_ServiceIn previously sent by your Agent. It is delivered when it is the next message available for delivery to your Agent.

Step Process Flow Control
1 SIF_ServiceInMsgId indicates which of your SIF_ServiceIns this packet is in response to. Is SIF_Error present? If no, go to Step 3.
2

The Responder's handling of your Agent's SIF_ServiceIn has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. This is the last packet your Agent will receive associated with that request.

If your Agent is a Pull-Mode Agent, acknowledge the message per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data, and return the SIF_Ack to the ZIS.

Message handling complete. Any resources associated with the request can be released.
3

If your Agent is a Pull-Mode Agent, process the response per your Agent's business rules. When complete or if an error occurs, acknowledge the message and remove it from your Agent's queue per SIF_Ack (Pull-Mode) above.

If your Agent is a Push-Mode Agent, it has one of two options: process the response, then acknowledge it; or acknowledge the response, then process it. The advantage of first processing the response is the ability to return a descriptive error, if necessary, to the ZIS when acknowledging the message. The disadvantage of first processing is that if the processing is long running, the connection from the ZIS to your Agent may time out, which will lead to the response being redelivered to your Agent in another delivery attempt, to possibly run into another time-out. To avoid the latter, it is RECOMMENDED that your Push-Mode Agent first acknowledge the response, then process it, unless response processing is known to always occur within a reasonable amount of time. Agents that first acknowledge then process SHOULD persist the response locally until processing is complete, as the response is removed from your Agent's queue upon successful acknowledgement, otherwise the response will be lost in the case of an application or system error that affects your Agent's ability to complete processing of the response.

Choose an option and process the response according to your Agent's business rules. When acknowledging: Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Agent's Agent Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Place 1 (immediate SIF_Ack) in SIF_Status/SIF_Data in the case of successful processing, and return the SIF_Ack to the ZIS. If an error has occurred, include a SIF_Error element with an appropriate SIF_Category and SIF_Code and describe the error as needed in SIF_Desc and optionally SIF_ExtendedDesc. Note that indicating a transport error will not remove the message from your Agent's queue, only acknowledge it. The same action can be accomplished indicating 8 (receiver is sleeping) in SIF_Status/SIF_Code.

If an error occurs regardless of the option chosen, it is RECOMMENDED that your Agent publish a SIF_LogEntry Add event.

Message handling complete. If SIF_MorePackets is No, this is the last packet associated with the request your Agent will receive; any resources associated with the request can be released.
Table 4.1.2.12-1: SIF_ServiceOutput Handling

4.2 ZIS Protocols

4.2.1 ZIS Messaging Protocols

This section documents how Zone Integration Servers send individual messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take. These correspond to each of the actions a Zone Integration Server can initiate.

4.2.1.1 SIF_Message Delivery (SIF_Event, SIF_Request, SIF_Response, SIF_ServiceInput, SIF_ServiceOutput, SIF_ServiceNotify to a Push-mode Agent)

A ZIS contacts a Push-Mode Agent to deliver SIF_Event, SIF_Request and SIF_Response messages queued for the Agent. This delivery protocol starts with a check on whether there are messages pending, as the protocol can loop as messages are delivered.

Step Process Flow Control
1 Are there messages queued for the Agent? If yes, go to Step 2. Otherwise messaging protocol complete (success).
2 Is the state of the Agent "asleep?" If yes, the ZIS SHOULD wait until the Agent sends a SIF_Wakeup message or re-registers in Push mode before attempting message delivery. Otherwise the ZIS MUST be prepared to handle transport errors/exceptions and/or the Agent responding with a SIF_Status/SIF_Code of 8 (receiver is sleeping). If no, go to Step 3. Otherwise messaging protocol complete (success).
3 Has the Agent previously invoked SMB? If no, go to Step 6.
4 Iterate through the Agent's queue from the message received first to the most recently received message. Stop at the first SIF_Response or SIF_Request in the queue, if one exists. If one exists, it is the next message to be delivered. Go to Step 7.
5 The only messages queued for the Agent are SIF_Events; try again later, or after a SIF_Response or SIF_Request arrives, or after the Agent has ended SMB by sending a final SIF_Ack. Messaging protocol complete (no message needs to be delivered).
6 The next message to be delivered is the message received first in the Agent's queue.
7 Is SIF_Header/SIF_Security present in the SIF_Message with SIF_EncryptionLevel, SIF_AuthenticationLevel, or both? If no, the message delivery encryption/authentication levels are the minimum encryption/authentication levels set up for the Zone. Go to Step 9.
8 The ZIS MUST guarantee that the minimum encryption and/or authentication levels specified are respected when delivering this message. Use the higher of these and the Zone's minimum encryption and/or authentication levels during message delivery.
9 If a connection is already open to the Push-Mode Agent from a previously delivered message, are the encryption and authentication levels greater than or equal to those needed for the delivery of this message? If there is no connection open, go to Step 11. If there is and the encryption/authentication levels are adequate for delivery, go to Step 15.
10 Attempt to renegotiate the encryption/authentication levels for the connection, or close the connection and attempt to open a new connection with adequate encryption/authentication levels. Go to Step 12.
11 If the registered transport layer is known to not provide adequate encryption/authentication levels (e.g. SIF HTTP), go to Step 12. Otherwise attempt to open a connection to the Agent with adequate encryption/authentication levels, using the appropriate transport layer.
12 Was a connection opened or renegotiated with adequate encryption/authentication levels? If no, the message cannot be delivered; remove it from the Agent's queue. It is RECOMMENDED that your ZIS log the error. Your ZIS MUST post a SIF_LogEntry  Add event with the appropriate error category and code, containing a copy of the SIF_Header of the queued message. SIF_LogEntry/SIF_Desc MUST contain the SIF_SourceId of the Agent that failed to receive the message. Go to Step 1 to start delivery of the next queued message, if desired. Otherwise messaging protocol complete (error).
13 Is the agent issuing the notification a provider of the corresponding service? If yes, go to Step 15
14 Prepare a SIF_Ack/SIF_Error category 14 (SIF Zone Service) code 17 (Not a provider for this service) and send it to the agent improperly issuing the event.
15 Send the message to the Agent over the connection.
16 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 26.
17 Is SIF_Status/SIF_Code 1 (immediate SIF_Ack)? If no, go to Step 19.
18 The Agent has successfully acknowledged receipt of the message; remove it from the Agent's queue. Go to Step 1 to start delivery of the next queued message, if desired. Otherwise messaging protocol complete (success).
19 Is SIF_Status/SIF_Code 2 (intermediate SIF_Ack)? If no, go to Step 23.
20 The Agent is invoking SMB. Is the delivered message a SIF_Event? If yes, go to Step 22.
21 The Agent has violated protocol; remove the message from the Agent's queue. It is RECOMMENDED that your ZIS log the error. Your ZIS MUST post a SIF_LogEntry  Add event with the appropriate error category of 13 (SMB Error) and code 2 (SMB can only be invoked for SIF_Event), containing a copy of the SIF_Header of the queued message. SIF_LogEntry/SIF_Desc MUST contain the SIF_SourceId of the Agent that committed the protocol error. Go to Step 1 to start delivery of the next queued message, if desired. Otherwise messaging protocol complete (error).
22 The Agent has invoked SMB on this SIF_Event. Persist that the Agent has invoked SMB along with the SIF_MsgId of the event. The event stays in the agent's queue as blocked, and all other events are frozen until the Agent eventually ends SMB by sending a final SIF_Ack with this SIF_MsgId in SIF_OriginalMsgId, or by sending a SIF_Wakeup or by re-registering. Go to Step 1 to start delivery of the next queued message, if desired. Otherwise messaging protocol complete (success).
23 Is SIF_Status/SIF_Code 8 (receiver is sleeping)? If no, go to Step 25.
24 The Agent is asleep. Re-attempt delivery later. Messaging protocol complete (success).
25 Messaging protocol has failed due to a SIF_Status/SIF_Code of 7 (already have this SIF_MsgId). The ZIS cannot correct this, as the SIF_MsgId originates from an Agent and can't be changed without other repercussions. Remove the message from the Agent's queue. It is RECOMMENDED that your ZIS log the error. Your ZIS MUST post a SIF_LogEntry  Add event with the appropriate error category and code, containing a copy of the SIF_Header of the queued message. SIF_LogEntry/SIF_Desc MUST contain the SIF_SourceId of the Agent that did not receive the message. Go to Step 1 to start delivery of the next queued message, if desired. Otherwise messaging protocol complete (error).
26 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. If SIF_Category does not indicate a transport error, remove the message from the Agent's queue. Otherwise re-attempt delivery of this message later. It is RECOMMENDED that your ZIS log the error. Your ZIS MAY post a SIF_LogEntry  Add event with the appropriate error category and code, containing a copy of the SIF_Header of the queued message. SIF_LogEntry/SIF_Desc MUST contain the SIF_SourceId of the Agent that indicated the error. Go to Step 1 to start delivery of the next queued message, if desired. Otherwise messaging protocol complete (error).
Table 4.2.1.1-1: SIF_Message Delivery Protocol

4.2.1.2 SIF_Ping (to a Push-mode Agent)

A ZIS can "ping" a Push-Mode Agent or check that it's "awake" by sending a SIF_Ping message to the Agent. If the Agent returns a successful acknowledgement, it is awake; the Agent may also reply that it is asleep. As a Push-Mode Agent may be offline completely, Zone Integration Servers should be prepared to handle transport errors directly or wrapped in a SIF_Ack/SIF_Error by underlying code.

Step Process Flow Control
1 Prepare a SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, the Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_Ping element in SIF_SystemControlData. Send SIF_Message to Agent over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 8.
3 Is SIF_Status/SIF_Code 1? If no, go to Step 5.
4 The Agent is awake. Messaging protocol complete (success).
5 Is SIF_Status/SIF_Code 8 (receiver is sleeping)? If no, go to Step 7.
6 The Agent is asleep. Messaging protocol complete (success).
7 Messaging protocol has failed due to a SIF_Status/SIF_Code of 7 (your ZIS sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
8 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.2.1.2-1: SIF_Ping Protocol

4.2.1.3 SIF_Sleep (to a Push-mode Agent)

A ZIS can send a SIF_Sleep message to a Push-Mode Agent to change its state to "sleeping," indicating that it will either be offline or acknowledging incoming messages with a SIF_Status/SIF_Code of 8 (receiver is sleeping), and that it will not be delivering messages to the Agent until it "wakes up" by sending a SIF_Wakeup message.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_Sleep element in SIF_SystemControlData. Send SIF_Message to Agent over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 1? If no, go to Step 5.
4 The Agent has successfully acknowledged your SIF_Sleep and should not be expecting further message delivery until your ZIS sends a SIF_Wakeup. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (Agent is asleep) or 7 (your ZIS sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.2.1.3-1: SIF_Sleep Protocol

4.2.1.4 SIF_Wakeup (to a Push-mode Agent)

A ZIS can send a SIF_Wakeup message to a Push-Mode Agent to change its state to "awake;" i.e., that it is ready to process incoming messages and deliver queued messages again.

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place an empty SIF_Wakeup element in SIF_SystemControlData. Send SIF_Message to Agent over appropriate transport.
2 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 6.
3 Is SIF_Status/SIF_Code 1? If no, go to Step 5.
4 The Agent has successfully acknowledged your "awake" status. Messaging protocol complete (success).
5 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (Agent is asleep) or 7 (your ZIS sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
6 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. Messaging protocol complete (failure).
Table 4.2.1.4-1: SIF_Wakeup Protocol

4.2.1.5 SIF_CancelRequests (to a Push-mode Agent)

A ZIS can send a SIF_CancelRequests message to a Push-Mode Agent after receiving a SIF_CancelRequests messages from another agent, as per the SIF_CancelRequests message handling protocol. As support for this message is currently optional for Push-Mode Agents, the ZIS should be prepared to handle a Generic Message Handling error from the Agent upon receipt of the SIF_SystemControl message, error code "Message not supported."

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place a SIF_CancelRequests element in SIF_SystemControlData.  
2 Place the requests that should be cancelled in SIF_RequestMsgIds/SIF_RequestMsgId. While it is not used by the Push-Mode Agent, set the NotificationType to None. Send SIF_Message to Agent over appropriate transport.
3 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 7.
4 Is SIF_Status/SIF_Code 1? If no, go to Step 6.
5 The Agent has successfully acknowledged your SIF_CancelRequests and should have cancelled any corresponding response activity. Messaging protocol complete (success).
6 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (Agent is asleep) or 7 (your ZIS sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
7 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. If the SIF_Error is a Generic Message Handling error, error code "Message not supported," go to Step 8. Otherwise messaging protocol complete (failure).
8 The Agent does not support SIF_CancelRequests. Messaging protocol complete (success).
Table 4.2.1.5-1: SIF_CancelRequests Protocol

4.2.1.6 SIF_CancelServiceInputs (to a Push-mode Agent)

A ZIS can send a SIF_CancelServiceInputs message to a Push-Mode Agent after receiving a SIF_CancelServiceInputs messages from another agent, as per the SIF_CancelServiceInputs message handling protocol . As support for this message is currently optional for Push-Mode Agents, the ZIS should be prepared to handle a Generic Message Handling error from the Agent upon receipt of the SIF_SystemControl message, error code "Message not supported."

Step Process Flow Control
1 Prepare a SIF_Message/SIF_SystemControl message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place a SIF_CancelServiceInputs element in SIF_SystemControlData.  
2 Place the requests that should be cancelled in SIF_ServiceMsgIds/SIF_ServiceMsgId. While it is not used by the Push-Mode Agent, set the NotificationType to None. Send SIF_Message to Agent over appropriate transport.
3 Receive SIF_Ack in response. Is SIF_Error present? If yes, go to Step 7.
4 Is SIF_Status/SIF_Code 1? If no, go to Step 6.
5 The Agent has successfully acknowledged your SIF_CancelServiceInputs and should have cancelled any corresponding response activity. Messaging protocol complete (success).
6 Messaging protocol has failed due to a SIF_Status/SIF_Code of 8 (Agent is asleep) or 7 (your ZIS sent a duplicate SIF_MsgId). Messaging protocol complete (failure).
7 Messaging protocol has failed due to a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. If the SIF_Error is a Generic Message Handling error, error code "Message not supported," go to Step 8. Otherwise messaging protocol complete (failure).
8 The Agent does not support SIF_CancelServiceInputs. Messaging protocol complete (success).
Table 4.2.1.6-1: SIF_CancelServiceInputs Protocol

4.2.2 ZIS Message Handling Protocols

This section documents how Zone Integration Servers should respond to incoming messages, and the resulting post-conditions upon success or failure, along with any necessary steps to take.

Note that in handling any SIF_Message, the ZIS can return a SIF_Ack with SIF_Status/SIF_Code 8 (receiver is sleeping) or 7 (already have this SIF_MsgId from you) if a duplicate message is detected. These responses are omitted from the handling protocols below.

4.2.2.1 SIF_Message

When a message is received, the ZIS should first validate the XML message. If the message is not SIF_Register, the ZIS should determine whether the sender is registered in the zone. If errors are found, a SIF_Ack with a SIF_Error element should be returned to the caller and no further processing should occur. If no errors are found, message processing proceeds according to message type. Subsequent message processing sections are assured of receiving well-formed and/or valid XML, and all non-SIF_Register message processing sections are assured that the agent is indeed registered with the zone.

Step Process Flow Control
1 Validate incoming XML message. Message validation is optional. The Version attribute of SIF_Message can be used to indicate the appropriate message definition. If not performing message validation, go to Step 3 if XML is well-formed. If performing message validation, go to Step 3 if message is well-formed and valid.
2 Prepare a SIF_Ack containing a SIF_Error element. (Note that if XML is not well-formed, or invalid and the well-formed XML is not made available by the XML parser, SIF_SourceId and SIF_MsgId will not be available from the incoming XML message. If this is the case, include SIF_OriginalSourceId and SIF_OriginalMsgId in the SIF_Ack as empty elements with xsi:nil set to true as necessary to indicate the current message.) Set SIF_Error/SIF_Category to indicate XML Validation and place the appropriate error code and description in SIF_Error/SIF_Code and SIF_Error/SIF_Desc. Place any additional parser information into SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to caller. If it can be determined the message is a SIF_Response, see SIF_Response Handling below, Step 13, to send an error SIF_Response to the requester. Stop processing this message.
3 Examine the Version attribute of the message. If the version is supported, go to Step 5.
4 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to Generic Message Handling, indicating that the message is not supported in SIF_Error/SIF_Code and SIF_Error/SIF_Desc. Return the SIF_Ack to the caller. If this message is a SIF_Response, see SIF_Response Handling below, Step 13, to send an error SIF_Response to the requester. Stop processing this message.
5 Examine message's SIF_Header to retrieve the SIF_SourceId and the message to get the message type. If message type is not SIF_Register, determine if the sender identified by SIF_SourceId is registered. If message type is SIF_Register or if the sender's SIF_SourceId is registered, go to Step 9.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to Access and Permissions, indicating that the sender is not registered in SIF_Error/SIF_Code and SIF_Error/SIF_Desc. Return the SIF_Ack to the caller. If this message is a SIF_Response, see SIF_Response Handling below, Step 13, to send an error SIF_Response to the requester. Stop processing the message.
7 Is the agent issuing the notification a provider of the corresponding service? If yes, go to Step 9.
8 Prepare a SIF_Ack/SIF_Error category 14 (SIF Zone Service) code 17 (Not a provider for this service) and send it to the agent improperly issuing the event.
9 Forward message to the proper handler based on the message type.
Table 4.2.2.1-1: SIF_Message Handling

4.2.2.2 SIF_Register

Before an agent can participate in a zone, it must register itself in order to provide the data that the ZIS needs to interact with the agent. This process is handled using a SIF_Register message.

Step Process Flow Control
1 If ZIS implementation limits SIF_SourceId values in some way, examine SIF_SourceId and determine whether it is valid. If implementation allows any SIF_SourceId or if the SIF_SourceId is valid, go to Step 3.
2 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Registration and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that SIF_SourceId is invalid. Return the SIF_Ack to the caller. Stop processing this message.
3 If ZIS implementation requires previous permissions to register, examine SIF_SourceId and determine whether sender is permitted to register. If implementation allows any sender to register or if sender is permitted to register, go to Step 5.
4 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Access and Permissions and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the lack of permission to register. Return the SIF_Ack to the caller. Stop processing this message.
5 Examine SIF_Version element(s) and determine if the ZIS can handle the version(s). Go to Step 7 if the ZIS can handle the SIF version(s) specified by agent.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Registration and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the ZIS cannot handle SIF messages in a version requested. Place the unsupported version in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing this message.
7 Examine SIF_MaxBufferSize and verify that it is greater than or equal to the minimum value for the ZIS. Go to Step 9 if SIF_MaxBufferSize is large enough.
8 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Registration and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_MaxBufferSize is too small to be supported by the ZIS. Return the SIF_Ack to the caller Stop processing this message.
9 If the supplied value of SIF_Mode is Push, verify that the SIF_Protocol element is provided and that the protocol information appears sufficient for contacting the agent in Push mode and that the ZIS supports the Accept-Encoding SIF_Protocol/SIF_Property, if specified. Go to Step 11 if SIF_Mode is Pull or SIF_Protocol information appears valid.
10 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Registration and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the protocol is not supported, a secure transport is required, or that the ZIS does not support the supplied Accept-Encoding value. Return the SIF_Ack to the caller. Stop processing this message.
11 Store data from the SIF_Register message into the agent's database profile.
12 Prepare a SIF_Ack containing a SIF_Status element indicating success, placing the agent's access control permissions in SIF_Status/SIF_Data/SIF_AgentACL. Return the SIF_Ack to the caller. Stop processing this message.
Table 4.2.2.2-1: SIF_Register Handling

An agent may also send the SIF_Register message when already registered. In this case, the ZIS should re-register the agent in the same manner as defined for initial registration. Any existing provision and subscription entries, as well as any pending messages, maintained by the ZIS for the agent should remain intact. Upon successful re-registration, any new or updated registration settings for the agent, including push mode protocol information, take effect after the ZIS has returned a successful SIF_Ack for the SIF_Register message.

4.2.2.3 SIF_Unregister

When an agent is going be removed from a Zone, the agent must send a SIF_Unregister message. When a ZIS receives this message from an agent, it performs those steps—ignoring SIF_Ack preparation and delivery—outlined for the SIF_Unprovide and SIF_Unsubscribe messages for any agent provisions or subscriptions, respectively. The ZIS then discards any messages pending for the agent. The ZIS will also remove any registration information and remove the agent from its list of registered agents.

It is RECOMMENDED that the ZIS not remove access control data from its database as a replacement agent may be installed. Keeping the access permissions is optional, however.

Step Process Flow Control
1 Examine message and retrieve the SIF_SourceId of the message. The ZIS must remove the agent from its list of registered agents. Perform SIF_Unprovide functionality for any objects the agent is providing. Perform SIF_Unsubscribe functionality for any objects to which the agent is subscribed. Discard any pending messages for the agent.
2 Prepare a SIF_Ack containing a SIF_Status element indicating success. Return the SIF_Ack to caller. Stop processing the message.
Table 4.2.2.3-1: SIF_Unregister Handling

4.2.2.4 SIF_Provide

An agent makes an object available to be requested by a process called Provision that is represented by the SIF_Provide message.

The SIF_Provide message can contain provision requests for multiple objects. The ZIS must treat all of the objects as a set; if there is an error with one of the objects then there should be no change to the Providers database.

Step Process Flow Control
1 Prepare a SIF_Ack. Go to Step 3.
2 Examine the message to determine whether any more objects are being provided. Go to Step 11 if there are no further object provisions to process for this message.
3 Retrieve the name of the next object to be provided. If not otherwise performed in initial message validation, check whether the object name is valid (e.g. valid/supported object, not SIF_ZoneStatus). If object name is valid, go to Step 5.
4 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Provision and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the object is invalid. Place the name of the invalid object in SIF_Error/SIF_ExtendedDesc. Go to Step 14.
5 If no SIF_Context is specified, the context is SIF_Default. Otherwise check that each SIF_Context supplied in SIF_Contexts is supported. If they are all supported, go to Step 7.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Generic Message Handling. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate a context is not supported. Place the name of the context in SIF_Error/SIF_ExtendedDesc. Go to Step 14.
7 Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this object in each of the specified contexts. If sender has the proper access and permissions, go to Step 9.
8 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Access and Permissions. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the sender lacks permission to provide this object. Place the name of the object in SIF_Error/SIF_ExtendedDesc. Go to Step 14.
9 Check the Providers database to see if this object has already been provided in the contexts specified. If the object does not have a provider in the contexts specified, go to Step 11.
10 Is the current provider the same as the SIF_SourceId of this message? If the provider differs from the SIF_SourceId of this message, go to Step 14. Otherwise go to Step 2.
11 Add a record in the Providers database to indicate that SIF_SourceId is the provider of this object in the given contexts. If an error occurs, add a SIF_Error element to the SIF_Ack. If an error occurs, go to Step 13; otherwise go to Step 2.
12 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Provision and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the object already has a provider. Place the name of the provider in SIF_Error/SIF_ExtendedDesc. Go to Step 14.
13 Add a SIF_Status element indicating success to the SIF_Ack. Return the SIF_Ack to the caller. Stop processing the message.
14 Undo all changes to the Providers database. Return the SIF_Ack to the caller. Stop processing the message.
Table 4.2.2.4-1: SIF_Provide Handling

4.2.2.5 SIF_Unprovide

If an agent wishes to withdraw an object previously provided, the SIF_Unprovide message is used.

The SIF_Unprovide message can contain multiple objects. The ZIS must treat all of the objects as a set; if there is an error with one of the objects then there should be no change to the Providers database.

Step Process Flow Control
1 Prepare a SIF_Ack. Go to Step 3.
2 Examine the message to determine whether any more objects are being unprovided. Go to Step 7 if there are no further objects to process for this message.
3 Examine the message and retrieve the name of an object to be unprovided. If not otherwise performed in initial message validation, check whether the object name is valid (e.g. valid/supported object, not SIF_ZoneStatus). Go to Step 5 if the object name is valid.
4 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Provision and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the object is invalid. Place the name of the invalid object in SIF_Error/SIF_ExtendedDesc. Go to Step 10.
5 If no SIF_Context is specified, the context is SIF_Default. Otherwise check that each SIF_Context supplied in SIF_Contexts is supported. If they are all supported, go to Step 7.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Generic Message Handling. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate a context is not supported. Place the name of the context in SIF_Error/SIF_ExtendedDesc. Go to Step 10.
7 If it exists, remove the records in the Providers database that marks SIF_SourceId as the provider of this object for the given contexts. If an error occurs, add a SIF_Error element to the SIF_Ack. If an error occurs, go to Step 10.
8 Leave all pending SIF_Requests for the object in the responder's queue, as they may include SIF_Requests routed explicitly to the responder using SIF_DestinationId. Go to Step 2.
9 Add a SIF_Status element indicating success to the SIF_Ack. Return the SIF_Ack to the caller Stop processing the message.
10 Undo all changes to the Providers database. Return the SIF_Ack to the caller. Stop processing the message.
Table 4.2.2.5-1: SIF_Unprovide Handling

4.2.2.6 SIF_Subscribe

An agent requests to receive SIF_Events for an object by a process called Subscription that is represented by the SIF_Subscribe message.

The SIF_Subscribe message can contain subscription requests for multiple objects. The ZIS must treat all of the objects as a set, if there is an error with one of the objects then there should be no change to the Subscribers database.

Step Process Flow Control
1 Prepare a SIF_Ack. Go to Step 3.
2 Examine the message to determine whether any more subscriptions need to be processed. Go to Step 9 if there are no further subscriptions to process in this message.
3 Retrieve the name of the next object to be subscribed to. If not otherwise performed in initial message validation, check whether the object name is valid (e.g., valid/supported object with events reported). If the object name is valid, go to Step 5.
4 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Subscription and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the object is invalid. Place the name of the invalid object in SIF_Error/SIF_ExtendedDesc. Go to Step 12.
5 If no SIF_Context is specified, the context is SIF_Default. Otherwise check that each SIF_Context supplied in SIF_Contexts is supported. If they are all supported, go to Step 7.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Generic Message Handling. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate a context is not supported. Place the name of the context in SIF_Error/SIF_ExtendedDesc. Go to Step 12.
7 Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this object and contexts. If sender has the proper access and permissions, go to Step 9.
8 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Access and Permissions. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the sender lacks permission to subscribe to this object. Place the name of the object in SIF_Error/SIF_ExtendedDesc. Go to Step 12.
9 Check the Subscribers database to see if the caller is already subscribed to this object for the specified contexts. If the caller is already subscribed to this object, go to Step 2.
10 Add a record in the Subscribers database to indicate that SIF_SourceId is a subscriber of this object's SIF_Events in the specified contexts. If an error occurs, add a SIF_Error element to the SIF_Ack. If an error occurs go to Step 12; otherwise go to Step 2.
11 Add a SIF_Status element indicating success to the SIF_Ack. Return the SIF_Ack to the caller. Stop processing the message.
12 Undo all changes to the Subscribers database. Return the SIF_Ack to the caller. Stop processing the message.
Table 4.2.2.6-1: SIF_Subscribe Handling

4.2.2.7 SIF_Unsubscribe

If an agent wishes to cancel one or more subscriptions, the SIF_Unsubscribe message is used. Events already queued for delivery prior to unsubscription will be delivered.

The SIF_Unsubscribe message can contain subscription requests for multiple objects. The ZIS must treat all of the objects as a set, if there is an error with one of the objects then there should be no change to the Subscribers database.

Step Process Flow Control
1 Prepare a SIF_Ack. Go to Step 3.
2 Examine the message to determine whether any more unsubscriptions need to be processed. Go to Step 6 if there are no further objects to process in the message.
3 Retrieve the name of the next object. If not otherwise performed in initial message validation, check whether the object name is valid (e.g. valid/supported object with events reported). If the object name is valid, go to Step 5.
4 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Subscription and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the object is invalid. Place the name of the invalid object in SIF_Error/SIF_ExtendedDesc. Go to Step 9.
5 If no SIF_Context is specified, the context is SIF_Default. Otherwise check that each SIF_Context supplied in SIF_Contexts is supported. If they are all supported, go to Step 7.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Generic Message Handling. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate a context is not supported. Place the name of the context in SIF_Error/SIF_ExtendedDesc. Go to Step 12.
7 If it exists, remove the record in the Subscribers database that marks SIF_SourceId as a subscriber of this object's SIF_Events in the specified contexts. If an error occurs, add a SIF_Error element to the SIF_Ack. If an error occurs go to Step 9, otherwise go to Step 2.
8 Add a SIF_Status element indicating success to the SIF_Ack. Return the SIF_Ack to the caller. Stop processing the message.
9 Undo all changes to the Subscribers database. Return the SIF_Ack to the caller. Stop processing the message.
Table 4.2.2.7-1: SIF_Unsubscribe Handling

4.2.2.8 SIF_Provision

An Agent is registering its support for various messages with regard to various objects. Settings supplied replace any previously recorded settings for the Agent.

Step Process Flow Control
1 Prepare SIF_Ack.  
2 Process SIF_ProvideObjects as provide. On error go to step 13.
3 Process objects not in SIF_ProvideObjects as unprovide. On error go to step 13.
4 Process SIF_SubscribeObjects as subscribe. On error go to step 13.
5 Process objects not in SIF_SubscribeObjects as unsubscribe. On error go to step 13.
6 Process SIF_PublishAddObjects. On error go to step 13.
7 Process SIF_PublishChangeObjects. On error go to step 13.
8 Process SIF_PublishDeleteObjects. On error go to step 13.
9 Process SIF_RequestObjects. On error go to step 13.
10 Process SIF_RespondObjects. On error go to step 13.
11 Save changes.  
12 Return success SIF_Ack. Stop processing.
13 Roll back any changes.  
14 Return error SIF_Ack. Stop processing.
Table 4.2.2.8-1: SIF_Provision Handling

4.2.2.9 SIF_Event

When an application has made a change in an object that is part of the Zone and for which the application has declared the ability to generate SIF_Events, the agent will send a SIF_Event message to its Zone Integration Server so the framework may distribute it.

Step Process Flow Control
1 Examine message and retrieve the name of the object. Check whether the object name is valid (e.g. valid/supported object with events reported). If object name is valid, go to Step 3.
2 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Event Reporting and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the event is invalid. Place the name of the invalid object in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
3 If no SIF_Context is specified, the context is SIF_Default. Otherwise check that each SIF_Context supplied in SIF_Contexts is supported. If they are all supported, go to Step 5.
4 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Generic Message Handling. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate a context is not supported. Place the name of the context in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
5 Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this object in the specified contexts. If sender has the proper access and permissions, go to Step 7.
6 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Access and Permissions. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the sender lacks permission to publish events pertaining to this object (use general SIF_Event error code, or specific Add, Change, Delete codes). Place the name of the object in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
7 Check the Subscriber database to see if there are any subscribers in the specified contexts for the SIF_Event. Go to Step 9 if there are no subscribers for this object.
8 For each subscriber make a copy of the SIF_Event. If the ZIS supports XML filtering pass the copy to the XML filter logic. If an XML filter matched the root SIF_Message do not put the copy into the subscriber's queue and continue to the next subscriber. With the copy if more than one context is specified for the event, only one copy of the event is placed in the subscribing agent's queue. If the event cannot be placed into an individual agent's queue due to the agent's maximum buffer size or because the subscribing agent does not support the message version of the SIF_Event, it is RECOMMENDED that the ZIS log the inability to deliver the event. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the original message. SIF_LogEntry/SIF_Desc must contain the SourceId of the agent that has failed to receive the message.
9 Prepare a SIF_Ack containing a SIF_Status element indicating success. Return a SIF_Ack to the caller. Stop processing the message.
Table 4.2.2.9-1: SIF_Event Handling

4.2.2.10 SIF_Request

When an agent needs information from a Zone context it sends a SIF_Request message to the ZIS. If the SIF_Request's header does not contain a SIF_DestinationId element, the ZIS will route the message to the Provider of the object referenced in the SIF_Request. If the header contains a SIF_DestinationId, the ZIS will route the message to the application referenced in the SIF_DestinationId if the security policies of the zone permit such routing. The ZIS will return a SIF_Ack message to the requesting agent to indicate whether or not it was able to process the SIF_Request message.

After the ZIS returns a success SIF_Ack to the requester, the ZIS will route the SIF_Request to the responder and the requesting agent may expect to receive one or more SIF_Response messages sent by the responder. However, the responder may not be currently on-line or it may not be able to immediately satisfy the SIF_Request. Therefore, requesting agents must not depend upon a timely response to their SIF_Request.

If the ZIS returns an error SIF_Ack, the requesting agent will not receive any SIF_Response messages from a responder.

Step Process Flow Control
1 Prepare a SIF_Ack.
2 Retrieve the name of the object from the ObjectName attribute of SIF_Query/SIF_QueryObject and check whether it's a valid/supported object. Go to Step 4 if the object name is valid.
3 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Request and Response and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the object name is invalid. Place the name of the invalid object in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
4 If no SIF_Context is specified, the context is SIF_Default. Otherwise check that the context supplied in SIF_Contexts is supported. If more than one context is specified, go to Step 5. If the context is supported, go to Step 6.
5 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Generic Message Handling. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate a specified context is not supported or that multiple contexts are not supported, depending on the error. Place the name of the context in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
6 Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this object in the applicable context. If sender has the proper access and permissions, go to Step 8.
7 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Access and Permissions. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the sender lacks permission to request this object. Place the name of the object in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
8 Examine the SIF_Request header looking for a SIF_DestinationId Go to Step 11 if a SIF_DestinationId was located.
9 No SIF_DestinationId was found. Examine the Providers database to locate the responder for the requested object in the applicable context. Go to Step 12 if a Provider was located.
10 Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that no provider was found. Return the SIF_Ack to the caller. Stop processing the message.
11 A SIF_DestinationId was specified indicating the responder. Confirm that the agent specified in SIF_DestinationId has permission to send SIF_Response messages for the requested data object in the applicable context. Go to Step 10 if the agent does not have the necessary permission.
12 If it can be determined from ACL settings or settings recorded by SIF_Provision and/or SIF_Provide that the Responder cannot handle a SIF_Query for a given object or SIF_ExtendedQuery for any referenced object, or that the Responder doesn't handle extended queries in general, add a SIF_Error element with the applicable SIF_Error/SIF_Category and SIF_Error/SIF_Code (object not supported, query not supported, or SIF_ExtendedQuery not supported). Place an appropriate error message in SIF_Desc and/or SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
13 If the ZIS supports SIF XML filter pass apply the SIF XML filter logic to the SIF_Request. If a rule applied to the root element SIF_Message then Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that the SIF_Request was canceled due to a SIF XML filter rule. Return the SIF_Ack to the caller. Stop processing the message if an error SIF_Ack was returned.
14 Deposit the SIF_Request in the responder's queue. If the request cannot be placed into an individual agent's queue due to the agent's maximum buffer size or because the destination agent does not support the message version of the SIF_Request, it is RECOMMENDED that the ZIS log the inability to deliver the request. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from this message. SIF_LogEntry/SIF_Desc MUST contain the SourceId of the agent that has failed to receive the request.
15 Return a SIF_Ack, with SIF_Status set to 0, to the caller to indicate that SIF_Request has been sent. Stop processing the message.
Table 4.2.2.10-1: SIF_Request Handling

4.2.2.11 SIF_Response

When receiving a SIF_Response packet from an agent responding to a SIF_Request, the ZIS MUST perform the validation protocol below.

Step Process Flow Control
1 Prepare a SIF_Ack.
2 Using the supplied SIF_RequestMsgId, look up the SIF_Request that initiated this response. Go to Step 4 if the SIF_Request is found.
3 Add a SIF_Error element to the SIF_Ack. Set SIF_Error/SIF_Category to indicate Request and Response and set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_RequestMsgId is invalid. Place SIF_RequestMsgId in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
4 Examine the SIF_MaxBufferSize specified in the SIF_Request message and compare it to the size of the SIF_Response packet. If the SIF_Response packet is smaller than or equal to the SIF_MaxBufferSize specified in the original request, go to Step 6.
5 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Request and Response. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_MaxBufferSize is incorrect. Place a description of the SIF_MaxBufferSize and the actual size of the message received in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Go to step 14.
6 Examine the SIF_DestinationId specified in the SIF_Response and compare it to the SIF_SourceId of the original request. If the SIF_DestinationId is correct, go to Step 8.
7 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Request and Response. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_DestinationId is incorrect. Place a description of the SIF_DestinationId specified and the SIF_DestinationId expected in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Go to step 14.
8 Examine the SIF_PacketNumber specified in the SIF_Response. If this is the first SIF_Response packet received, the SIF_PacketNumber must be set to a value of 1. Subsequent packets must be received in order with the SIF_PacketNumber set to 1 + the previous SIF_PacketNumber. If the SIF_PacketNumber is correct, go to Step 10.
9 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Request and Response. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_PacketNumber is incorrect. Place a description of the SIF_PacketNumber specified and the SIF_PacketNumber expected in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Go to step 14.
10 Examine the SIF_Version specified in the SIF_Response and compare it to the SIF_Versions allowed in the original request. If the SIF version matches one of the SIF Versions requested in the SIF_Request, go to Step 12.
11 Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Request and Response. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_Version is incorrect. Place a description of the version of the SIF_Response and versions allowed by the SIF_Request in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller. Go to step 14.
12 If the ZIS supports SIF XML filter apply the xml filter rules to the SIF_Response.
13 Place the SIF_Response packet in the requesting agent's queue. Message processing is complete. Stop processing the message.
14

Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate Request and Response and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the reason that the SIF_Response packet was rejected.

Add SIF_PacketNumber with a value set to set to 1 + the previous SIF_PacketNumber and SIF_MorePackets to No.

Send the SIF_Response to the original requester. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the request. SIF_LogEntry/SIF_ExtendedDesc should contain information about why the message failed SIF_Response validation.

Stop processing the message.

The ZIS must also guarantee that no additional SIF_Response packets for this SIF_Request will be accepted. Depending on the implementation, the ZIS may need to alter the SIF_Request cache it maintains to signal that the SIF_Request is no longer valid.

The ZIS may remove the SIF_Request from the cache as the stream is closed.

Table 4.2.2.11-1: SIF_Response Handling

4.2.2.12 SIF_Ping

An Agent is pinging your ZIS to see if it is reachable, "awake" and/or processing messages.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. If your ZIS is "awake," include a SIF_Status element with a SIF_Code of 0 (success). Otherwise you may optionally notify the Agent that your ZIS is asleep by returning a SIF_Code of 8 (receiver is sleeping).  
2 Return the SIF_Ack to the Agent. Message processing complete (success).
Table 4.2.2.12-1: SIF_Ping Handling

4.2.2.13 SIF_Sleep

The Agent wants its state changed to "asleep." Upon successful state change, your ZIS SHOULD avoid sending messages to a Push-Mode Agent until receipt of a SIF_Wakeup message or that Agent re-registers, or be prepared to handle transport errors or the aforementioned acknowledgement. Whether the Agent is registered in Push or Pull mode, this state is communicated to other Agents in SIF_ZoneStatus and MUST be persisted accordingly. In addition to sending a SIF_Wakeup or SIF_Register, a Pull-Mode Agent can also change its state to "awake" by sending a SIF_GetMessage.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 0 (success). Change the state of the Agent to "asleep."  
2 Return the SIF_Ack to the Agent. Message processing complete (success).
Table 4.2.2.13-1: SIF_Sleep Handling

4.2.2.14 SIF_Wakeup

An Agent wants its state changed to "awake," notifying the ZIS and other Agents of the state change. A ZIS MUST persist this state in order to communicate it to other Agents via SIF_ZoneStatus. When a Push-Mode Agent changes its state to "awake," the ZIS may also resume delivery of queued messages to the Agent.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 0 (success). Change the Agent's state to "awake."  
2 Return the SIF_Ack to the Agent. Message processing complete (success).
Table 4.2.2.14-1: SIF_Wakeup Handling

4.2.2.15 SIF_GetZoneStatus

An Agent is requesting the status of the zone.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 0 (success). Reflect the current state of the zone in SIF_Status/SIF_Data/SIF_ZoneStatus.  
2 Return the SIF_Ack to the Agent. Message processing complete (success).
Table 4.2.2.15-1: SIF_GetZoneStatus Handling

4.2.2.16 SIF_GetAgentACL

An Agent is requesting its access control permissions.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 0 (success). Communicate the Agent's ACL permissions in SIF_Status/SIF_Data/SIF_AgentACL.  
2 Return the SIF_Ack to the Agent. Message processing complete (success).
Table 4.2.2.16-1: SIF_GetZoneStatus Handling

4.2.2.17 SIF_CancelRequests

If an Agent abandons or restarts a data collection using SIF_Requests, whether or not the response stream has started, it is RECOMMENDED that it send one or more SIF_CancelRequests messages to the ZIS. Upon receipt of the SIF_CancelRequests message, the ZIS deletes corresponding SIF_Request messages from Agent queues and deletes its own state/tracking information regarding each request. Doing the latter ensures that if a Responder is still processing a request, the ZIS effectively ends the response stream upon receipt of the next SIF_Response packet by returning a SIF_Error with a SIF_Category of 8 (Request and Response Error) and a SIF_Code of 10 (invalid SIF_RequestMsgId specified in SIF_Response). No changes to responding Agent behaviors are required as all agents in the SIF 2.x lifecycle have the capability to handle this error state.

When cancelling SIF_Requests, the ZIS also has the ability to send a SIF_CancelRequests message to Push-Mode Agents. Pull-Mode Responders cannot receive these messages, but any pending response handling is cancelled per the ZIS behavior above. When dealing with Push-Mode Agents, ZIS implementations must bear in mind that support for this message is optional for Push-Mode Agents.

When a cancelling Agent specifies a NotificationType of Standard, it is the responsibility of the ZIS to end the response stream to the requesting Agent by sending a SIF_Response packet with a SIF_MorePackets of No on the Responder's behalf.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 0 (success). Return the SIF_Ack to the Agent. (There are no error return values that apply to this message.) Go to Step 2.
2 For each SIF_RequestMsgId element, perform the following steps. If all SIF_RequestMsgId elements have been processed, processing is complete.
3 Using the supplied SIF_RequestMsgId, look up the SIF_Request that initiated this response. Go to Step 2 if the SIF_Request is not found, or has already been completed with a "final" SIF_Response packet (SIF_MorePackets = No).
4 Examine the SIF_SourceId specified in the SIF_Request message and compare it to the SIF_SourceId in the SIF_SystemControl message. If the SIF_SourceId is not the same, go to Step 2.
5 Close out the SIF_Request tracking state for the request so that no further tracking is performed.  
6 If the responding Agent has already received the request and is running in Push mode, send a SIF_CancelRequests message to that Agent. (Note: This could also be accomplished by packaging up all SIF_RequestMsgIds that apply to the same responding Agent and sending a single SIF_CancelRequests message.)  
7 Examine the value of SIF_NotificationType. If set to Standard, go to Step 8. If set to None, go to Step 10.
8 Prepare a SIF_Response message with SIF_DestinationId set to SIF_SourceId and SIF_RequestMsgId set to SIF_MsgId from the SIF_Request message.  
9

Add a SIF_Error element with the SIF_Category set to indicate Request and Response, with SIF_Code and SIF_Desc indicating 18 (SIF_Request cancelled by requesting agent).

Add SIF_PacketNumber with a value set to the previous SIF_PacketNumber + 1. Set SIF_MorePackets to No.

Place the SIF_Response in the requester's queue.

 
10 Determine if there are any more SIF_RequestMsgId elements left to process. Go to Step 2 if there are more SIF_RequestMsgId elements, otherwise processing is complete.
Table 4.2.2.17-1: SIF_CancelRequests Handling

4.2.2.18 SIF_CancelServiceInputs

If an Agent abandons or restarts a data collection using SIF_ServiceInputs, whether or not the response stream has started, it is RECOMMENDED that it send one or more SIF_CancelServiceInputs messages to the ZIS. Upon receipt of the SIF_CancelServiceInputs message, the ZIS deletes corresponding SIF_ServiceInput messages from Agent queues and deletes its own state/tracking information regarding each request. Doing the latter ensures that if a Responder is still processing a service input, the ZIS effectively ends the response stream upon receipt of the next SIF_ServiceOutput packet by returning a SIF_Error with a SIF_Category of 14 (SIF Zone Service Error) and a SIF_Code of 8 (invalid SIF_ServiceMsgId specified in SIF_ServiceOutput). No changes to responding Agent behaviors are required as all agents in the SIF 2.x lifecycle have the capability to handle this error state.

When cancelling SIF_ServiceInputs, the ZIS also has the ability to send a SIF_CancelServiceInputs message to Push-Mode Agents. Pull-Mode Responders cannot receive these messages, but any pending response handling is cancelled per the ZIS behavior above. When dealing with Push-Mode Agents, ZIS implementations must bear in mind that support for this message is optional for Push-Mode Agents.

When a cancelling Agent specifies a NotificationType of Standard, it is the responsibility of the ZIS to end the response stream to the requesting Agent by sending a SIF_ServiceOutput packet with a SIF_MorePackets of No on the Responder's behalf.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. Include a SIF_Status element with a SIF_Code of 0 (success). Return the SIF_Ack to the Agent. (There are no error return values that apply to this message.) Go to Step 2.
2 For each SIF_ServiceMsgId element, perform the following steps. If all SIF_ServiceMsgId elements have been processed, processing is complete.
3 Using the supplied SIF_ServiceMsgId, look up the SIF_ServiceInput that initiated this response. Go to Step 2 if the SIF_ServiceInput is not found, or has already been completed with a "final" SIF_ServiceOutput packet (SIF_MorePackets = No).
4 Examine the SIF_SourceId specified in the SIF_ServiceInput message and compare it to the SIF_SourceId in the SIF_SystemControl message. If the SIF_SourceId is not the same, go to Step 2.
5 Close out the SIF_ServiceInput tracking state for the request so that no further tracking is performed.  
6 If the responding Agent has already received the request and is running in Push mode, send a SIF_CancelServiceInputs message to that Agent. (Note: This could also be accomplished by packaging up all SIF_ServiceMsgIds that apply to the same responding Agent and sending a single SIF_CancelServiceInputs message.)  
7 Examine the value of SIF_NotificationType. If set to Standard, go to Step 8. If set to None, go to Step 10.
8 Prepare a SIF_ServiceOutput message with SIF_DestinationId set to SIF_SourceId and SIF_ServiceMsgId set to SIF_ServiceMsgId from the SIF_ServiceInput message.  
9

Add a SIF_Error element with the SIF_Category set to indicate SIF Zone Service, with SIF_Code and SIF_Desc indicating 15 (SIF_ServiceInput cancelled by requesting agent).

Add SIF_PacketNumber with a value set to the previous SIF_PacketNumber + 1. Set SIF_MorePackets to No.

Place the SIF_ServiceOutput in the requester's queue.

 
10 Determine if there are any more SIF_ServiceMsgId elements left to process. Go to Step 2 if there are more SIF_ServiceMsgId elements, otherwise processing is complete.
Table 4.2.2.18-1: SIF_CancelRequests Handling

4.2.2.19 SIF_GetMessage

A Pull-Mode Agent is requesting the next message in its queue.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply. Place the incoming SIF_Header/SIF_SourceId and SIF_Header/SIF_MsgId in SIF_OriginalSourceId and SIF_OriginalMsgId, respectively. If the Agent sending SIF_GetMessage is registered as a Pull-Mode Agent, go to step 3.  
2 The Agent is a Push-Mode Agent and is not allowed to send SIF_GetMessage. Include a SIF_Error/SIF_Category of 5 (Registration) and a SIF_Error/SIF_Code of 9 (Agent is registered in Push mode). Populate SIF_Desc and optionally SIF_ExtendedDesc as desired. Return the SIF_Ack to the Agent. Message processing complete.
3 If the recorded state of the Pull-Mode Agent is "asleep," change that state to "awake." Is there a message available in the Agent's message queue, subject to Selective Message Blocking? If yes, go to step 5.  
4 There is no message currently available for the Agent. Include a SIF_Status/SIF_Code of 9 (no messages available). Return the SIF_Ack to the Agent. Message processing complete.
5 The next available message in the Agent's queue, subject to Selective Message Blocking, can be delivered (it will be removed from the queue later per successful handling of a SIF_Ack from the Pull-Mode Agent). If SIF_Security is specified on the message and the connection from the Pull-Mode Agent does not meet the specified minimum encryption and/or authentication levels, or if the connection does not meet minimum encryption/authentication levels in the Zone, remove the message from the Agent's queue and return an appropriate SIF_Error. Otherwise include a SIF_Status/SIF_Code of 0 (success) and place the message in SIF_Status/SIF_Data. Message processing complete.
Table 4.2.2.19-1: SIF_GetMessage Handling

4.2.2.20 SIF_Ack (from a Push-Mode Agent)

A Push-Mode Agent is sending a final SIF_Ack to end Selective Message Blocking (SMB).

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply.  
2 Is SIF_Status/SIF_Code 3 (final SIF_Ack)? If yes, go to Step 4.
3

The Agent has violated protocol. End SMB if it has been invoked by the Agent and remove the blocked SIF_Event from the Agent's queue. Indicate SIF_Error/SIF_Category of 13 (SMB Error) and SIF_Error/SIF_Code  3 (final SIF_Ack expected).

It is RECOMMENDED that your ZIS log the error. Your ZIS MAY post a SIF_LogEntry  Add event with the same error category and code above, containing a copy of the SIF_Header of the message.

Return the SIF_Ack to the Agent. Message handling complete (error).
4 Does SIF_OriginalMsgId match the SIF_MsgId for the SIF_Event that was blocked in SMB, if any? If yes, go to Step 6.
5

The Agent has violated protocol. As there can be only one event blocked by SMB, end SMB for the agent and remove the blocked SIF_Event from the Agent's queue, if any. Indicate SIF_Error/SIF_Category of 13 (SMB Error) and SIF_Error/SIF_Code  4 (incorrect SIF_MsgId in final SIF_Ack).

It is RECOMMENDED that your ZIS log the error. Your ZIS MAY post a SIF_LogEntry  Add event with the same error category and code above, containing a copy of the SIF_Header of the message.

Return the SIF_Ack to the Agent. Message handling complete (error).
6 SMB has been ended by the Agent. Removed the blocked SIF_Event from the Agent's queue. Place 0 in SIF_Status/SIF_Code. Return the SIF_Ack to the Agent. Message handling complete (success).
Table 4.2.2.20-1: SIF_Ack Handling

4.2.2.21 SIF_Ack (from a Pull-Mode Agent)

A Pull-Mode Agent is acknowledging a message it has retrieved using SIF_GetMessage. This typically leads to the message in question being removed from the Agent's queue. The Agent may also invoke Selective Message Blocking when acknowledging an event, blocking delivery of subsequent SIF_Events until Selective Message Blocking is ended by the Agent.

Step Process Flow Control
1 Prepare a SIF_Ack message with SIF_Header containing a new GUID in SIF_MsgId, your Zone Id in SIF_SourceId and the current time in SIF_Timestamp; other SIF_Header elements do not apply.  
2 Is SIF_Error present? If yes, go to Step 14.
3 Is SIF_Status/SIF_Code 1 (immediate SIF_Ack)? If no, go to Step 5.
4 If no message matches SIF_OriginalMsgId, set SIF_Error/SIF_Category to 12 (Generic Message Handling) and SIF_Error/SIF_Code to 6 (no such message). Otherwise remove the identified message from the Agent's queue and set SIF_Status/SIF_Code to 0. Return SIF_Ack. Message handling complete.
5 Is SIF_Status/SIF_Code 2 (intermediate SIF_Ack)? If no, go to Step 7.
6 If no message matches SIF_OriginalMsgId, set SIF_Error/SIF_Category to 12 (Generic Message Handling) and SIF_Error/SIF_Code to 6 (no such message). If the message identified is not a SIF_Event, set SIF_Category to 13 (SMB Error) and SIF_Code to 2 (SMB can only be invoked on a SIF_Event). Otherwise invoke SMB on the identified SIF_Event, persisting SIF_OriginalMsgId, and set SIF_Status/SIF_Code to 0. This event is blocked and all SIF_Events are frozen. Return SIF_Ack. Message handling complete.
7 Is SIF_Status/SIF_Code 3 (final SIF_Ack)? If no, go to Step 9.
8 If SMB has not been invoked or the message identified by SIF_OriginalMsgId doesn't exist or doesn't match the SIF_Event blocked by SMB, set SIF_Error/SIF_Category to 13 (SMB Error) and SIF_Error/SIF_Code to 4 (incorrect SIF_MsgId in final SIF_Ack). (In the case of SMB having been invoked but the message not matching, end SMB, remove the message blocked by SMB from the Agent's queue and unfreeze delivery of events.) Otherwise end SMB, remove the identified message from the Agent's queue and unfreeze delivery of events. Set SIF_Status/SIF_Code to 0. Return SIF_Ack. Message handling complete.
9 Is SIF_Status/SIF_Code 7 (already have this SIF_MsgId from you)? If no, go to Step 11.
10 The ZIS cannot correct this, as the SIF_MsgId originates from an Agent and can't be changed without other repercussions. Remove the message from the Agent's queue. Set SIF_Status/SIF_Code to 0. Return SIF_Ack. Message handling complete.
11 Is SIF_Status/SIF_Code 8 (receiver is sleeping)? If no, go to Step 13.
12 The Agent is stating it cannot process the message at this time; leave it as the next message to be delivered. Set SIF_Status/SIF_Code to 0. Return SIF_Ack. Message handling complete.
13

The Agent has violated protocol. Indicate SIF_Error/SIF_Category of 12 (Generic Message Handling Error) and SIF_Error/SIF_Code 5 (protocol error) for the message.

Return SIF_Ack. Message handling complete.
14 The Agent has indicated a SIF_Error condition. See Error Codes with SIF_Category and SIF_Code, and examine SIF_Desc and SIF_ExtendedDesc, if included. If SIF_Category does not indicate a transport error, remove the message from the Agent's queue. Otherwise it remains the next message to be delivered. Set SIF_Status/SIF_Code to 0. Return SIF_Ack. Message handling complete.
Table 4.2.2.21-1: SIF_Ack Handling

4.2.2.22 SIF_ServiceNotify

The design of SIF Zone Services allows a service definition to be defined as containing notification events that can be sent to the zone. When an application wishes to notify the zone that something has happened, it does so by sending a SIF_ServiceNotify to the ZIS.

Step Process Flow Control
1

Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this service and operation in the specified context.

If sender has the proper access and permissions, go to step 3.

2

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate SIF Zone Service. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate ACL permission denied. Return the SIF_Ack to the caller.

Stop processing message.

3

Using the SIF_SourceId, consult the SIF_ZoneStatus to determine if the sender is a service provider.

If sender is a service provider go to step 5

4

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate Access and Permission Error. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the Agent has no permission to provide the service. Return the SIF_Ack to the caller.

Stop processing message.

5 Get SIF_ServiceMsgId value.
Get SIF_PacketNumber value.
Get SIF_MorePackets value.

Use the SIF_ServiceMsgId to look up any previous state information in the packet tracking cache. Use the information retrieved and the information obtained from the SIF_Message/SIF_ServiceNotify to determine if the packet sequence for the SIF_PacketNumber is correct. The SIF_MorePackets is used to determine if this is the terminating packet.

If the SIF_PacketNumber is correct go to step 7

6

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate SIF Zone Service. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_PacketNumber is incorrect. Place a description of the SIF_PacketNumber specified and the SIF_PacketNumber expected in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller.

If the packet stream has not been terminated by the ZIS go to step 10.

7

Check the Subscriber database to see if there are any subscribers in the specified contexts for the specific SIF_Service and SIF_Operation from the SIF_ServiceNotify. The identification of a subscriber is based upon the service name and operation name.

Go to Step 9 if there are no subscribers for this notification event.

8

Place a copy of the SIF_ServiceNotify message into each subscribing agent's queue. If more than one context is specified for the event, only one copy of the event is placed in the subscribing agent's queue. If the SIF_ServiceNotify cannot be placed into an individual agent's queue due to the agent's maximum buffer size or because the subscribing agent does not support the message version of the SIF_ServiceNotify, it is RECOMMENDED that the ZIS log the inability to deliver the event. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the original message. SIF_LogEntry/SIF_Desc must contain the SourceId of the agent that has failed to receive the message.

9

Prepare a SIF_Ack containing a SIF_Status element indicating success. Return a SIF_Ack to the caller.

Stop processing the message.

10

Prepare a SIF_ServiceNotify message with a copy of the information in the original SIF_ServiceNotify except for the SIF_Body.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate SIF Zone Service and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the reason that the SIF_ServiceNotify packet was rejected.

Add SIF_PacketNumber with a value set to set to 1 + the previous SIF_PacketNumber and SIF_MorePackets to No.

Send the SIF_ServiceNotify to the subscribers. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the request. SIF_LogEntry/SIF_ExtendedDesc should contain information about why the message failed SIF_ServiceNotify validation.

Stop processing the message.

The ZIS must also guarantee that no additional SIF_ServiceNotify packets for this SIF_ServiceMsgId will be accepted. Depending on the implementation, the ZIS may need to alter the SIF_ServiceNotify cache it maintains to signal that the SIF_ServiceNotify/SIF_ServiceMsgId is no longer valid.

The ZIS may remove the SIF_ServiceNotify/SIF_ServiceMsgId from the cache as the stream is closed.

Table 4.2.2.22-1: SIF_ServiceInput Handling

4.2.2.23 SIF_ServiceInput

When an agent wishes to invoke an operation on a SIF Zone Service, it sends a SIF_ServiceInput message to the ZIS. If the SIF_ServiceInput's header does not contain a SIF_DestinationId element, the ZIS will route the message to the Provider of the service referenced in the SIF_ServiceInput. If the header contains a SIF_DestinationId, the ZIS will route the message to the application referenced in the SIF_DestinationId if the security policies of the zone permit such routing. The ZIS will return a SIF_Ack message to the requesting agent to indicate whether or not it was able to process the SIF_ServiceInput message.

After the ZIS returns a success SIF_Ack to the requester, the ZIS will route the SIF_ServiceInput to the responder and the requesting agent may expect to receive one or more SIF_ServiceOutput messages sent by the responder. However, the responder may not be currently on-line or it may not be able to immediately satisfy the SIF_ServiceInput. Therefore, requesting agents must not depend upon a timely response to their SIF_ServiceInput.

If the ZIS returns an error SIF_Ack, the requesting agent will not receive any SIF_ServiceOutput messages from a responder.

Step Process Flow Control
1

Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this service and operation in the specified context.

If sender has the proper access and permissions, go to step 3.

2

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate SIF Zone Service. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate ACL permission denied. Return the SIF_Ack to the caller.

Stop processing message.

3 Get SIF_ServiceMsgId value.
Get SIF_PacketNumber value.
Get SIF_MorePackets value.

Use the SIF_ServiceMsgId to look up any previous state information in the packet tracking cache. Use the information retrieved and the information obtained from the SIF_Message/SIF_ServiceInput to determine if the packet sequence for the SIF_PacketNumber is correct. The SIF_MorePackets is used to determine if this is the terminating packet.

If the SIF_PacketNumber is correct go to step 5

4

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate SIF Zone Service. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the SIF_PacketNumber is invalid. Place a description of the SIF_PacketNumber specified and the SIF_PacketNumber expected in SIF_Error/SIF_ExtendedDesc. Return the SIF_Ack to the caller.

If the packet stream has not been terminated by the ZIS go to step 13.

5 Examine the SIF_ServiceInput header looking for a SIF_DestinationId Go to Step 8 if a SIF_DestinationId was located.
6 No SIF_DestinationId was found. Examine the Providers database to locate the responder for the requested service in the applicable context. Go to Step 8 if a Provider was located.
7 Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate SIF Zone Service and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that no provider was found. Return the SIF_Ack to the caller. Stop processing the message.
8

Examine the SIF_ServiceInput header looking for a SIF_Version.

If the SIF_ServiceOutput does not match any SIF_Version from SIF_ServiceInput: Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate SIF Zone Service and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that a version mismatch occurred. Return the SIF_Ack to the caller

Go to Step 9 if a version match was made.

If a version match is not made, complete the step then stop processing the message.

9 A SIF_DestinationId was specified indicating the responder and version numbers match. Confirm that the agent specified in SIF_DestinationId has permission to send SIF_ServiceOutput messages for the requested data object in the applicable context. Go to Step 11 if the agent has the necessary permission.
10 If it can be determined from ACL settings that the Responder cannot handle a SIF_ServiceInput for the given service operation, add a SIF_Error element with the applicable SIF_Error/SIF_Category and SIF_Error/SIF_Code. Place an "ACL permission denied" error message in SIF_Desc and/or SIF_ExtendedDesc. Return the SIF_Ack to the caller. Stop processing the message.
11 Deposit the SIF_ServiceInput in the responder's queue. If the request cannot be placed into an individual agent's queue due to the agent's maximum buffer size or because the destination agent does not support the message version of the SIF_ServiceInput, it is RECOMMENDED that the ZIS log the inability to deliver the request. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from this message. SIF_LogEntry/SIF_Desc MUST contain the SourceId of the agent that has failed to receive the service request. If the message cannot be put into the agent's queue and the SIF_PacketNumber is greater than 1 go to step 13.
12

Prepare a SIF_Ack containing a SIF_Status element indicating success. Return a SIF_Ack to the caller.

Stop processing the message.

13

Prepare a SIF_ServiceInput message with a copy of the information in the original SIF_ServiceInput except for the SIF_Body.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate SIF Zone Service and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the reason that the SIF_ServiceInput packet was rejected.

Add SIF_PacketNumber with a value set to set to 1 + the previous SIF_PacketNumber and SIF_MorePackets to No.

Send the SIF_ServiceInput to the target agent. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the request. SIF_LogEntry/SIF_ExtendedDesc should contain information about why the message failed SIF_ServiceInput validation.

Stop processing the message.

The ZIS must also guarantee that no additional SIF_ServiceInput packets for this SIF_ServiceMsgId will be accepted. Depending on the implementation, the ZIS may need to alter the SIF_ServiceInput cache it maintains to signal that the SIF_ServiceInput/SIF_ServiceMsgId is no longer valid.

The ZIS may remove the SIF_ServiceInput/SIF_ServiceMsgId from the cache as the stream is closed.

Table 4.2.2.23-1: SIF_ServiceInput Handling

4.2.2.24 SIF_ServiceOutput

When receiving a SIF_ServiceOutput packet from an agent responding to a SIF_ServiceInput, the ZIS MUST perform the validation protocol below.

Step Process Flow Control
1

Using the SIF_SourceId, consult the ACL to determine if the sender has the proper access and permissions for this service and operation in the specified context.

If sender has the proper access and permissions, go to step 3.

2

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate SIF Zone Service. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate ACL permission denied. Return the SIF_Ack to the caller.

Stop processing message.

3 Get SIF_ServiceMsgId value.
Get SIF_PacketNumber value.
Get SIF_MorePackets value.

Use the SIF_ServiceMsgId to look up any previous state information in the packet tracking cache. Use the information retrieved and the information obtained from the SIF_Message/SIF_ServiceInput to determine if the packet sequence for the SIF_PacketNumber is correct. The SIF_MorePackets is used to determine if this is the terminating packet.
The cache should also indicate if there was a SIF_ServiceInput that initiated this SIF_ServiceOutput. Also verify the SIF_ServiceOutput does not exceed the SIF_MaxBufferSize specified in the SIF_ServiceInput. The SIF_Version of the SIF_ServiceOutput MUST be in the range of versions specified in the SIF_ServiceInput.

If the validation is correct go to step 5

4

Prepare a SIF_Ack containing a SIF_Error element. Set SIF_Error/SIF_Category to indicate SIF Zone Service. Set SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate "Packet number invalid, Buffer size exceeded."

If the packet stream has not been terminated by the ZIS go to step 9.

5 Examine the SIF_ServiceInput header looking for a SIF_DestinationId. Verify the SIF_DestinationId matches the SIF_SourceId in the original SIF_ServiceInput. Go to Step 7 if a SIF_DestinationId was located.
6 Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate SIF Zone Service and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate that SIF_DestinationId does not match the SIF_SourceId from SIF_ServiceInput. Return the SIF_Ack to the caller. Stop processing the message.
7 Deposit the SIF_ServiceOutput in the Agent's queue. If the message cannot be placed into an individual agent's queue due to the agent's maximum buffer size or because the destination agent does not support the message version of the SIF_ServiceOutput, it is RECOMMENDED that the ZIS log the inability to deliver the message. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from this message. SIF_LogEntry/SIF_Desc MUST contain the SourceId of the agent that has failed to receive the service request. If the message cannot be put into the agent's queue and the SIF_PacketNumber is greater than 1 go to step 9
8

Prepare a SIF_Ack containing a SIF_Status element indicating success. Return a SIF_Ack to the caller.

Stop processing the message.

9

Prepare a SIF_ServiceOutput message with a copy of the information in the original SIF_ServiceOutput except for the SIF_Body.

Add a SIF_Error element with the SIF_Error/SIF_Category set to indicate SIF Zone Service and SIF_Error/SIF_Code and SIF_Error/SIF_Desc to indicate the reason that the SIF_ServiceOutput packet was rejected.

Add SIF_PacketNumber with a value set to set to 1 + the previous SIF_PacketNumber and SIF_MorePackets to No.

Send the SIF_ServiceOutput to the requesting agent. In addition, the ZIS MUST report a SIF_LogEntry event with the appropriate error category and code, containing a copy of the SIF_Header from the request. SIF_LogEntry/SIF_ExtendedDesc should contain information about why the message failed SIF_ServiceOutput validation.

Stop processing the message.

The ZIS must also guarantee that no additional SIF_ServiceOutput packets for this SIF_ServiceMsgId will be accepted. Depending on the implementation, the ZIS may need to alter the SIF_ServiceOutput cache it maintains to signal that the SIF_ServiceOutput/SIF_ServiceMsgId is no longer valid.

The ZIS may remove the SIF_ServiceOutput/SIF_ServiceMsgId from the cache as the stream is closed.

Table 4.2.2.24-1: SIF_ServiceOutput Handling

Valid XHTML 1.0 Transitional