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 SAIAction
A single valued field representing a qualifier for a more general service
type. Each use of the SAIAction type shall define the range of acceptable
values.
5.2.2 SAIBrowserApp
A data type that represents the complete browser application. This is different
to 5.2.4 SAIBrowserRef because it defines the
browser application itself whereas the SAIBrowserRef defines a reference
to the standardised interface to the browser's functionality. The data
type shall contain some method for obtaining an SAIBrowserRef.
5.2.3 SAIBrowserName
The data type defines a representation of the name of the browser. If the
browser implementation does not support this information then a NULL value
is considered a legal representation of this data type
5.2.4 SAIBrowserRef
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 SAIBrowserVersion
The data type defines a representation of the name of the browser. If the
browser implementation does not support this information then a NULL value
is considered a legal representation of this data type
5.2.6 SAIFieldAccess
The 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 SAIFieldID
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 are needed.
The field concept is further defined in 4.4.6
Fields.
5.2.8 SAIFieldName
The data type used to represent a field
name.
5.2.9 SAIFieldType
The data type to represent 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 SAINodeID. Valid types of the field are defined
in
ISO/IEC 14772-1 5, Field and event reference.
5.2.10 SAIFieldValue
A data type that represents the value to to be set or to be returned of
an SAIFieldType in language specific terms. A table may be constructed
mapping each SAIFieldType represented to at least one language specific
entry. This data type is a variant record containing an item of class SAIFieldType
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 SAIFrameRate
The data type used to represent the frame rate that is currently being
achieved by the browser.
5.2.12 SAINavSpeed
The data type used to represent the navigation speed of the user.
5.2.13 SAINodeID
This data type represents identifiers for a node.
Individual language bindings may place conditions on uniqueness allowing
other methods for checking equivalent references to the same browser. 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.6 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 SAINodeType
The data type used to represent the node
type.
5.2.15 SAIParameterList
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 SAIPropertyList
An abstract data type defining a set of key/value pairs for the provision
of properties.
5.2.17 SAIRequesterID
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 SAIURL
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 SAIString
This data type represents a string formatted with the UTF-8 universal character
set. (see 2.[UTF8]).
5.2.20 NULL
A representation of the empty value. 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 SAIError
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 SAIError. 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 SAIError 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 SAI_BROWSER_UNAVAILABLE
The request to gain a reference to a SAIBrowserApp
has failed. Examples may be because 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 SAI_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 to SAI_BROWSER_UNAVAILABLE
as it assumes that a valid reference has already been obtained and the
error occurred at a later time.
5.3.4 SAI_DISPOSED
The request made of the current SAINodeID, SAIFieldID or
SAIBrowserRef reference
is being made to an object that has already been disposed prior to this
service request.
5.3.5 SAI_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 SAI_INVALID_BROWSER
The instance of SAIBrowserRef data type provided as
part of the parameters to the service request has been disposed of prior
to this request.
5.3.7 SAI_INVALID_NAME
The name provided to a service request is invalid or cannot be found in
the context of that object.
5.3.8 SAI_INVALID_NODE
The instance of SAINodeID data type provided as part
of the parameters to this service request has been disposed of prior to
this request.
5.3.9 SAI_INVALID_FIELD
The instance of SAIFieldID data type provided as part
of the parameters to this service request has been disposed of prior to
this request.
5.3.10 SAI_INVALID_URL
The instance of SAIURL 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 SAI_URL_UNAVAILABLE
error or an asynchronous event notifying of such a problem.
5.3.11 SAI_INVALID_VRML
The SAIString 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 SAI_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.6 getWorldURL)
or getNode (6.3.15 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 SAIBrowserEvent
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 SAI_B_Initialized
The data type representing the browser having completed the initialisation
process of loading VRML content (see 4.5.3.1
Initialize).
5.4.1.3 SAI_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.2
Shutdown).
5.4.1.4 SAI_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.4
Connection Lost).
5.4.1.5 SAI_B_URLError
The data type representing an error condition when no URLs could be processed
to form valid VRML content (see 4.5.3.3
No URLs Available).
5.4.2 SAIFieldEvent
The data type used to represent the notification of a change in a field
value that the external application has registered interest in.
http://www.vrml.org/Specifications/VRML97/part2/dataRef.html