5 Data type reference
5.1 Introduction and Table of Contents
5.1.1 Introduction
This clause describes the language independent data types used in the definition of 6 Services reference.
5.1.2 Table of contents
Table 5.1 defines the contents of this clause.
5.1.3 Concepts
All data types in this clause are language binding independent. They represent single value information that is passed as parameters, return values or error conditions that can be generated through the external authoring interface. Each language binding shall define implementations of each of these data types.
These data types represent the specific implementation of each type; that is, how the VRML browser would represent them internally, not the text format described in ISO/IEC 14772-1.
5.2 Data type definitions
5.2.1 EAIAction
EAIAction is a single valued field representing a qualifier for a more general service type. Each use of the EAIAction type shall define the range of acceptable values.
5.2.2 EAIBrowserApp
EAIBrowserApp is a data type that represents the complete browser application. This is different from 5.2.4 EAIBrowserRef because it defines the browser application itself whereas the EAIBrowserRef defines a reference to the standardised interface to the browser's functionality. The data type shall contain some method for obtaining an EAIBrowserRef.
5.2.3 EAIBrowserName
This data type defines a representation of the name of the browser. If the browser implementation does not support this information, a NULL value is considered a legal representation of this data type
5.2.4 EAIBrowserRef
This data type represents a browser reference. This is a unique identifier per browser instance. Individual language bindings may place conditions on uniqueness allowing other methods for checking equivalent references to the same browser.
The browser concept is further defined in 4.4.4 Browser.
5.2.5 EAIBrowserVersion
This data type defines a representation of the name of the browser. If the browser implementation does not support this information, a NULL value is considered a legal representation of this data type
5.2.6 EAIFieldAccess
This data type defines the type of access that is permitted to a field. The valid values are types for field, eventIn, eventOut and exposedField.
5.2.7 EAIFieldID
This data type represents an identifier for a particular field of a node. It is guaranteed to be unique within the scope of an individual NODE reference. It is not guaranteed to be unique in terms of all field references generated. To uniquely define a field within the scene graph, a combination of node and field identifiers is needed.
The field concept is further defined in 4.4.6 Field.
5.2.8 EAIFieldName
This data type is used to represent a field name.
5.2.9 EAIFieldType
This data type is used to store the type of data a field represents. In some cases (where the field type represents an MFString or SFString), this field type may correspond to an EAINodeID. Valid types of the field are defined in ISO/IEC 14772-1 5, Field and event reference.
5.2.10 EAIFieldValue
This data type represents the value to be set or to be returned of an EAIFieldType in language specific terms. A table may be constructed mapping each EAIFieldType represented to at least one language specific entry. This data type contains an item of class EAIFieldType and an item of the field type specified by the value of the first item. All field types defined in ISO/IEC 14772-1 5. Field and event reference shall be supported.
5.2.11 EAIFrameRate
This data type is used to represent the frame rate in frames per second that is currently being achieved by the browser.
5.2.12 EAINavSpeed
This data type is used to represent the navigation speed of the user in metres per second.
5.2.13 EAINodeID
This data type is used to specify an identifier for a node. Individual language bindings may place conditions on uniqueness allowing other methods for checking equivalent references to the same node. The node reference is not required to be part of the active scene graph.
A NULL value is a legal value for this data type. It is used to indicate that no node identifier is to be used. For example the Field service setValue (see 6.5.7 setValue) a value of NULL on an SFNode field type is used to clear the node that may have previously been set as the value.
The node concept is further defined in 4.4.5 Node.
5.2.14 EAINodeType
This data type is used to represent the node type.
5.2.15 EAIParameterList
EAIParameterList is the abstract data type used to represent a list of parameters that may be passed to a service request. Each language binding shall be required to define the exact listing of parameters and their mapping to language specific types. This may be used to represent more than one list of parameters where a binding provides multiple overloaded implementations of a single service.
5.2.16 EAIPropertyList
EAIPropertyList is an abstract data type defining a set of key/value pairs for the provision of properties.
5.2.17 EAIRequesterID
This data type represents the identifier of a client application or part thereof that is requesting a service to be performed. Variables of this data type are usually used to identify a particular client piece of code that is interested in listening for changes in some information in either the scene graph or browser state that functions as a callback device.
5.2.18 EAIURL
EAIURL is a data type which references a single URL. The URL may be any valid URL representation but is usually defined as a human readable string that conforms to 2. [URL].
5.2.19 EAIString
This data type represents a string formatted with the UTF-8 universal character set. (see 2.[UTF8]).
5.2.20 NULL
This data value is used to represent the empty value. It contains no data or reference to any data type as a valid value to return from a service when nothing can be returned and yet no error is generated. Conceptually equivalent to 2.[JAVA] null data type and C/C++ NULL data type.
5.3 Error types
5.3.1 EAIError
This section defines the error types that may be generated in response to service requests. Errors are generated as synchronous values from a service request and returned as variables of type EAIError. These error types appear in the errors definition of a service request (6.1.3 Conventions). A language binding shall define the representation for the EAIError data type and assign values for each of the errors defined below but may also define additional error data types to these.
5.3.2 EAI_BROWSER_UNAVAILABLE
This error indicates that the request to gain a reference to a EAIBrowserApp has failed. Examples may be that a network connection is down or that the type of reference required is not supported by the vendor specific implementation of a language binding.
5.3.3 EAI_CONNECTION_ERROR
An error has occurred that resulted in the connection between the browser and external application becoming non-functional. Therefore, the service request could not be executed. This is a different error condition from EAI_BROWSER_UNAVAILABLE as it assumes that a valid reference has already been obtained and the error occurred at a later time.
5.3.4 EAI_DISPOSED
The request made of the current EAINodeID, EAIFieldID or EAIBrowserRef reference is being made to an object that has already been disposed prior to this service request.
5.3.5 EAI_INVALID_ACCESS_TYPE
The attempt to perform an operation of a field failed because it is an invalid action for that field type. For example an attempt was made to read the value of an eventIn would generate this error.
5.3.6 EAI_INVALID_BROWSER
The instance of EAIBrowserRef data type provided as part of the parameters to the service request has been disposed of prior to this request.
5.3.7 EAI_INVALID_NAME
The name provided to a service request is invalid or cannot be found in the context of that object.
5.3.8 EAI_INVALID_NODE
The instance of EAINodeID data type provided as part of the parameters to this service request has been disposed of prior to this request.
5.3.9 EAI_INVALID_FIELD
The instance of EAIFieldID data type provided as part of the parameters to this service request has been disposed of prior to this request.
5.3.10 EAI_INVALID_URL
The instance of EAIURL data type provided as part of the parameters to this service request is invalid due to a syntax error. Errors due to the requested URL not being available shall generate either an EAI_URL_UNAVAILABLE error or an asynchronous event notifying of such a problem.
5.3.11 EAI_INVALID_VRML
The EAIString or VRML file (for example as a result of the fetching of a URL reference) passed to this service request contains invalid syntax and cannot be parsed to produce legal data types for use in other service requests.
5.3.12 EAI_URL_UNAVAILABLE
The service request requiring the browser to have a world URL set cannot be completed because no URL has been set. This error is typically generated from a getWorldURL (6.3.11 getWorldURL) or getNode (6.3.9 getNode) service request
5.4 Event Types
5.4.1 Browser Events
Browser event types are asynchronous events that are generated in response to changes in the status of the browser implementation. The following event types shall be implemented by each language binding. Additional implementation dependent events may be defined to supplement the provided event types.
5.4.1.1 EAIBrowserEvent
The data type that represents the general class of events produced by each browser service. (see 4.5.3 Browser to external application)
5.4.1.2 EAI_B_Initialized
The data type representing the browser having completed the initialisation process of loading VRML content (see 4.5.3.2 Initialize).
5.4.1.3 EAI_B_Shutdown
The data type representing the browser being shutdown. That is the execution model is no longer running or content is displayed (see 4.5.3.3 Shutdown).
5.4.1.4 EAI_B_ConnectionError
The data type representing an error condition has occurred in the internal connection between the browser and the external application (see 4.5.3.5 Connection Lost).
5.4.1.5 EAI_B_URLError
The data type representing an error condition when no URLs could be processed to form valid VRML content (see 4.5.3.4 No URLs Available).
5.4.2 EAIFieldEvent
The data type used to represent the notification of a change in a field value that the external application has registered interest in.