mozilla

Revision 453281 of Api de Alarma

  • Revision slug: WebAPI/Alarm
  • Revision title: Api de Alarma
  • Revision id: 453281
  • Created:
  • Creator: ccarruitero
  • Is current revision? No
  • Comment

Revision Content

{{ SeeCompatTable() }}

Resumen

La API de Alarma provee acceso a la configuración de alarmas del dispositivo, con la cual se puede programar una notificación o una aplicación para que se inicie en un momento específico. Por ejemplo, algunas aplicaciones, como el despertador, calendario o actualizaciones automáticas necesitan utilizar la API de alarma para activar comportamientos particulares del dispositivo en los tiempos especificados.

Por si mismo, la API de alarmas solo permite programar alarmas. Una alarma es enviada a las aplicaciones a través de la API de mensaje del sistema, entonces las aplicaciones que desean reaccionar a las alarmas tienen que registrarse en los mensajes de alarma.

Las alarmas son establecidas usando el objeto {{domxref("window.navigator.mozAlarms")}}, el cual es una instancia de {{domxref("MozAlarmsManager")}}.

Programar alarmas

Lo primero ha hacer cuando se utiliza alarmas es programar alarmas. Existen dos tipos de alarmas basadas respecto a la zona horaria. En ambos casos se realiza utilizando el método {{domxref("MozAlarmsManager.add")}} .

Nota: Si una alarmar no es dirigida a una aplicación específica, el sistema podría enviar todas las alarmas a todas las aplicaciones que escuchan por alarmas.

Alarmas ignorando zonas horarias

Este tipo de alarmas es enviado basado en la hora local del dispositivo. Si el usuario del dispositivo cambia la zona horaria, la alarma será enviada basada en la nueva zona horaria. Por ejemplo, si un usuario se encuentra en Paris y configura una alarma que debería ser enviada a las 12 PM CET (hora de europa central) y el usuario viaja a San Francisco, la alarma será enviada a las 12 PM PDT (Hora del Pacífico).

// Esta es la fecha a programar la alarma
var myDate  = new Date("May 15, 2012 16:20:00");

// Esta es la información a pasar a la alarma
var data    = {
  foo: "bar"
}

// La cadena "ignoreTimezone" es lo que hace a la alarma ignorar esto
var request = navigator.mozAlarms.add(myDate, "ignoreTimezone", data);

request.onsuccess = function () {
  console.log("La alarma ha sido programada");
};

request.onerror = function () { 
  console.log("Ha ocurrido un error: " + this.error.name);
};

Alarmas respetando zonas horarias

Este tipo de alarmas es enviado basado en la hora en la zona horaria que se definio cuando la alarma fue programada. Si por alguna razón, el usuario del dispositivo cambia su zona horaria, la alarma será enviada basada en la zona horaria original. Por ejemplo, si un usuario se encuentra en Paris y programa una alarma que debería ser enviada a las 12 PM CET (Hora de europa central) y si el usuario viaja a San Francisco, la alarma será enviada a las 3 AM PDT (Hora del Pacífico).

// Esta es la fecha a programar la alarma
var myDate  = new Date("May 15, 2012 16:20:00");

// Esta es la información a pasar a la alarma
var data    = {
  foo: "bar"
}

// La cadena "honorTimezone" es lo que hace a la alarma respetar la zona horaria
var request = navigator.mozAlarms.add(myDate, "honorTimezone", data);

request.onsuccess = function () {
  console.log("La alarma ha sido programada");
};

request.onerror = function () { 
  console.log("Ha ocurrido un error: " + this.error.name);
};

Administrando alarmas

Once an alarm is scheduled, it's still possible to manage it.

The {{domxref("MozAlarmsManager.getAll")}} method will return the complete list of alarms currently scheduled by the application. This list is an Array of {{Anch("mozAlarm")}} objects.

mozAlarm

{{page("/en-US/docs/Web/API/MozAlarmsManager.getAll","mozAlarm")}}

var request = navigator.mozAlarms.getAll();

request.onsuccess = function () {
  this.result.forEach(function (alarm) {
    console.log('Id: ' + alarm.id);
    console.log('date: ' + alarm.date);
    console.log('respectTimezone: ' + alarm.respectTimezone);
    console.log('data: ' + JSON.stringify(alarm.data));
  });
};

request.onerror = function () { 
  console.log("An error occurred: " + this.error.name);
};

The {{domxref("MozAlarmsManager.remove")}} method is used to unschedule an existing alarm.

var alarmId;

// Set an alarm and store it's id
var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "honorTimezone");

request.onsuccess = function () {
  alarmId = this.result.id;
}

// ...

// Later on, removing the alarm if it exists
if (alarmId) {
  navigator.mozAlarms.remove(alarmId);
}

Handling alarms

Any application can react when an alarm is dispatched by the system. In order to be able to handle any alarms, an application must register itself as an alarm handler. This is done through the System Messaging API in two steps:

First, the applications must include alarm to the messages property of its application manifest with the URL to the document which registers the callback function to be used when an alarm is dispatched.

"messages": [
  { "alarm": "/index.html" }
]

Second, the application must bind a callback function with the alarm message. This is done using the {{domxref("window.navigator.mozSetMessageHandler","navigator.mozSetMessageHandler")}} method. This callback function will receive a {{Anch("mozAlarm")}} object containing the data attached to the alarm.

navigator.mozSetMessageHandler("alarm", function (mozAlarm) { 
  alert("alarm fired: " + JSON.stringify(mozAlarm.data)); 
});

If an application wants to know if there is a pending alarm at the system level, it's possible to use the {{domxref("window.navigator.mozHasPendingMessage","navigator.mozHasPendingMessage")}} method with the value alarm.

navigator.mozHasPendingMessage("alarm"); 

Specifications

Specification Status Comment
{{SpecName('Alarm API')}} {{Spec2('Alarm API')}} Initial specification.

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support {{ CompatUnknown()}} {{CompatGeckoDesktop("16")}} {{ property_prefix("moz") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatNo() }} {{CompatGeckoMobile("10")}} {{ property_prefix("moz") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}

See also

  • {{domxref("window.navigator.mozAlarms","navigator.mozAlarms")}}
  • {{domxref("MozAlarmsManager")}}
  • {{domxref("window.navigator.mozSetMessageHandler")}}

Revision Source

<p>{{ SeeCompatTable() }}</p>
<h2 id="Resumen">Resumen</h2>
<p>La <span class="external">API</span> de Alarma provee acceso a la configuración de alarmas del dispositivo, con la cual se puede programar una notificación o una aplicación para que se inicie en un momento específico. Por ejemplo, algunas aplicaciones, como el despertador, calendario o actualizaciones automáticas necesitan utilizar la API de alarma para activar comportamientos particulares del dispositivo en los tiempos especificados.</p>
<p>Por si mismo, la API de alarmas solo permite programar alarmas. Una alarma es enviada a las aplicaciones a través de la API de mensaje del sistema, entonces las aplicaciones que desean reaccionar a las alarmas tienen que registrarse en los mensajes de alarma.</p>
<p>Las alarmas son establecidas usando el objeto {{domxref("window.navigator.mozAlarms")}}, el cual es una instancia de {{domxref("MozAlarmsManager")}}.</p>
<h2 id="example" name="example">Programar alarmas</h2>
<p>Lo primero ha hacer cuando se utiliza alarmas es programar alarmas. Existen dos tipos de alarmas basadas respecto a la zona horaria. En ambos casos se realiza utilizando el método {{domxref("MozAlarmsManager.add")}} .</p>
<div class="note">
  <p><strong>Nota:</strong> Si una alarmar no es dirigida a una aplicación específica, el sistema podría enviar todas las alarmas a todas las aplicaciones que escuchan por alarmas.</p>
</div>
<h3 id="Alarmas_ignorando_zonas_horarias">Alarmas ignorando zonas horarias</h3>
<p>Este tipo de alarmas es enviado basado en la hora local del dispositivo. Si el usuario del dispositivo cambia la zona horaria, la alarma será enviada basada en la nueva zona horaria. Por ejemplo, si un usuario se encuentra en Paris y configura una alarma que debería ser enviada a las 12 PM CET (hora de europa central) y el usuario viaja a San Francisco, la alarma será enviada a las 12 PM PDT (Hora del Pacífico).</p>
<pre class="brush: js">
// Esta es la fecha a programar la alarma
var myDate  = new Date("May 15, 2012 16:20:00");

// Esta es la información a pasar a la alarma
var data    = {
  foo: "bar"
}

// La cadena "ignoreTimezone" es lo que hace a la alarma ignorar esto
var request = navigator.mozAlarms.add(myDate, "ignoreTimezone", data);

request.onsuccess = function () {
  console.log("La alarma ha sido programada");
};

request.onerror = function () { 
  console.log("Ha ocurrido un error: " + this.error.name);
};
</pre>
<h3 id="Alarmas_respetando_zonas_horarias">Alarmas respetando zonas horarias</h3>
<p>Este tipo de alarmas es enviado basado en la hora en la zona horaria que se definio cuando la alarma fue programada. Si por alguna razón, el usuario del dispositivo cambia su zona horaria, la alarma será enviada basada en la zona horaria original. Por ejemplo, si un usuario se encuentra en Paris y programa una alarma que debería ser enviada a las 12 PM CET (Hora de europa central) y si el usuario viaja a San Francisco, la alarma será enviada a las 3 AM PDT (Hora del Pacífico).</p>
<pre class="brush: js">
// Esta es la fecha a programar la alarma
var myDate  = new Date("May 15, 2012 16:20:00");

// Esta es la información a pasar a la alarma
var data    = {
  foo: "bar"
}

// La cadena "honorTimezone" es lo que hace a la alarma respetar la zona horaria
var request = navigator.mozAlarms.add(myDate, "honorTimezone", data);

request.onsuccess = function () {
  console.log("La alarma ha sido programada");
};

request.onerror = function () { 
  console.log("Ha ocurrido un error: " + this.error.name);
};
</pre>
<h2 id="Managing_alarms">Administrando alarmas</h2>
<p>Once an alarm is scheduled, it's still possible to manage it.</p>
<p>The {{domxref("MozAlarmsManager.getAll")}} method will return the complete list of alarms currently scheduled by the application. This list is an <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array" title="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> of {{Anch("mozAlarm")}} objects.</p>
<h3 id="mozAlarm">mozAlarm</h3>
<p>{{page("/en-US/docs/Web/API/MozAlarmsManager.getAll","mozAlarm")}}</p>
<pre class="brush: js">
var request = navigator.mozAlarms.getAll();

request.onsuccess = function () {
  this.result.forEach(function (alarm) {
    console.log('Id: ' + alarm.id);
    console.log('date: ' + alarm.date);
    console.log('respectTimezone: ' + alarm.respectTimezone);
    console.log('data: ' + JSON.stringify(alarm.data));
  });
};

request.onerror = function () { 
  console.log("An error occurred: " + this.error.name);
};
</pre>
<p>The {{domxref("MozAlarmsManager.remove")}} method is used to unschedule an existing alarm.</p>
<pre class="brush: js">
var alarmId;

// Set an alarm and store it's id
var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "honorTimezone");

request.onsuccess = function () {
  alarmId = this.result.id;
}

// ...

// Later on, removing the alarm if it exists
if (alarmId) {
  navigator.mozAlarms.remove(alarmId);
}
</pre>
<h2 id="Handling_alarms">Handling alarms</h2>
<p>Any application can react when an alarm is dispatched by the system. In order to be able to handle any alarms, an application must register itself as an alarm handler. This is done through the System Messaging API in two steps:</p>
<p>First, the applications must include <code>alarm</code> to the <a href="/en-US/docs/Apps/Manifest#messages" title="/en-US/docs/Apps/Manifest#messages">messages property of its application manifest</a> with the URL to the document which registers the callback function to be used when an alarm is dispatched.</p>
<pre class="brush: js">
"messages": [
  { "alarm": "/index.html" }
]</pre>
<p>Second, the application must bind a callback function with the <code>alarm</code> message. This is done using the {{domxref("window.navigator.mozSetMessageHandler","navigator.mozSetMessageHandler")}} method. This callback function will receive a {{Anch("mozAlarm")}} object containing the data attached to the alarm.</p>
<pre class="brush: js">
navigator.mozSetMessageHandler("alarm", function (mozAlarm) { 
  alert("alarm fired: " + JSON.stringify(mozAlarm.data)); 
});
</pre>
<p>If an application wants to know if there is a pending alarm at the system level, it's possible to use the {{domxref("window.navigator.mozHasPendingMessage","navigator.mozHasPendingMessage")}} method with the value <code>alarm</code>.</p>
<pre class="brush: js">
navigator.mozHasPendingMessage("alarm"); 
</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{SpecName('Alarm API')}}</td>
      <td>{{Spec2('Alarm API')}}</td>
      <td>Initial specification.</td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown()}}</td>
        <td>{{CompatGeckoDesktop("16")}} {{ property_prefix("moz") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Chrome for Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{CompatGeckoMobile("10")}} {{ property_prefix("moz") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{domxref("window.navigator.mozAlarms","navigator.mozAlarms")}}</li>
  <li>{{domxref("MozAlarmsManager")}}</li>
  <li>{{domxref("window.navigator.mozSetMessageHandler")}}</li>
</ul>
Revert to this revision