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.
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. Table 6.2 contains three columns: the first column specifies each characteristic type, the second column defines the characteristics type, and the third column defines the properties of that characteristic.
Table 6.2 — Characteristics types
|
Characteristic Type |
Definition |
Properties |
|
parameters: |
The list of values that are required in order to complete a service request. These values may take any form as required by the particular language binding. |
first parameter data type, second parameter, [optional parameter data type] |
|
returns: |
Immediate, synchronous values that are passed back to the external application upon completion of a service request. The request is blocked until these values are sent, if specified. |
The list of return values data types or expected ranges |
|
errors: |
Error conditions that can be generated as part of a service invocation. Errors are fatal for the service request issuing the error. No return value shall be generated if an error is generated. Errors are synchronous with the request. |
List of errors data types |
|
events: |
Asynchronous events that are generated to listeners that have registered interest in this particular object (browser or field) resulting in notification to the listener of the event. The listener may not be the same as the caller that generated the event condition. For example, consider two applications registered as browser listeners. One invokes the loadURL service but both will receive shutdown and initialize events. The required event types are defined in 4.5 Events. |
The first event |
|
buffered: |
Indicator to say whether this service request is effected by 6.3.16 Update control |
Yes, No, or Not Applicable (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 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 EAIBrowserRef 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, 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.12 loadURL) or replaceWorld (see 6.3.14 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 EAIBrowserApp 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 titles defined in ISO/IEC 14772-1 4.12.10, Browser script interface. Default values are defined in the appropriate subclause of ISO/IEC 14772-1. A brief description of each service is defined here 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 is not specified in this clause. Actual representations are defined in the language bindings.
6.3.2 createVrmlFromString
|
parameters: |
EAIBrowserRef, EAIString |
|
returns: |
EAINodeID [EAINodeID]s |
|
errors: |
EAI_INVALID_VRML |
|
events: |
None |
|
buffered: |
No |
Create VRML nodes from a string. The string shall contain valid VRML syntax; otherwise an error is generated. If any relative URLs are encountered in this string, 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, 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.3 createVrmlFromURL
|
parameters: |
EAIBrowserRef, EAIURL [EAIURLs], EAINodeID, EAIFieldID |
|
returns: |
None |
|
errors: |
EAI_INVALID_URL |
|
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 scene graph.
The EAIFieldID value shall 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.4 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 generates this event, just that the event is generated). If any events have been held because beginUpdate has been called, disposing of the browser shall also call endUpdate to release those events to the browser.
6.3.5 Dynamic Route Handling
|
parameters: |
EAIBrowserRef, EAINodeID, EAIFieldID, EAINodeID, EAIFieldID, EAIAction |
|
returns: |
None |
|
errors: |
EAI_INVALID_NODE |
|
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 existence of the nominated route. The EAINodeID/EAIFieldID pair parameters are considered 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, 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.16, Update Control), 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 Execution Model are permitted to operate.
6.3.6 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.7 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.8 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.9 getNode
|
parameters: |
EAIBrowserRef, EAIString |
|
returns: |
EAINodeID |
|
errors: |
EAI_INVALID_NAME |
|
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 (see 6.3.12 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 (see 6.3.14 replaceWorld) , an EAI_INVALID_NAME error shall be generated as DEF names are not kept once the load has taken place.
6.3.10 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, a NULL value shall be returned.
6.3.11 getWorldURL
|
parameters: |
EAIBrowserRef |
|
returns: |
EAIURL |
|
errors: |
EAI_URL_UNAVAILABLE
|
|
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 (see 6.3.12 loadURL), the string will reflect the new URL. If replaceWorld (see 6.3.14 replaceWorld) is called, the URL still represents the original world.
6.3.12 loadURL
|
parameters: |
EAIBrowserRef, EAIURL [EAIURL]s, EAIPropertyList |
|
returns: |
None |
|
errors: |
EAI_INVALID_URL
|
|
events: |
EAI_B_Shutdown |
|
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 an 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, 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 (see 6.3.14 replaceWorld) or loadURL (see 6.3.12 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 initialize event shall be generated at the point where the world is ready to be run if replaceWorld was called.
6.3.13 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 shall be made independent of the method of communicating with the browser.
As a minimum, a conforming implementation shall provide the events defined in 4.5.3, Browser to External Application.
6.3.14 replaceWorld
|
parameters: |
EAIBrowserRef, EAINodeID [EAINodeID]s |
|
returns: |
None |
|
errors: |
EAI_INVALID_NODE |
|
events: |
EAI_B_Shutdown |
|
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 (see 6.3.14 replaceWorld) or loadURL (see 6.3.12 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 initialize event shall be generated at the point where the world is ready to be run.
6.3.15 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.16 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 scene graph. A call to end update without a previous matching begin update has no effect.
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 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 scene graph (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 scene graph structures contain references to this node and the responsibility and timing for this action is browser implementation specific.
6.4.3 getField
|
parameters: |
EAINodeID, EAIFieldName |
|
returns: |
EAIFieldID |
|
errors: |
EAI_INVALID_NAME |
|
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, 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.4 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, the name returned is the name of the PROTO declaration.
6.4.5 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.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 shall 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 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.4 getType
|
parameters: |
EAINodeID, EAIFieldID |
|
returns: |
EAIFieldType |
|
errors: |
None |
|
events: |
None |
|
buffered: |
No |
The type of the field is implementation dependent.
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 beginUpdate, 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 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.
6.5.7 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.
