5 Infrastructure

Contains one of the SIF message types.

The xmlns attribute specifies the XML namespace for SIF messages. For this version of the specification, the value of this attribute MUST be http://www.sifinfo.org/uk/infrastructure/2.x . This XML namespace value will remain the same until the next major release of SIF (3.0).

Note that one SIF_Message may be contained within another when a ZIS delivers a Pull-Mode Agent's next message in a SIF_Ack response to a SIF_GetMessage from the Pull-Mode Agent. If the default namespace specified for the child SIF_Message is the same as the default namespace of the parent SIF_Message, the xmlns attribute for the child message MAY be omitted.

The version of the SIF Implementation Specification that defines this message's XML structure. For this version of the specification, the value of this attribute is 2.4. This attribute can be used by ZIS and agent implementations to choose schema files to validate the message's XML.

Header information associated with a message.

SIF_MsgId is a globally unique message identifier from the Agent or ZIS that sends out the message.

Timestamp of when the message was sent.

This element allows an originating agent to specify security requirements that the ZIS must ensure upon delivery of the message to recipient agents. SIF_Security is only examined and processed by a ZIS on SIF_Request, SIF_Response and SIF_Event messages. In this version of the specification, SIF_Security is ignored on all other messages; its use on other messages is reserved for future versions of this specification.

The originating agent uses this element to specify security requirements for the channel between the ZIS and any recipient agents at delivery time. The ZIS must ensure these requirements are met for this message when delivered to other agents.

The minimum level of authentication required by the message originator to be considered a secure channel upon message delivery to other agents.

The minimum level of encryption required by the message originator to be considered a secure channel upon message delivery to other agents.

The SIF_SourceId is the ID of the originator of the message. Each source needs to have a zone unique case-sensitive identifier.

This element represents the ID of the recipient of the message and may be present as follows:

SIF_Response messages MUST have this element set to the SIF_SourceId of the originator of the SIF_Request message. The ZIS will use this information to route the SIF_Response to the requesting agent.

SIF_Request messages MAY have this element set to the ID of a specific agent if the requesting agent wishes to direct the SIF_Request to a specific responder. If present, the ZIS will route the SIF_Request to the agent referenced in the element subject to the access control policies in effect for the zone.

This element SHOULD NOT be used in any other SIF Infrastructure messages. If the element is present, it will be ignored by the ZIS.

Contains each SIF Context that applies to the message. If omitted, the applicable context is SIF_Default. SIF_Context is repeatable for SIF_Events, not repeatable for SIF_Request or SIF_Response.

The minimum level of encryption required by the message originator to be considered a secure channel upon message delivery to other agents.

The minimum level of authentication required by the message originator to be considered a secure channel upon message delivery to other agents.

A list of SIF contexts that applies to a message or operation. Typically where used as an optional element, the omission of this element implies the SIF_Default context applies.

The name of a SIF Context that applies to a message or operation.

Contains protocol information regarding a ZIS or Agent.

The type of protocol to use (HTTPS, HTTP or an implementation-defined protocol).

Whether the protocol provides a secure channel.

This element is required if the protocol is HTTPS or HTTP. It contains the https or http URL for contacting the agent.

May contain zero or more SIF_Property elements containing SIF_Name/SIF_Value pairs describing any protocol settings required to ensure proper communication.

Property name.

Property value.

This element is used to signal a successful response.

An optional textual description/equivalent of SIF_Code.

Optional element to hold data related to a successful operation. This data is currently limited to a SIF_Message returned by the ZIS in response to a Pull-Mode Agent's SIF_GetMessage, SIF_AgentACL returned by the ZIS in response to SIF_Register and SIF_GetAgentACL, and SIF_ZoneStatus returned by the ZIS in response to SIF_GetZoneStatus.

This element is used to signal an unsuccessful response.

See Error Codes.

A simple, easy to understand, description of the error. The primary consumer of this message is the application user. Example: "Unable to open database."

An optional error description that is more complete and technical in nature. It is to be used as a diagnostic message in trouble-shooting procedures. Example: "The 'Students' table is opened in exclusive mode by user 'ADM1' (dbm.cpp, line 300)."

This is the object that is being queried for.

The actual name of the object that is being queried for.

Individual elements/attributes being requested of matching object. See SIF_Element Syntax below. If specified, only the elements/attributes requested are returned in the SIF_Response (with any parent elements/attributes); otherwise, all elements supported by the provider's object are returned.

Note that this is a means to filter or select a subset of elements/attributes from a matching object; specifying elements/attributes here that do not occur in or are not supported in a matching object does not exclude that matching object from being returned. Include any existing parent elements/attributes of the elements/attributes that are requested but not present.

Either SIF_ConditionGroup or SIF_Example may optionally be specified to present conditions matching objects should satisfy.

SIF_ConditionGroup represents the conditions that the queried object(s) must meet. If conditions are specified, only those objects that meet the conditions are returned; otherwise, all objects of the specified name are returned.

The Boolean operator for joining conditions (SIF_Conditions elements) within this element. Note that None should be used if there is only one SIF_Conditions element.

This construct allows for nested conditions.

The boolean operator for joining conditions (SIF_Condition elements) within this element. Note that None should be used if there is only one SIF_Condition element.

This element represents an individual condition.

This is the element/attribute being queried. See below for syntax.

The comparison operator for the condition.

SIF_Value is the data that is used to compare with the value of the element or attribute.

An example SIF object that serves as a template for matching objects. There is an implied EQ operator for every element/attribute value present and an implied And group of all resulting conditions. Currently this is an experimental feature and limited to use with select objects; wider use may be considered in future versions of this specification.

SIF's default query mechanism for SIF_Request, SIF_Query, has several limitations that limit its usefulness when creating reporting applications that process data from a SIF zone. SIF_Query is limited to matching only one object type per query, requiring applications to manually join together results as needed for reporting and general data processing. SIF_ExtendedQuery is designed to allow for joins on object identifiers/RefIds and to allow retrieval of data in a row/column fashion similar to SQL. Each returned column may contain hierarchical XML elements/objects. Providers and Responders in a Zone may support SIF_ExtendedQuery in addition to SIF_Query. Support for SIF_ExtendedQuery can be declared in and retrieved from the Zone is various Infrastructure messages and objects.

Note that matching rows are generated solely based on the SIF_From clause, with optional join criteria, optionally limited/filtered by the SIF_Where clause. If a repeatable element is requested as a column in SIF_Select, this does not generate multiple rows for each occurrence of matching elements; all elements are returned in the corresponding column within a single row.

If no SIF_DestinationId applies to the request and this element is supplied, the Requester specifies that the extended query be routed to the Provider on record for the given object name. If this element is omitted and no SIF_DestinationId applies to the request, the ZIS routes the request to the Provider on record for the object name in SIF_From.

Identifies which data elements/attribute are to be returned as columns in each matching row.

Specifies whether query results should return all rows (false) or just distinct ones (true). Rows are distinct if at least one column differs between them.

The maximum number of rows to return. If All, return all rows, otherwise return the top rows up to the maximum row count indicated.

Indicates the element/attribute to return as a column. Contents can be left empty to return the whole object specified in ObjectName, or * can be designated to return all attributes and immediate child elements of the object specified in ObjectName, or SIF_Element Syntax can be specified, relative to the object specified in ObjectName. Requested attributes are to be returned as the text value of the corresponding attribute, elements as a copy of the XML element itself including attributes if they exist.

Optional caption for the column.

The name of the object from which to retrieve element/attributes.

Join specification for the query if more than one object is being queried. If only one object is being queried, specify it without the SIF_Join clause. This clause generates the matching rows returned, optionally limited/filtered by the SIF_Where clause. Each object referenced in the SIF_Select, SIF_Where and SIF_OrderBy clauses must be included here.

The name of the object to query.

Additional objects to query, with join conditions specifying the relationships between objects.

Type of relational join.

Specifies the conditions for the join.

Specifies the left-side element/attribute on which to constrain the join. Currently only support for keys/RefIds/RefId references is required.

Name of the object that contains the element/attribute.

Specifies right left-side element/attribute on which to constrain the join. Currently only support for keys/RefIds/RefId references is required.

Name of the object that contains the element/attribute.

Optionally specifies conditions to limit/filter rows resulting from the SIF_From clause.

Conditions that matching rows must meet.

The Boolean operator for joining conditions (SIF_Conditions elements) within this element. Note that None should be used if there is only one SIF_Conditions element.

This construct allows for nested conditions.

The boolean operator for joining conditions (SIF_Condition elements) within this element. Note that None should be used if there is only one SIF_Condition element.

This element represents an individual condition.

This is the element/attribute being queried.

The name of the object containing the element/attribute.

The comparison operator for the condition.

SIF_Value is the data that is used to compare with the value of the element or attribute.

An optional list of elements/attributes by which to sort the resulting rows.

Indicates the element/attribute by which to sort.

The name of the object containing the element/attribute.

Whether to order the element/attribute in ascending or descending order.

This element provides a wrapper for data returned in response to a SIF_ExtendedQuery. Used in SIF_Response and SIF_ReportObject.

Provides the element/attribute and caption information for each column supplied in SIF_ExtendedQuery. The order must correspond to the order of the elements as requested in SIF_ExtendedQuery.

The element/attribute specified for the column in SIF_ExtendedQuery.

The object in which the element/attribute occurs.

The caption for the column, if specified in SIF_ExtendedQuery.

Optionally allows type of column value to be explicitly communicated.

A list of matching rows resulting from the supplied SIF_ExtendedQuery. Note that the complete list of rows may span multiple SIF_Response messages, per the SIF_MaxBufferSize supplied in SIF_Request. If there are no matching rows, this is an empty list.

An individual matching row resulting from the supplied SIF_ExtendedQuery.

Contains the value of each column specified in SIF_ExtendedQuery/SIF_Select. The order of the columns must correspond to the order of the elements as requested in SIF_ExtendedQuery. Note the number of columns may be expanded from the requested columns if * is indicated one or more times in the SIF_Select clause.

This message is used as an acknowledgement to an infrastructure message.

Header information associated with this message.

The SIF_SourceId of the infrastructure message for which the SIF_Ack serves as a response.

The SIF_MsgId of the infrastructure message for which the SIF_Ack message serves as a response.

This element is used to signal a successful response.

This element is used to signal an unsuccessful response.

SIF_Event is used to deliver event objects as defined in SIF.

Header information associated with this message.

Contains the actual object (partial or whole) that is being added, changed or deleted.

This is the name of the object being added, changed or deleted.

This is the action associated with the object that is being conveyed by this SIF_Event.

The SIF_Provide message is used for advertising the provision of data objects.

Header information associated with this message.

This is the object that is being provided.

The actual name of the object that is being provided.

Whether or not the Agent supports SIF_ExtendedQuery for this object.

The contexts in which the object is being provided; if omitted, the context is SIF_Default.

Once registered, this message allows an agent to announce to the ZIS the functionality the agent will provide. The ZIS compares the functionality to its access control list and either returns a failure or a success. Upon success, the ZIS performs an atomic update of its provide/subscribe database entries for the agent to match the objects listed in this message and atomically updates other stored settings for the agent. A ZIS must not allow an agent to perform operations that it did not successfully announce. Agents should be aware that if the access control list changes after a successful SIF_Provision, some operations may still be rejected with access control errors.

Header information associated with this message.

A list of objects an Agent wishes to provide.

The name of each object.

Whether or not SIF_ExtendedQuery is supported with regard to this object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects to which an Agent wishes to subscribe.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to publish Add events.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to publish Change events.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to publish Delete events.

The name of each object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects an Agent wishes to request.

The name of each object.

Optionally specify whether or not SIF_ExtendedQuery may be sent in requests for this object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of objects for which an Agent wishes to handle requests, whether or not it is the Provider for each object. Note that this list MUST include those objects specified in SIF_ProvideObjects.

The name of each object.

Whether or not SIF_ExtendedQuery is supported with regard to this object.

Applicable contexts for stated object support. If omitted, the context defaults to SIF_Default.

A list of SIF Zone Services that the agent wishes to provide to the zone

The name of the SIF Zone Service as defined by a SIF Zone Service specification

Applicable contexts for stated SIF Zone Service support. If omitted, the context defaults to SIF_Default.

Indicates that the agent desires to respond to directed requests for one or more services in the SIF Zone

The name of the SIF Zone Service as defined by a SIF Zone Service specification

Applicable contexts for stated SIF Zone Service support. If omitted, the context defaults to SIF_Default.

Indicates that the agent will make service calls to the specified SIF Zone Service by sending a SIF_ServiceInput message. This is an optinal element that is used for allowing agents to report all of their expected activities within a zone. It is not used operationally within the zone, and failing to submit this element while provisioning will not prevent the agent from making service calls.

The name of the SIF Zone Service as defined by a SIF Zone Service specification

Applicable contexts for stated SIF Zone Service support. If omitted, the context defaults to SIF_Default.

The agent is not required to specify which operations it will invoke on the specified SIF Zone Service. However, the agent can do so if it desires report all of the activity it does within a zone.

A specific method that the agent invokes the specified SIF Zone Service

Indicates that the agent desires to subscribe to one or more events emitted by the specified service

The name of the SIF Zone Service as defined by a SIF Zone Service specification

Applicable contexts for stated SIF Zone Service support. If omitted, the context defaults to SIF_Default.

If SIF_Operations is not present, then the agent desires to subscribe to all events emitted by the service within the given context

A specific event that the agent desires to subscribe to

SIF_Register is the message for registering an agent with a ZIS.

Header information associated with this message.

This is the descriptive name of the agent that is registering (i.e. Ramsey Media Center).

Specifies the SIF Implementation Specification version(s) defining messages the agent can receive. If the ZIS cannot communicate in this format, it should reject the request.

The format of SIF_Version values can be found in Version Numbers. In a SIF_Register message, an individual SIF_Version element may also contain the following wildcards:

* - Any SIF version

<major version>.* - Any minor version plus revisions within a major version (e.g., 1.*)

<major version>.<minor version><r>* - Any revision within a minor version (e.g., 1.1r*)

Note: As wildcarding was first introduced in version 1.1 of the specification, 1.* does not match versions 1.0, 1.0r1 or 1.0r2. 1.1 or later agents that register with 1.* and wish to also receive messages from pre-1.1 agents must include SIF_Version element(s) with the supported pre-1.1 versions.

Specifies the maximum size of a packet to be returned by the ZIS. The ZIS may return packets smaller than, or equal to, the maximum value.

Specifies the communication mode (Pull or Push) as chosen by the message sender.

If SIF_Mode is Push, SIF_Protocol contains protocol information for contacting the agent in Push mode. A Pull-mode agent does not need to send SIF_Protocol; if received, a ZIS ignores it.

The vendor of the SIF agent.

The agent version number. The format of this field is undefined, but it should match the format used in the agent's conformance statement, if the agent is SIF Certified.

Examples
2.0.1.11

Contains information about the vendor of the product that the agent represents.

The name of the company of the product that this agent supports.

The name of the product that this agent supports.

The version of the product. This field is informative only.

HTTP URL referencing an icon for graphical representation of the application/agent. Should range from 16x16 pixels to 128x128 pixels and be of an image MIME type commonly supported by Web browsers (e.g. PNG, JPEG, GIF). Agents may optionally follow the more restrictive guidelines at [FAVICON].

SIF_Request is used to request information in SIF data objects from other SIF nodes.

Header information associated with this message.

Specifies which SIF Implementation Specification version should be used when returning the response data; wildcards are allowed. The responding agent SHOULD return data using the highest version it supports that falls within the specified versions.

Specifies the maximum size of a response packet to be returned to the requester. The responder may return packets smaller than, or equal to, the maximum value. To guarantee delivery of response packets, requesting agents must not specify a SIF_MaxBufferSize greater than its registered SIF_Register/SIF_MaxBufferSize.

Either SIF_Query or SIF_ExtendedQuery must be specified, which contain the criteria to be used to match response objects.

SIF_Response is used to respond to a SIF_Request message.

Header information associated with this message. The SIF_DestinationId needs to be the SIF_SourceId of the original SIF_Request message being processed.

This is the message ID of the SIF_Request message being processed. It provides a unique match between a SIF_Response and a previous SIF_Request. Since the ID of each message from an agent is unique, the receiver of a SIF_Response message will be able to relate the SIF_Response to a SIF_Request that it sent out previously.

This element represents the index of the SIF_Response message in the sequence of packets that make up a complete response. Its value must be in the range of 1 through n, with n equal to the total number of packets that make up a response.

The receiver of a SIF_Response message, with the help of the SIF_MorePackets and SIF_PacketNumber element in each incoming SIF_Response message, will be able to interpret and process each SIF_Response as part of a complete response to a previous SIF_Request.

This element provides an indication as to whether there are more packets besides this one to make up a complete response.

The necessity of this element stems from the requirement on an agent to break response data to fit into the SIF_MaxBufferSize provided in the SIF_Request. Agents may also break response data into multiple packets for the benefit of improving performance or for circumventing limitations of the underlying network infrastructure.

When this element's value is equal to No, it is an indication from the sender to the receiver that it has already sent out all the packets that make up a complete response for a SIF_Request as indicated by the SIF_RequestMsgId element.

The responder returns SIF_Error, SIF_ObjectData or SIF_ExtendedQueryResults.

This element allows the Responder to report an error condition that occurs while processing the SIF_Request.

If a SIF_Error element is present, the requesting agent must not expect to receive further SIF_Responses to the SIF_Request.

The SIF_ObjectData element contains the data objects matching the supplied criteria in the SIF_Request message if the SIF_Request contained SIF_Query. If the SIF_Request contained SIF_ExtendedQuery, include SIF_ExtendedQueryResults.

This element contains the elements requested by SIF_ExtendedQuery in SIF_Request.

This message is used to subscribe to event objects that are contained in this message.

Header information associated with this message.

The actual name of the object that is being subscribed to. All valid SIF_Events for this object will be routed to the subscriber.

The contexts to which the subscription applies; if omitted, the context is SIF_Default.

This message is designed to control the flow of data an agent and ZIS or vice-versa, and to synchronously retrieve data available from the ZIS.

Header information associated with this message.

This element holds the sub-message being sent.

This sub-message detects if an a Push-Mode Agent or ZIS is ready to receive and process messages.

This sub-message tells a receiver not to send any more messages to the sender.

This message tells a receiver that the sender is able to process messages.

This message tells the ZIS to return the first available message to the agent, subject to Selective Message Blocking.

This message tells the ZIS to return the current SIF_ZoneStatus in a SIF_Ack.

This message tells the ZIS to return the Agent's ACL permissions in a SIF_Ack.

This sub-message asks a receiver (ZIS or Push-Mode Agent) to cancel the specified SIF_Requests, pending or in process.

The SIF_SystemControl message is already part of the SIF Infrastructure. This messages allows for synchronous communication between an agent and a ZIS. The SIF_SystemControl - SIF_CancelServiceInputs allows an agent or ZIS to notify the other party that the specified SIF_ServiceInput should be cancelled.