Scegliere e salvare toni usando lo schema URI ms-tonepicker

  • Articolo

Questo argomento descrive come usare lo schema URI ms-tonepicker:. Questo schema URI può essere usato per:

  • Determinare se la selezione toni è disponibile nel dispositivo.
  • Visualizza la selezione toni per elencare suonerie disponibili, suoni di sistema, toni di testo e suoni alla sveglia; e ottenere un token di tono che rappresenta il suono selezionato dall'utente.
  • Visualizzare il risparmio tono, che accetta un token di file audio come input e lo salva nel dispositivo. I toni salvati sono quindi disponibili tramite la selezione tono. Gli utenti possono anche assegnare un nome descrittivo al tono.
  • Convertire un token di tono nel nome descrittivo.

ms-tonepicker: riferimento allo schema URI

Questo schema URI non passa argomenti tramite la stringa dello schema URI, ma passa invece argomenti tramite ValueSet. Tutte le stringhe fanno distinzione tra maiuscole e minuscole.

Le sezioni seguenti indicano quali argomenti devono essere passati per eseguire l'attività specificata.

Attività: determinare se la selezione tono è disponibile nel dispositivo

var status = await Launcher.QueryUriSupportAsync(new Uri("ms-tonepicker:"),     
                                     LaunchQuerySupportType.UriForResults,
                                     "Microsoft.Tonepicker_8wekyb3d8bbwe");

if (status != LaunchQuerySupportStatus.Available)
{
    // the tone picker is not available
}

Attività: visualizzare la selezione tono

Gli argomenti che è possibile passare per visualizzare la selezione tono sono i seguenti:

Parametro Type Obbligatorio Possibili valori Descrizione
Azione string yes "PickRingtone" Apre la selezione tono.
CurrentToneFilePath string no Token di tono esistente. Tono da mostrare come tono corrente nella selezione tono. Se questo valore non è impostato, per impostazione predefinita viene selezionato il primo tono nell'elenco.
Questo non è, in senso stretto, un percorso di file. È possibile ottenere un valore appropriato per CurrenttoneFilePath dal valore ToneToken restituito dalla selezione toni.
TypeFilter string no "Suonerie", "Notifiche", "Allarmi", "Nessuno" Seleziona i toni da aggiungere alla selezione. Se non viene specificato alcun filtro, vengono visualizzati tutti i toni.

Valori restituiti in LaunchUriResults.Result:

Valori restituiti Type Possibili valori Descrizione
Risultato Int32 0-riuscito.
1-annullato.
7-parametri non validi.
8 - nessun tono corrisponde ai criteri di filtro.
255 - l'azione specificata non viene implementata.		 Risultato dell'operazione del picker.
ToneToken string Token del tono selezionato.
La stringa è vuota se l'utente seleziona l'impostazione predefinita nella selezione.		 Questo token può essere usato in un payload di notifica di tipo avviso popup oppure può essere assegnato come suoneria o tono di testo di un contatto. Il parametro viene restituito in ValueSet solo se Result è 0.
DisplayName string Nome descrittivo del tono specificato. Una stringa che può essere mostrata all'utente per rappresentare il tono selezionato. Il parametro viene restituito in ValueSet solo se Result è 0.

Esempio: aprire la selezione toni in modo che l'utente possa selezionare un tono

LauncherOptions options = new LauncherOptions();
options.TargetApplicationPackageFamilyName = "Microsoft.Tonepicker_8wekyb3d8bbwe";

ValueSet inputData = new ValueSet() {
    { "Action", "PickRingtone" },
    { "TypeFilter", "Ringtones" } // Show only ringtones
};

LaunchUriResult result = await Launcher.LaunchUriForResultsAsync(new Uri("ms-tonepicker:"), options, inputData);

if (result.Status == LaunchUriStatus.Success)
{
     Int32 resultCode =  (Int32)result.Result["Result"];
     if (resultCode == 0)
     {
         string token = result.Result["ToneToken"] as string;
         string name = result.Result["DisplayName"] as string;
     }
     else
     {
           // handle failure
     }
}

Attività: visualizzare il risparmio tono

Gli argomenti che è possibile passare per visualizzare in risparmio tono sono i seguenti:

Parametro Type Obbligatorio Possibili valori Descrizione
Azione string yes "SaveRingtone" Apre il selettore per salvare una suoneria.
ToneFileSharingToken string yes Token di condivisione file SharedStorageAccessManager per il file suoneria da salvare. Salva un file audio specifico come suoneria. I tipi di contenuto supportati per il file sono audio mpeg e audio x-ms-wma.
DisplayName string no Nome descrittivo del tono specificato. Imposta il nome visualizzato da utilizzare quando si salva la suoneria specificata.

Valori restituiti in LaunchUriResults.Result:

Valori restituiti Type Possibili valori Descrizione
Risultato Int32 0-riuscito.
1-annullata dall'utente.
2-File non valido.
3-Tipo di contenuto del file non valido.
4-Il file supera la dimensione massima della suoneria (1 MB in Windows 10).
5-Il file supera il limite di lunghezza di 40 secondi.
6-Il file è protetto da Digital Rights Management.
7-parametri non validi.		 Risultato dell'operazione del picker.

Esempio: Salvare un file musicale locale come suoneria

LauncherOptions options = new LauncherOptions();
options.TargetApplicationPackageFamilyName = "Microsoft.Tonepicker_8wekyb3d8bbwe";

ValueSet inputData = new ValueSet() {
    { "Action", "SaveRingtone" },
    { "ToneFileSharingToken", SharedStorageAccessManager.AddFile(myLocalFile) }
};

LaunchUriResult result = await Launcher.LaunchUriForResultsAsync(new Uri("ms-tonepicker:"), options, inputData);

if (result.Status == LaunchUriStatus.Success)
{
     Int32 resultCode = (Int32)result.Result["Result"];

     if (resultCode == 0)
     {
         // no issues
     }
     else
     {
          switch (resultCode)
          {
             case 2:
              // The specified file was invalid
              break;
              case 3:
              // The specified file's content type is invalid
              break;
              case 4:
              // The specified file was too big
              break;
              case 5:
              // The specified file was too long
              break;
              case 6:
              // The file was protected by DRM
              break;
              case 7:
              // The specified parameter was incorrect
              break;
          }
      }
 }

Attività: convertire un token di tono nel nome descrittivo.

Gli argomenti che è possibile passare per ottenere il nome descrittivo di un tono sono i seguenti:

Parametro Type Obbligatorio Possibili valori Descrizione
Azione string yes "GetToneName" Indica che si vuole ottenere il nome descrittivo di un tono.
ToneToken string yes Il token del tono Token di tono da cui ottenere un nome visualizzato.

Valori restituiti in LaunchUriResults.Result:

Valore restituito Type Possibili valori Descrizione
Risultato Int32 0-Operazione di selezione completata.
7-Parametro non corretto (ad esempio, nessun ToneToken specificato).
9-Errore durante la lettura del nome del token specificato.
10-Impossibile trovare il token di tono specificato.		 Risultato dell'operazione del picker.
DisplayName string Nome descrittivo del tono. Restituisce il nome visualizzato del tono selezionato. Questo parametro viene restituito solo in ValueSet solo se Result è 0.

Esempio: recuperare un token di tono da Contact.RingToneToken e visualizzarne il nome descrittivo nella scheda contatto.

using (var connection = new AppServiceConnection())
{
    connection.AppServiceName = "ms-tonepicker-nameprovider";
    connection.PackageFamilyName = "Microsoft.Tonepicker_8wekyb3d8bbwe";
    AppServiceConnectionStatus connectionStatus = await connection.OpenAsync();
    if (connectionStatus == AppServiceConnectionStatus.Success)
    {
        var message = new ValueSet() {
            { "Action", "GetToneName" },
            { "ToneToken", token)
        };
        AppServiceResponse response = await connection.SendMessageAsync(message);
        if (response.Status == AppServiceResponseStatus.Success)
        {
            Int32 resultCode = (Int32)response.Message["Result"];
            if (resultCode == 0)
            {
                string name = response.Message["DisplayName"] as string;
            }
            else
            {
                // handle failure
            }
        }
        else
        {
            // handle failure
        }
    }
}