These are the proposed changes to the geolocation API specifications. The new getAddress() functional specification is detailed below, and the new mailing address data structure is modeled off of the xAL (Extensible Address Language) v2.0 specifications located here. The full downloadable CIQ specifications (including the xAL specification) can be located here. There are also references within this article to some of the current objects from the current W3C Geolocation API, located here.
[NoInterfaceObject]
interface Address {
readonly attribute DOMString? country;
readonly attribute DOMString? adminArea;
readonly attribute DOMString? subAdminArea;
readonly attribute DOMString? locality;
readonly attribute DOMString? subLocality;
readonly attribute DOMString? thoroughfare;
readonly attribute DOMString? subThoroughfare;
readonly attribute DOMString? premises;
readonly attribute DOMString? postalCode;
readonly attribute DOMString? featureName;
};
The country attribute is specified using the two-letter [ISO 3166-1] code.
The adminArea denotes the name of a country subdivision (e.g. state or province name).
The subAdminArea denotes the name of a land area within an administration area (e.g. district or county name)
The locality attribute reflects the name of a locality (e.g. city or town name)
The subLocality denotes any additional locality-level information (e.g. ward or subdivision name)
The thoroughfare reflects an available street address (e.g. For the street-level address “650 Castro Street”, the thoroughfare would have the value “Castro Street”)
The subThoroughfare denotes any additional street-level information (e.g. For the street-level address “650 Castro Street”, the subThoroughfare would have the value “650”)
The premises describes any available detailed address information (e.g. building, block, unit or apartment number)
The postalCode reflects the postal code for the address (e.g. zip or postal code).
The featureName denotes any named feature about this address (e.g. The Golden Gate Bridge)
[Callback, NoInterfaceObject]
interface AddressOptions {
attribute long timeout;
};
The timeout attribute denotes the maximum length of time (expressed in milliseconds) that is allowed to pass during the address acquisition operation from the call to getAddress() until the corresponding successCallback is invoked. If the implementation is unable to successfully acquire a new Address before the given timeout elapses, and no other errors have occurred in this interval, then the corresponding errorCallback must be invoked with an AddressError object whose code attribute is set to TIMEOUT. Note that the time that is spent obtaining the user permission is not included in the period covered by the timeout attribute.
[Callback, NoInterfaceObject]
interface AddressCallback {
void handleEvent(in Address address);
};
[Callback, NoInterfaceObject]
interface AddressErrorCallback {
void handleEvent(in AddressError error);
};
[NoInterfaceObject]
interface AddressError {
const unsigned short PERMISSION_DENIED = 1;
const unsigned short ADDRESS_UNAVAILABLE = 2;
const unsigned short TIMEOUT = 3;
readonly attribute unsigned short code;
readonly attribute DOMString message;
};
void getAddress(in Coordinates coords,
in AddressCallback successCallback,
in optional AddressErrorCallback errorCallback,
in optional AddressOptions options);
The getAddress() method takes two, three or four arguments. When called, it must immediately return and then asynchronously attempt to obtain the current physical mailing address of the location provided from the coords parameter of type Coordinates. If the attempt is successful, the successCallback must be invoked (i.e. the handleEvent operation must be called on the callback object) with a new Address object, reflecting the associated physical mailing address at the location of the coords parameter. If the attempt fails, the errorCallback must be invoked with a new AddressError object, reflecting the reason for the failure.
The implementation of the getAddress method should execute the following set of steps:
1. Run the following pre-processing steps:
1. If successCallback is the null value, then throw a TypeError. This matches a failed type conversion in WebIDL. See step 5 in section 4.1.15 in [WEBIDL].
2. If a AddressOptions parameter was present, and its timeout attribute was defined to a non-negative value, assign this value to an internal timeout variable. If timeout was defined to a negative value, set the internal timeout variable to 0. If timeout was not specified, set the internal timeout variable to Infinity.
2. If a cached Address object is available for this location, invoke the successCallback with the cached Address object as a parameter and exit this set of steps.
3. If the value of the timeout variable is 0, invoke the errorCallback (if present) with a new AddressError object whose code attribute is set to TIMEOUT and exit this set of steps.
4. Start an address acquisition operation (e.g. by invoking a platform-specific API).
5. Start a timer that will fire after the number of milliseconds denoted by the value of the timeout variable. When the timer fires, cancel any ongoing address acquisition operations associated with this instance of the steps, invoke the errorCallback (if present) with a new AddressError object whose code attribute is set to TIMEOUT, and exit this set of steps.
6. If the operation completes successfully before the timeout expires, cancel the pending timer, invoke the successCallback with a new Address object that reflects the result of the acquisition operation and exit this set of steps. The success criteria includes providing non-null values for all relevant attributes of the Address object.
7. If the operation fails before the timeout expires, cancel the pending timer and invoke the errorCallback (if present) with a new AddressError object whose code is set to ADDRESS_UNAVAILABLE.
