dom/public/idl/geolocation/nsIGeolocationProvider.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Geolocation.
  15  *
  16  * The Initial Developer of the Original Code is Mozilla Corporation
  17  * Portions created by the Initial Developer are Copyright (C) 2008
  18  * the Initial Developer. All Rights Reserved.
  19  *
  20  * Contributor(s):
  21  *  Doug Turner <dougt@meer.net>  (Original Author)
  22  *
  23  * Alternatively, the contents of this file may be used under the terms of
  24  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26  * in which case the provisions of the GPL or the LGPL are applicable instead
  27  * of those above. If you wish to allow use of your version of this file only
  28  * under the terms of either the GPL or the LGPL, and not to allow others to
  29  * use your version of this file under the terms of the MPL, indicate your
  30  * decision by deleting the provisions above and replace them with the notice
  31  * and other provisions required by the GPL or the LGPL. If you do not delete
  32  * the provisions above, a recipient may use your version of this file under
  33  * the terms of any one of the MPL, the GPL or the LGPL.
  34  *
  35  * ***** END LICENSE BLOCK ***** */
  36
  37
  38
  39 #include "nsISupports.idl"
  40
  41 interface nsIURI;
  42 interface nsIDOMWindow;
  43 interface nsIDOMGeoPosition;
  44 interface nsIGeolocationPrompt;
  45
  46 /**
  47  * Interface allows access to a geolocation and is passed to
  48  * the nsIGeolocationPrompt so that the application can approve
  49  * or deny the request.
  50  */
  51 [scriptable, function, uuid(F2AEFDE1-8E38-48B3-BBB8-BD6C4AE1AC8A)]
  52 interface nsIGeolocationRequest : nsISupports {
  53
  54   readonly attribute nsIURI requestingURI;
  55   readonly attribute nsIDOMWindow requestingWindow;
  56
  57   void cancel();
  58   void allow();
  59 };
  60
  61 /**
  62  * Interface provides a way for the application to handle
  63  * the UI prompts associated with geo position.
  64  */
  65 [scriptable, function, uuid(2300C895-1BEE-4297-912C-A57082F3E936)]
  66 interface nsIGeolocationPrompt : nsISupports {
  67   /**
  68    * Called when a request has been made to access geolocation data
  69    */
  70   void prompt(in nsIGeolocationRequest request);
  71 };
  72
  73 /**
  74  * Interface provides a way for a geolocation provider to
  75  * notify the system that a new location is available.
  76  */
  77 [scriptable, uuid(B89D7227-9F04-4236-A582-25A3F2779D72)]
  78 interface nsIGeolocationUpdate : nsISupports {
  79
  80   /**
  81    * Notify the geolocation service that a new geolocation
  82    * has been discovered.
  83    * This must be called on the main thread
  84    */
  85   void update(in nsIDOMGeoPosition position);
  86 };
  87
  88
  89 /**
  90  * Interface provides location information to the nsGeolocator
  91  * via the nsIDOMGeolocationCallback interface.  After
  92  * startup is called, any geo location change should call
  93  * callback.onRequest().
  94  */
  95 [scriptable, uuid(E319BE2D-B1D1-4CA6-AEF4-66178589B63D)]
  96 interface nsIGeolocationProvider : nsISupports {
  97
  98   /**
  99    * Start up the provider.  This is called before any other
 100    * method.  may be called multiple times.
 101    */
 102   void startup();
 103
 104   /**
 105    * Returns true when the devices is ready and has a
 106    * postion, otherwise false.
 107    */
 108    boolean isReady();
 109
 110   /**
 111    * watch
 112    * When a location change is observed, notify the callback
 113    */
 114   void watch(in nsIGeolocationUpdate callback);
 115
 116   /**
 117    * currentLocation return the current location as seen by
 118    * the provider.  may be null.
 119    */
 120   readonly attribute nsIDOMGeoPosition currentPosition;
 121
 122   /**
 123    * shutdown
 124    * Shuts down the location devices.
 125    */
 126   void shutdown();
 127 };
 128
 129 %{C++
 130 /*
 131     This must be implemented by geolocation providers.  It
 132     must support nsIGeolocationProvider.
 133 */
 134 #define NS_GEOLOCATION_PROVIDER_CONTRACTID "@mozilla.org/geolocation/provider;1"
 135
 136 /*
 137     This must be implemented by embedders.  It must support
 138     nsIGeolocationPrompt.
 139 */
 140 #define NS_GEOLOCATION_PROMPT_CONTRACTID   "@mozilla.org/geolocation/prompt;1"
 141 %}