Rinviare gli aggiornamenti del dispositivoDefer device updates

Un'applicazione di alto livello può rinviare temporaneamente gli aggiornamenti del sistema operativo Azure Sphere e delle immagini dell'applicazione per evitare che provochino l'interruzione di processi critici.A high-level application can temporarily defer updates to the Azure Sphere OS and to application images to prevent the update from interrupting critical processing. Un dispositivo Azure Sphere in un elettrodomestico, ad esempio, può rinviare gli aggiornamenti se in uso.An Azure Sphere device in a kitchen appliance, for example, could defer updates during use. Per poter rinviare gli aggiornamenti, l'app esegue la registrazione per le notifiche di aggiornamento.To have the opportunity to defer updates, the app registers for update notifications. Dopo il download dell'aggiornamento, il sistema operativo invia una notifica all'applicazione, che può visualizzare informazioni dettagliate sull'aggiornamento e richiedere il rinvio.After the OS downloads the update, it notifies the application, which can get details about the update and request deferral.

L'esempio Deferred Update mostra come usare un ciclo di eventi e gli eventi di sistema per posticipare gli aggiornamenti.The Deferred Update sample shows how to use an event loop and system events to defer updates.

Le applicazioni con funzionalità in tempo reale (RTApps) non possono ricevere notifiche di aggiornamento o richiedere rinvii.Real-time capable applications (RTApps) cannot receive update notifications or request deferrals. Spetta a un'app di alto livello gestire il rinvio degli aggiornamenti per conto di un'applicazione RTApps nel dispositivo.A high-level app is responsible for managing update deferral on behalf of RTApps on the device.

Requisiti per il rinvioDeferral requirements

Le applicazioni che posticipano gli aggiornamenti devono includere i file di intestazione appropriati e aggiungere le impostazioni di rinvio al manifesto dell'applicazione.Applications that defer updates must include the appropriate header files and add deferral settings to the application manifest.

File di intestazioneHeader files

Includere nel progetto le intestazioni eventloop e sysevent:Include the eventloop and sysevent headers in your project:

 #include <applibs/eventloop.h>
 #include <applibs/sysevent.h>

Impostazioni del manifesto dell'applicazioneApplication manifest settings

Per ricevere notifiche sugli eventi di aggiornamento software e per avere la possibilità di rinviare tali aggiornamenti, un'applicazione include due funzionalità nel file manifesto dell'applicazione:To be notified about software update events and to have the opportunity to defer such updates, an application includes two capabilities in the application manifest file:

  • SystemEventNotificationsSystemEventNotifications
  • SoftwareUpdateDeferralSoftwareUpdateDeferral

Impostare il campo SystemEventNotifications su true nel file app_manifest.json per ricevere le notifiche degli eventi di aggiornamento del sistema.Set the SystemEventNotifications field to true in the app_manifest.json file to receive notifications of system update events. L'applicazione deve anche eseguire la registrazione per le notifiche degli eventi come descritto nella sezione Meccanismo di notifica.The application must also register for event notifications, as described in Notification mechanism. Impostare SoftwareUpdateDeferral su true per abilitare l'app a rinviare e riprendere gli aggiornamenti.Set SoftwareUpdateDeferral to true to enable the app to defer and resume updates.

Di seguito sono illustrate le impostazioni di app_manifest.json necessarie per abilitare la notifica e il rinvio:The following shows the app_manifest.json settings required to enable both notification and deferral:

"Capabilities": {
        "SystemEventNotifications" : true,
        "SoftwareUpdateDeferral" : true
    }

Meccanismo di notificaNotification mechanism

Azure Sphere supporta il rinvio degli aggiornamenti tramite un meccanismo di notifica e ciclo degli eventi.Azure Sphere supports update deferral through an event notification and event loop mechanism. L'applicazione crea un oggetto EventLoop, ovvero un oggetto a thread singolo attraverso il quale l'applicazione riceve una notifica degli eventi in sospeso.The application creates an EventLoop, which is a single-threaded object through which the application is notified of pending events.

Per ricevere le notifiche, un'app chiama SysEvent_RegisterForEventNotifications passando i parametri seguenti:To receive notifications, an app calls SysEvent_RegisterForEventNotifications, passing these parameters:

  • Un puntatore al ciclo di eventiA pointer to the event loop
  • eventBitmask che specifica gli eventi per cui l'app richiede la notificaAn eventBitmask that specifies the events for which the app requests notification
  • Un puntatore a una funzione di callback definita dall'appA pointer to an app-defined callback function
  • Un puntatore di contesto facoltativo che viene passato al callbackAn optional context pointer that is passed to the callback

Con SysEvent_RegisterForEventNotifications è possibile usare un solo oggetto EventLoop per ogni thread.Only one EventLoop object can be used with SysEvent_RegisterForEventNotifications per thread. Una seconda chiamata a SysEvent_RegisterForEventNotifications con un oggetto EventLoop diverso avrà esito negativo.A second call to SysEvent_RegisterForEventNotifications with a different EventLoop object will fail.

Dopo la registrazione, l'applicazione chiama EventLoop_Run, che richiama la funzione di callback se lo stato di un evento è cambiato.After registration, the application calls EventLoop_Run, which invokes the callback function if an event has changed status. La funzione di callback riceve un valore di SysEvent_Events, che identifica il tipo di evento.The callback function receives a SysEvent_Events value, which identifies the type of event. A sua volta, il callback chiama SysEvent_Info_GetUpdateData per verificare se l'evento è un aggiornamento del sistema operativo o dell'applicazione e per stabilire per quanto tempo è possibile rinviare l'aggiornamento.In turn, the callback calls SysEvent_Info_GetUpdateData to find out whether the event is an OS or application update and how long the update can be deferred. L'app può quindi determinare come gestire la notifica degli eventi.The app can then determine how to handle the event notification.

Azure Sphere può inviare diverse notifiche di stato per ogni evento di aggiornamento:Azure Sphere may send several status notifications for each update event:

StatoStatus DescrizioneDescription
SysEvent_Status_PendingSysEvent_Status_Pending Avviso di 10 secondi che indica che si verificherà un evento di aggiornamento con la possibilità di rinviarlo.A 10-second warning that an update event will occur, with the opportunity to defer.
SysEvent_Status_FinalSysEvent_Status_Final Avviso di 10 secondi che indica che si verificherà un evento di aggiornamento senza la possibilità di rinviarlo.A 10-second warning that an update event will occur, without the opportunity for deferral.
SysEvent_Status_DeferredSysEvent_Status_Deferred L'evento precedentemente in sospeso è stato rinviato e verrà eseguito in un secondo momento.The previously pending event has been deferred and will occur later.
SysEvent_Status_CompleteSysEvent_Status_Complete Il processo di aggiornamento del software è stato completato.The software update process is complete. Questa notifica degli eventi viene inviata solo per gli aggiornamenti dell'applicazione.This event notification is sent only for application updates.

Un'app può richiedere il rinvio solo dopo aver ricevuto una notifica SysEvent_Status_Pending.An app can request deferral only after it receives a SysEvent_Status_Pending notification. Per consentire l'esecuzione immediata dell'aggiornamento, l'applicazione può ignorare la notifica.To allow the update to occur immediately, the application can ignore the notification.

Per rinviare l'aggiornamento, l'applicazione chiama SysEvent_DeferEvent passando il numero di minuti di rinvio dell'aggiornamento.To defer the update, the application calls SysEvent_DeferEvent, passing the number of minutes to defer the update. Per un aggiornamento del sistema operativo, il rinvio massimo è di 1440 minuti (24 ore).For an OS update, the maximum deferral is 1440 minutes (24 hours). Per un aggiornamento dell'applicazione, il periodo di rinvio massimo è di 10.020 minuti (167 ore).For an application update, the maximum deferral period is 10,020 minutes (167 hours).

Un'applicazione può terminare il rinvio di un aggiornamento in modo anomalo chiamando SysEvent_ResumeEvent.An application can end an update deferral prematurely by calling SysEvent_ResumeEvent. Per un aggiornamento dell'applicazione o del sistema operativo, una chiamata riuscita a SysEvent_ResumeEvent riavvia il processo di notifica e invia quindi un nuova notifica SysEvent_Status_Pending .For an application or OS update, a successful call to SysEvent_ResumeEvent restarts the notification process and thus sends a new SysEvent_Status_Pending notification. L'app non deve chiamare nuovamente SysEvent_DeferEvent fino a quando non riceve una notifica di questo tipo.The app should not call SysEvent_DeferEvent again until it has received such a notification.

Quando l'applicazione riceve la notifica di SysEvent_Status_Final , deve prepararsi a ricevere un segnale SIGTERM dal sistema operativo Azure Sphere.When the application receives the SysEvent_Status_Final notification, it should prepare to receive a SIGTERM signal from the Azure Sphere OS. Quando viene ricevuto il segnale SIGTERM, l'app deve eseguire la pulizia e l'uscita finali.When the SIGTERM signal is received, the app should perform final cleanup and exit. L'applicazione non deve essere chiusa prima della ricezione del SIGTERM. in caso contrario, potrebbe essere riavviato prima dell'invio del SIGTERM.The application should not exit before the SIGTERM is received; otherwise, it could be restarted before the SIGTERM is sent. Per un aggiornamento del sistema operativo, l'applicazione deve eseguire tutte le operazioni di pulizia necessarie prima del riavvio del dispositivo.For an OS update, the application should do whatever cleanup is required before device reboot. Per un aggiornamento dell'applicazione, l'applicazione di alto livello deve eseguire tutte le operazioni necessarie prima che venga riavviata qualsiasi applicazione nel dispositivo.For an application update, the high-level application should do whatever is necessary before it or any other application on the device is restarted. La notifica dell'applicazione attualmente non specifica l'applicazione da aggiornare.Application notification does not currently specify which application is being updated.

Quando la notifica non è più necessaria, l'app deve chiamare SysEvent_UnregisterForEventNotifications e quindi EventLoop_Close per rilasciare la memoria allocata per l'oggetto ciclo di eventi.When notification is no longer required, the app should call SysEvent_UnregisterForEventNotifications and then EventLoop_Close to release the memory allocated for the event loop object. Si noti che dopo aver annullato la registrazione di tutte le notifiche degli eventi, l'app può usare un nuovo oggetto EventLoop.Note that after all event notifications have been unregistered, the app can use a new EventLoop object.