6 Services reference

6.1 Introduction and overview

6.1.1 Introduction

This clause provides a detailed definition of the semantics of the services that a browser shall provide to external applications as defined in this part of ISO/IEC 14772.

6.1.2 Table of contents

Table 6.1 defines the topics in this clause.

**Table 6.1 -- Table of contents**
6.1 Introduction and overview 6.1.1 Introduction 6.1.2 Table of Contents 6.1.3 Conventions used 6.2 Establishing a connection 6.2.1 Introduction 6.2.2 getBrowser 6.2.3 createBrowser 6.3 Browser services 6.3.1 Introduction 6.3.2 getName 6.3.3 getVersion 6.3.4 getCurrentSpeed 6.3.5 getCurrentFrameRate 6.3.6 getWorldURL 6.3.7 replaceWorld 6.3.8 loadURL 6.3.9 setDescription 6.3.10 createVrmlFromString 6.3.11 createVrmlFromURL 6.3.12 Dynamic Route Handling 6.3.13 Update Control 6.3.14 Register Browser Interest 6.3.15 getNode 6.3.16 dispose	6.4 Node services 6.4.1 Introduction 6.4.2 getName 6.4.3 getType 6.4.4 getField 6.4.5 dispose 6.5 Field services 6.5.1 Introduction 6.5.2 getAccessType 6.5.3 getType 6.5.4 getName 6.5.5 getValue 6.5.6 setValue 6.5.7 Register Field Interest

6.1.3 Conventions

Each item in this clause defines a particular request that can be made through the External Authoring Interface. Each request is defined by a number of characteristics in tabular form. The table contains two columns; The first defines each characteristic type and the second defines the properties of that characteristic.

`parameters:`	first param data type, second param, [optional param data type]
`returns:`	The list of return values data types or expected ranges
`errors:`	List of errors data types
`events:`	The first event The second event
`buffered:`	Simple yes, no or N/A

Parameters shown in square brackets [] are optional and not required to be passed with that service request.

All characteristics defined for every service shall be implemented for each language binding. At the end of each table, some explanatory text will follow which includes extra information pertinent to the implementation of that service.

6.2 Establishing a Connection

6.2.1 Introduction

The following services can be used to establish a session and an obtain a browser reference. Individual browser implementations may support one or both of these methods. At least one shall be required to be supported

6.2.2 getBrowser

`parameters:`	EAIParameterList
`returns:`	EAIBrowserRef
`errors:`	EAI_BROWSER_UNAVAILABLE
`events:`	none
`buffered:`	N/A

This is a blocking call. No further requests from this external application will be processed until an EAIBrowser value has been generated (which may include the need to start a new instance of a VRML browser) or an error condition is generated.

If an application makes a request for the same browser twice in the same session then the same browser identifier shall be returned.

An implementation may define more than one variant of this service with different parameter types. For example there may be alternate forms to access a browser embedded in a HTML page and one for remote access from another machine within the same language binding.

Additional error types may be added by individual language bindings to deal with platform specific issues.

6.2.3 createBrowser

`parameters:`	EAIParameterList, EAIPropertyList
`returns:`	EAIBrowserApp
`errors:`	EAI_BROWSER_UNAVAILABLE
`events:`	none
`buffered:`	N/A

Create a new instance of a browser application. The browser shall start with no URL set (that is no active VRML scene graph). The URL may be set at a later time using the loadURL (see 6.3.8 loadURL) or replaceWorld (see 6.3.7 replaceWorld) service requests.

The property list is used to define the properties of the browser application itself. The service request shall use the same property list definitions as those defined in loadURL. It is not required to support exactly the same capabilities, but the property list format shall be identical and any behaviours are identical.

This is a blocking request. No further requests from this external application will be processed until an EAIBrowser value has been generated (which may include the need to start a new instance of a VRML browser) or an error condition is generated.

Each request of this service shall produce a new browser application instance in accordance with the supplied parameter values.

An implementation may define more than one variant of this service with different parameter types. For example there may be alternate forms to start a browser on a remote machine or to create a new window within a running application.

Additional error types may be added by individual language bindings to deal with platform specific issues.

6.3 Browser Services

6.3.1 Introduction

The following services can be requested from a browser. The titles of each service correspond to the appropriate title as defined in ISO/IEC 14772-1 4.12.10. Default values are not given here as they can be determined by reading the appropriate subsection of ISO/IEC 14772-1. A brief description of each service is defined here where it indicating where it matches or differs from that in ISO/IEC 14772-1.

Although not specified, all services are capable of throwing an EAI_CONNECTION_ERROR whenever a request is made if the session between the application and the browser has failed.

Note: The data representation of the parameters or return values are not specified. It could be equally valid to represent all parameters as strings as it is for binary representations.

6.3.2 getName

`parameters:`	EAIBrowserRef
`returns:`	EAIBrowserName
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	no

The name of the browser is implementation dependent. If this service is not supported a NULL value shall be returned.

6.3.3 getVersion

`parameters:`	EAIBrowserRef
`returns:`	EAIBrowserVersion
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	no

The version number of the browser is implementation dependent. If this service is not supported then a NULL value shall be returned.

6.3.4 getCurrentSpeed

`parameters:`	EAIBrowserRef
`returns:`	EAINavSpeed
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	no

The current speed is the average navigation speed for the currently bound NavigationInfo node in metres per second in the coordinate system of the currently bound viewpoint.

6.3.5 getCurrentFrameRate

`parameters:`	EAIBrowserRef
`returns:`	EAIFrameRate
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	No

Get the current frame display rate of the browser. If this is not supported the value returned is zero.

6.3.6 getWorldURL

`parameters:`	EAIBrowserRef
`returns:`	EAIURL
`errors:`	EAI_URL_UNAVAILABLE EAI_DISPOSED
`events:`	None
`buffered:`	no

Get the fully qualified URL of the currently loaded world. This returns the entire URL including any possible arguments that might be associated with a CGI call or similar mechanism. If the initial world is replaced with loadURL then the string will reflect the new URL. If replaceWorld is called then the URL still represents the original world.

6.3.7 replaceWorld

`parameters:`	EAIBrowserRef, EAINodeID [EAINodeID]s
`returns:`	None
`errors:`	EAI_INVALID_NODE EAI_DISPOSED
`events:`	EAI_B_Shutdown EAI_B_Initialized
`buffered:`	No

The EAI_B_Shutdown event is generated immediately upon receiving this service request.
The EAI_B_Initialized event is generated when the new nodes have been set and all browser specific initialization has taken place but before the first time driven event cascade has been started (event cascades may have previously resulted due to the initialization process through internal scripts).

Replace the current world with the EAINodeID value(s) as the new root nodes. If another replaceWorld or loadURL request is made during the processing of the current request, the current request is terminated and the new one started. In this case, no extra shutdown event shall be generated. The initialise event shall be generated at the point where the world is ready to be run.

6.3.8 loadURL

`parameters:`	EAIBrowserRef, EAIURL [EAIURL]s, EAIPropertyList
`returns:`	None
`errors:`	EAI_INVALID_URL EAI_DISPOSED
`events:`	EAI_B_Shutdown EAI_B_Initialize EAI_B_URLError
`buffered:`	No

The EAI_B_Shutdown event is generated immediately upon receiving this service request if the parameter list is such that the browser is about to be shutdown (for example replaces a HTML Frame where the browser was embedded).

The EAI_B_Initialized event is generated when the new nodes have been set and all browser specific initialization has taken place but before the first time driven event cascade has been started (event cascades may have previously resulted due to the initialization process through internal scripts).

The property list definition shall include at least one property that defines loading the URL supplied as a new world in the supplied EAIBrowserRef. If the property list is empty then the action is to replace the world of the current browser with the new world if the successful URL is a VRML file.

If another replaceWorld or loadURL request is made during the processing of the current request, the current request is terminated and the new one started. In this case, no extra shutdown event shall be generated. The initialise event shall be generated at the point where the world is ready to be run if replaceWorld was called.

6.3.9 setDescription

`parameters:`	EAIBrowserRef, EAIString
`returns:`	None
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	No

If the browser supports a description title, it shall be set to the new description. Typically, this will be the title in a window title bar. In cases where there may be multiple browsers on a single window, the result is implementation dependent.

6.3.10 createVrmlFromString

`parameters:`	EAIBrowserRef, EAIString
`returns:`	EAINodeID [EAINodeID]s
`errors:`	EAI_INVALID_VRML EAI_DISPOSED
`events:`	None
`buffered:`	No

Create VRML nodes from a string. The string must contain valid VRML syntax otherwise an error is generated. If any relative URLs are encountered in this string, then the base is assumed to be the current browser location. The string is not required to contain the VRML file header #VRML V2.0 utf8. If it is present it shall be treated as an indicator to the version of VRML contained. If absent then the default version assumed shall be that provided in ISO/IEC 14772-1 4.2.2 Header. A browser is not required to support any versions prior to ISO/IEC 14772-1.

If the string contains legal VRML statements but does not contain any node instances, a NULL is returned. For example the string may contain EXTERNPROTO declarations but no instances of any node. The order of EAINodeID values returned is guaranteed to be in the order that the top level nodes are declared in the string.

6.3.11 createVrmlFromURL

`parameters:`	EAIBrowserRef, EAIURL [EAIURLs], EAINodeID, EAIFieldID
`returns:`	None
`errors:`	EAI_INVALID_URL EAI_INVALID_NODE EAI_INVALID_FIELD EAI_DISPOSED
`events:`	EAI_B_URLError
`buffered:`	No

Create nodes from the contents of the file represented by the URL. The URL may be a relative URL which is considered to be using the browser location.as the base document. The destination node identifier is not required to be part of the currently rendered scene graph. It is legal to create a node with createVrmlFromString and use that as the destination for a createVrmlFromURL request without having added the node to the active VRML scenegraph.

The EAIFieldID value must designate an MFNode eventIn to pass the nodes as created otherwise an error is generated. The order of nodes passed to the destination node shall remain in the same order that the top level nodes are declared in the file.

6.3.12 Dynamic Route Handling

`parameters:`	EAIBrowserRef, EAINodeID, EAIFieldID, EAINodeID, EAIFieldID, EAIAction
`returns:`	None
`errors:`	EAI_INVALID_NODE EAI_INVALID_FIELD EAI_DISPOSED
`events:`	None
`buffered:`	Yes

The parameter of type EAIAction specifies whether this should be an add or delete of this route. Other actions may be added, such as to query the existance of the nominated route. The EAINodeID/EAIFieldID pair parameters are considerd as defining the source field and destination fields for the route request.

Route modification requests are to fit with the general event model scheme as defined in ISO/IEC 14772-1 4.10 Execution Processing. The end of the event cascade is considered to be the cascade that is initiated by the application sending events into the VRML browser environment. Any new cascades generated as a result of the processing of the initial events are shall not be considered for the determination of the event cascade.

If a single event is sent to the browser then at the point that its event cascade has completed is considered to be the end of the event cascade defined in Step 1 of ISO/IEC 14772-1 4.10.3 Execution Model. If events are batched together through the use of Update control (see 6.3.13, Update Control) then the end of the event cascade is considered to be the end of all the primary cascades caused by the release of the events at end update. That is, all event cascades shall have been completed before steps 2 - 8 of ISO/IEC 14772-1 4.10.3 are permitted to operate.

6.3.13 Update control

`parameters:`	EAIBrowserRef, EAIAction
`returns:`	None
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	N/A

The EAIAction parameter specifies whether this should be to start the buffer (begin update) or to empty it (end update). Other actions may be added, such as to query the number of items, or the state of the buffer and are implementation dependent.

The timestamp of events generated at the call to endUpdate are implementation dependent but should be consistent with the time within the current world. That is, timestamps cannot be in the "past" relative to the other current events generated internally with event model at the time when they are generated.

Begin update and End update are not nesting calls. Once begin update has been called, it may be called any number of times, but only a single end update call is needed to release the buffered events into the scenegraph. A call to end update without a previous matching begin update has no effect.

6.3.14 Register Browser Interest

`parameters:`	EAIBrowserRef, EAIAction, EAIRequesterID
`returns:`	None
`errors:`	EAI_DISPOSED
`events:`	Receiver of all EAIBrowserEvents
`buffered:`	No

This service nominates the requester as the receiver of all EAIBrowserEvents. The act of making this service request itself does not imply any events shall be generated.

The parameter of type EAIRequesterID could be inferred from the source of the input and may not need to be part of the parameters and is implementation dependent. Each binding to this service shall specify this requirement.

The parameter of type EAIAction specifies whether this is a request to add interest in events, or to remove interest in the events.

Any change to the current browser shall be notified to the listener that has registered interest in these events. These event notifications must be made independent of the method of communicating with the browser.

As a minimum, a conforming implementation shall provide the events defined in Section 4.5.3, Browser to External Application.

6.3.15 getNode

`parameters:`	EAIBrowserRef, EAIString
`returns:`	EAINodeID
`errors:`	EAI_INVALID_NAME EAI_URL_UNAVAILABLE EAI_DISPOSED
`events:`	None
`buffered:`	No

The EAIString is to identify the name of the node that has been marked with a DEF statement in the currently loaded VRML scene. Access is only available to DEF names in the top level file that is loaded as a result of loadURL or the initial loading of the browser. DEFs in Inlined files and from dynamically created content shall not be accessible in accordance with ISO/IEC 14772-1 4.6.2 DEF/USE Semantics.

If the world contents have been replaced with a call to replaceWorld, then an EAI_INVALID_NAME error shall be generated as DEF names are not kept once the load has taken place.

6.3.16 Dispose

`parameters:`	EAIBrowserRef
`returns:`	None
`errors:`	None
`events:`	EAI_B_Shutdown
`buffered:`	No

The client is about to exit this session and the browser is free to dispose of any resources that this client may have consumed. An EAI_B_Shutdown event is sent only to this client and may be generated internally by the language implementation on the client machine (that is, it is not required that the browser itself generate this event, just that the event is generated). If any events have been held because begin update has been called, disposing of the browser shall also call end update to release those events to the browser.

6.4 Node Services

6.4.1 Introduction

The following services can be requested of an individual node. Each service requires that you have an identifier for that node. After a request of an individual node to dispose of their resources, any further request made to a node service shall generate a disposed error.

Although not specified, all services are capable of throwing an EAI_CONNECTION_ERROR whenever a request is made if the session between the application and the browser has failed.

6.4.2 getName

`parameters:`	EAINodeID
`returns:`	EAIString
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	No

Request the name of this node. The name is the name as specified in ISO/IEC 14772-1 6 Node Reference. If the node represents a PROTO node instance then the name returned is the name of the PROTO declaration.

6.4.3 getType

`parameters:`	EAINodeID
`returns:`	EAINodeType
`errors:`	EAI_DISPOSED
`events:`	None
`buffered:`	No

The type indicator is either the type defined for the basic node types in the VRML specification, or the PROTO type name if it is a prototyped node. This is not required to be supported for a conforming implementation.

6.4.4 getField

`parameters:`	EAINodeID, EAIFieldName
`returns:`	EAIFieldID
`errors:`	EAI_INVALID_NAME EAI_DISPOSED
`events:`	None
`buffered:`	No

Request a field identifier so that operations can be performed on the node properties. If the field requested is an exposedField then either the field name or the set_ and _changed modifiers may be used to access the appropriate form of the node as required. Access to fields is implementation dependent.

6.4.5 Dispose

`parameters:`	EAINodeID
`returns:`	None
`errors:`	None
`events:`	None
`buffered:`	Yes

The client has no further interest in the resource represented by this node. The browser is now free to take whatever action is necessary to reclaim any resources consumed by this node, at any time in the future. If this node has already been disposed, further requests have no effect.

Disposing of a node does not remove the node from the scenegraph (if it was inserted in the first place) but rather removes any local information per client to it. The underlying VRML node representation is only disposed of if no other applications or scenegraph structures contain references to this node and the responsibility and timing for this action is browser implementation specific.

6.5 Field Services

6.5.1 Introduction

The following are services that can be requested of individual fields of a node. If the node that a field was retrieved from has been disposed, field services are still permitted to operate providing that the field reference has been obtained before disposing of the node. If a call is made to a field service after requesting to dispose of the field, a disposed error shalll be generated.

Although not specified, all services are capable of throwing an EAI_CONNECTION_ERROR whenever a request is made if the session between the application and the browser has failed.

6.5.2 getAccessType

`parameters:`	EAINodeID, EAIFieldID
`returns:`	EAIFieldAccess
`errors:`	None
`events:`	None
`buffered:`	No

The representation of the access type is implementation dependent.

6.5.3 getType

`parameters:`	EAINodeID, EAIFieldID
`returns:`	EAIFieldType
`errors:`	None
`events:`	None
`buffered:`	No

The type of the field is implementation dependent.

6.5.4 getName

`parameters:`	EAINodeID, EAIFieldID
`returns:`	EAIFieldName
`errors:`	None
`events:`	None
`buffered:`	No

If supported by the implementation, this will return the name of the field as it was requested from the node. If the service requested the set_children field of a grouping node, this will return "set_children", but if a different request was for children on the same node, "children" will be returned.

6.5.5 getValue

`parameters:`	EAINodeID, EAIFieldID
`returns:`	EAIFieldValue
`errors:`	EAI_INVALID_ACCESS_TYPE
`events:`	None
`buffered:`	No

Get the value represented by this field as it exists in the world. This will represent the current value of the field at the time of the request. If the request is made of a field that has a setValue request buffered through begin update, the value returned shall be the old value prior to the setValue request. The value of the field may be a NODE if the field represents an MFNode or SFNode.

6.5.6 setValue

`parameters:`	EAINodeID, EAIFieldID, EAIFieldValue
`returns:`	None
`errors:`	EAI_INVALID_ACCESS_TYPE
`events:`	None
`buffered:`	Yes

Set the value of this field. Set requests shall obey the requirements as specified the buffer_events service.

The value of the field may be a NODE if the field represents an MFNode or SFNode. It is permitted to send a null to a node or field in order to clear the value from that field. For example sending a null to the appearance eventIn of a Shape (ISO/IEC 14772-1 6.41 Shape) node shall result in the appearance field being cleared and set to the default value of NULL.

6.5.7 Register Field Interest

`parameters:`	EAINodeID, EAIFieldID, EAIAction, EAIRequesterID
`returns:`	None
`errors:`	EAI_INVALID_ACCESS_TYPE
`events:`	EAIFieldEvent
`buffered:`	No

This service nominates the requester as the receiver of all EAIFieldEvents. The act of making this service request itself does not imply any events shall be generated.

The parameter of type EAIRequesterID could be inferred from the source of the input and may not need to be part of the parameters.

The parameter of type EAIAction specifies whether this is a request to add interest in events, or to remove interest in the events.

What capabilities are permitted to be listened to are implementation dependent. For example, some implementations may permit listening to eventIn values and eventOut values while others will only permit eventOut values to be listened to.

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