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.

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.

4.1.1.3 SIF_Provide

4.1.1.4 SIF_Unprovide

4.1.1.5 SIF_Subscribe

4.1.1.6 SIF_Unsubscribe

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.

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.

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.

4.1.1.10 SIF_Ping

4.1.1.11 SIF_Sleep

4.1.1.12 SIF_Wakeup

4.1.1.13 SIF_GetZoneStatus

4.1.1.14 SIF_GetAgentACL

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.

4.1.1.16 SIF_GetMessage (Pull-Mode only)

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.

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).

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.

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.

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.

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.

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.

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.

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.

4.1.2.8 SIF_CancelRequests (Push-Mode only) (optional)

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 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.

4.2.1.2 SIF_Ping (to a Push-mode Agent)

4.2.1.3 SIF_Sleep (to a Push-mode Agent)

4.2.1.4 SIF_Wakeup (to a Push-mode Agent)

4.2.1.5 SIF_CancelRequests (to a Push-mode Agent)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

4.2.2.11.1 Implementation Notes

The ZIS must maintain a reliable list of all open SIF_Requests in order to satisfy the Quality of Service validations that are applied to SIF_Responses above. It is envisioned that once a SIF_Response has been completed, either by receiving the last packet or by failing one of the validations applied below, knowledge of the initiating SIF_Request will no longer need to be maintained by the ZIS. If the responding agent attempts to send any more SIF_Responses for a failed SIF_Request, it will automatically fail at Step 2 and get the error response specified in Step 3. Notification of the failed SIF_Response would have already been sent to the requesting agent.

There remain three cases where a requesting agent will not receive a complete SIF_Response for a request.

1. The responding agent never replies with a SIF_Response.
2. The responding agent starts replying, but never finishes the SIF_Response by sending a SIF_Response with the SIF_MorePackets element set to "No".
3. The responding agent attempts a reply with a SIF_Response but the ZIS is unable to parse the message enough to read the SIF_RequestMsgId. If this case occurs, and the responding agent sends a subsequent SIF_Response that is parseable, it is likely that the requesting agent will be notified of the problem because subsequent SIF_Response packets will not pass the SIF_PacketNumber validation.

Management of the SIF_Request cache that is maintained by the ZIS is left up to the ZIS implementation. The ZIS is required to maintain the SIF_Requests for a reasonable amount of time. If the ZIS eventually removes SIF_Requests that have been cached for a long period of time, that option must be able to be configured by the ZIS administrator.

When an open request cache entry is removed by the administrator or a timeout of the record, the ZIS should publish a SIF_LogEntry and a SIF_Response/SIF_Error indicating the reason it was removed.

4.2.2.12 SIF_Ping

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

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.

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.

4.2.2.15 SIF_GetZoneStatus

An Agent is requesting the status of the zone.

4.2.2.16 SIF_GetAgentACL

An Agent is requesting its access control permissions.

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.

4.2.2.18 SIF_GetMessage

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

4.2.2.19 SIF_Ack (from a Push-Mode Agent)

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

4.2.2.20 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.