VRML97 logo

5 Data type reference

--- VRML separator bar ---

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.
 
 
Table 5.1 -- Table of contents
5.1 Introduction and table of contents 
 5.1.1 Introduction 
 5.1.2 Table of contents 
 5.1.3 Concepts 

5.2 Data type definitions 
 5.2.1 SAIAction 
 5.2.2 SAIBrowserApp 
 5.2.3 SAIBrowserName 
 5.2.4 SAIBrowserRef 
 5.2.5 SAIBrowserVersion 
 5.2.6 SAIFieldAccess 
 5.2.7 SAIFieldID 
 5.2.8 SAIFieldName 
 5.2.9 SAIFieldType 
 5.2.10 SAIFieldValue 
 5.2.11 SAIFrameRate 
 5.2.12 SAINavSpeed 
 5.2.13 SAINodeID 
 5.2.14 SAINodeType 
 5.2.15 SAIParameterList 
 5.2.16 SAIPropertyList 
 5.2.17 SAIRequesterID 
 5.2.18 SAIURL 
 5.2.19 SAIString 
 5.2.20 NULL

5.3 Error data types 
 5.3.1 SAIError 
 5.3.2 SAI_BROWSER_UNAVAILABLE 
 5.3.3 SAI_CONNECTION_ERROR 
 5.3.4 SAI_DISPOSED 
 5.3.5 SAI_INVALID_ACCESS_TYPE 
 5.3.6 SAI_INVALID_BROWSER 
 5.3.7 SAI_INVALID_NAME 
 5.3.8 SAI_INVALID_NODE 
 5.3.9 SAI_INVALID_FIELD 
 5.3.10 SAI_INVALID_URL 
 5.3.11 SAI_INVALID_VRML 
 5.3.12 SAI_URL_UNAVAILABLE 

5.4 Event Types 
 5.4.1 Browser Events 
  5.4.1.1 SAIBrowserEvent 
  5.4.1.2 SAI_B_Initialized 
  5.4.1.3 SAI_B_Shutdown 
  5.4.1.4 SAI_B_ConnectionError 
  5.4.1.5 SAI_B_URLError 
 5.4.2 SAIFieldEvent 
 

 

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.

--- VRML separator bar ---

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.

--- VRML separator bar ---

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
--- VRML separator bar ---

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.

--- VRML separator bar ---

http://www.vrml.org/Specifications/VRML97/part2/dataRef.html