Draft X3D Specification Addition for NetworkSensor capability

Document Status

Work on these nodes has been discontinued, at least temporarily. Because the NetworkSensor node allows definition of new fields by name, a proper implementation requires native X3D-player support and a full Prototype-based implementation is not possible. No X3D browser companies have yet committed to produce such an implementation.

Further questions can be directed to the x3d-public@web3d.org mailing list.

Specification draft updated June 12 2008


9 Networking Component

Insert the following new sections 9.4.4 and 9.4.5 before section 9.5:

9.4.4 Connection

Connection: X3DNetworkSensorNode {
    SFBool [in,out] enabled  TRUE
    SFNode [in,out] metadata NULL [X3DMetadataObject]
    SFBool        [out]      isActive FALSE
    MFString      [in,out]   url ["x3dp://localhost:80/"]
    SFInt32       [in]       protocol 0 [0,65535]
    SFTime        [in,out]   timeOut  0
    SFBool        [in]       secure   TRUE
}

The Connection node specifies a network connection such as a TCP/IP socket. The X3D Browser shall support at least two such nodes being active at any one time. Support for more active Connection nodes can be optionally supported.

The url field identifies the application protocol://network address:port number triplet for the stream in the style of urls.

The protocol field is a code specifying the underlying protocol (such as HTTP, ftp, TCP/IP, UDP) to use: 0 means underlying protocol is defined by the application protocol, 1  for HTTP (default), 2 for HTTP1.1, 3 for TCP/IP, 4 for UDP, 5 for  multicast.  Multicast support is optional because it can be impractical to get it to work in a general public situation, due to lack of control/access to routers. There is no onus on the X3D application to have control over multicast configuration of network nodes.

The application protocol part of the address field identifies the higher level "application" protocol the X3D application is using over the underlying protocol specified in the protocol field. If the default HTTP underlying protocol is to be used then the prefix: "http:" can be omitted and refers specifically to HTTP 1.0. When the underlying protocol is anything other than HTTP the default application protocol is "x3dp:"

The application protocol "x3dp:" refers to a basic common application protocol to be defined in another X3D document. When it is defined, it recommended that "x3dp:" be supported so there is at least one application protocol that all X3D Browsers can interpret. Examples of other application protocols that may be used are "xmpp:", "dis:", and "swmp:".  This specification shall, however,  be independent of the status of the common x3dp application protocol specification.

url may contain a list of host address triplets, each formatted as: <protocol><host address><port number>. For example, a url may be:  ["x3dp://224.2.181.145:7000" "http://224.2.181.145:7000"  "alternate.net.server"] or it may just be: ["localhost"]. It is recommended that each host be initially tested for response so that non responding hosts can be skipped for one that does respond. It is up to the implementation as to how hosts are tested, whether in sequential order or parallel. However, the order hosts are listed is to be taken as the order of preference for responding hosts. That is, if multiple hosts respond, the one listed first is to be used. The url field may have an additional suffix string such as initial path and authentication, for example: "x3dp://localhost:80/pathid?initialAuthentication="authString".

The port number part of the address field identifies the port to use, for example "7000".

Note that if more than one NetworkSensor refers to the same connection node then the events from the NetworkSensor nodes shall be routed over the same connection. By default, only two simultaneous active ports are required to be supported.

isActive is initially FALSE and only becomes TRUE if the port is successfully opened.

enabled is initially TRUE and means the browser should attempt to open the port. If set to FALSE the port will be closed. If the port could not be opened the browser will change enabled to FALSE.

timeout is the period of time to wait, in milliseconds, before deciding a host is not responding. If a connection times out, enabled shall be set to FALSE.

secure is TRUE by default and means that only connections to the originating server are accepted. The browser may optionally implement a secure=FALSE capability in which case it will be possible for the web3d application to communicate with non originating servers, but this is not as secure.

9.4.5 NetworkSensor

NetworkSensor : X3DNetworkSensorNode {
    SFBool    [in,out] enabled         TRUE
    SFNode    [in,out] metadata        NULL  [X3DMetadataObject]
    SFBool    [out]    isActive
    SFNode    [in out] connection      NULL [Connection node only]
    SFString  [in]     httpRequest     ""
    MFString  [out]    httpResponse    NULL
    SFString  []       channelId       ""
    # And any number of:
    fieldType [in]     fieldName
    fieldType [in,out] fieldName
    fieldType [out]    fieldName
    fieldType []       fieldName
}

The NetworkSensor is intended to provide more efficient sending and receiving of events via a network connection than would normally be possible via an external API. It acts as a high speed gateway between a network stream and the X3D scene graph so routes can be set to/from it. It defines a set of fields to be sent/received over a connection.  The connection shall be non blocking: the node shall wait for a response without suspending the execution of other Browser functions.

Fan in of events is treated the same as other nodes: multiple events received at the same "time" are not buffered, they are sent as one packet.  In the case of HTTP, if the node is waiting on a response then it is up to the Browser implementation to buffer incoming MFString events or not.

enabled is initially TRUE.

connection specifies the network connection to use.

httprequest  and httpResponse only apply when the protocol is HTTP. The HTTP capability should allow for HTTP functions such as POS, MGET, HEADER and others defined in HTTP. When the protocol is HTTP, "fieldType" fields are ignored.

httprequest contains at least a URL but this may be preceeded by a HTTP header. The X3D Browser shall support the use of standard URL encoded parameters with the special characters "?", "=", """ and "&" appended to the URL. The domain is already specified in the connection field.

httpResponse is the event returned from a server in response to a HTTP request. The response must be in the form of an X3D MFNode. That is, the HTTP httprequest-httpResponse sequence shall operate in a similar way as if it came from a CreateX3DFromUrl call. 

channelId  identifies the NetworkSensor node instance which corresponds to a communication channel. For example, two clients with the same channel id of 1 could communicate the same type of data between them. This enables more than one NetworkSensor to use the same connection and the connection can  push the id's over the network  so a recipient can know which NetworkSensor  it came from.

Any number of fields and field types can be defined. The transmission format will be determined by the chosen protocol.
The default mapping order of fields to elements in transmission packets is in-order.

Insert row in Support levels table 9.3, support level 4:

Connection | "Lower level protocols: HTTP1.0, HTTP1.1, TCP/IP and UDP shall be supported except multicast which is optional. The W3C URL encoding standard shall be supported. "


4.4.2.3 Interface hierarchy

Add the following to the interface hierarchy diagram:


"
+- X3DNetworkSensorNode -+- Connection

                                              -+- NetworkSensor
"