Escolher e salvar tons usando o esquema de URI ms-tonepicker

  • Artigo

Este tópico descreve como usar o esquema de URI ms-tonepicker:. Esse esquema de URI pode ser usado para:

  • Determinar se o seletor de tom está disponível no dispositivo.
  • Exibir o seletor de tom para listar toques, sons do sistema, tons de texto e sons de alarme disponíveis; e obter um token de tom que representa o som que o usuário selecionou.
  • Exibir o protetor de tom, que usa um token de arquivo de som como entrada e salva-o no dispositivo. Os tons salvos estão disponíveis por meio do seletor de tom. Os usuários também podem dar um nome amigável ao tom.
  • Converta um token de tom em seu nome amigável.

Referência de esquema de URI ms-tonepicker:

Esse esquema de URI não passa argumentos via cadeia de caracteres de esquema URI, mas passa argumentos por meio de um ValueSet. Todas as cadeias de caracteres diferenciam maiúsculas de minúsculas.

As seções a seguir indicam quais argumentos devem ser transmitidos para realizar a tarefa especificada.

Tarefa: determinar se o seletor de tom está disponível no 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
}

Tarefa: exibir o seletor de tom

Os argumentos que você pode passar para exibir o seletor de tom são os seguintes:

Parâmetro Type Obrigatório Valores possíveis Descrição
Ação string sim "PickRingtone" Abre o seletor de tom.
CurrentToneFilePath string não Um token de tom existente. O tom a ser exibido como o tom atual no seletor de tom. Se esse valor não for definido, o tom primeiro na lista será selecionado por padrão.
Não, estritamente falando, isso é um caminho de arquivo. Você pode obter um valor adequado para CurrenttoneFilePath do valor ToneToken retornado do seletor de tom.
TypeFilter string não "Toques", "Notificações", "Alarmes", "None" Seleciona quais tons serão adicionados ao seletor. Se nenhum filtro for especificado, todos os tons serão exibidos.

Valores que são retornados em LaunchUriResults.Result:

Valores retornados Tipo Valores possíveis Descrição
Resultado Int32 0 = êxito.
1 = cancelado.
7 = parâmetros inválidos.
8 = nenhum tom corresponde aos critérios de filtro.
255 = a ação especificada não foi implementada.		 O resultado da operação de seletor.
ToneToken string Token do tom selecionado.
A cadeia de caracteres ficará vazia se o usuário selecionar padrão no seletor.		 Esse token pode ser usado em uma carga de notificação do sistema, ou pode ser atribuído como toque ou tom do texto de um contato. O parâmetro será retornado no ValueSet somente se Resultado for 0.
DisplayName string Nome amigável do tom especificado. Uma cadeia de caracteres que pode ser exibida ao usuário para representar o tom selecionado. O parâmetro será retornado no ValueSet somente se Resultado for 0.

Exemplo: abrir o seletor de tom para que o usuário possa selecionar um tom

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
     }
}

Tarefa: exibir o protetor de tom

Os argumentos que você pode passar para exibir o protetor de tom são os seguintes:

Parâmetro Type Obrigatório Valores possíveis Descrição
Ação string sim "SaveRingtone" Abre o seletor para salvar um toque.
ToneFileSharingToken string sim Token de compartilhamento de arquivo SharedStorageAccessManager para o arquivo de toque a ser salvo. Salva um arquivo de som específico como um toque. Os tipos de conteúdo com suporte para o arquivo são áudio mpeg e áudio x-ms-wma.
DisplayName string não Nome amigável do tom especificado. Define o nome de exibição a ser usado ao salvar o toque especificado.

Valores que são retornados em LaunchUriResults.Result:

Valores retornados Tipo Valores possíveis Descrição
Resultado Int32 0 = êxito.
1 = cancelado pelo usuário.
2 = arquivo inválido.
3 = tipo de conteúdo de arquivo inválido.
4 = o arquivo excede o tamanho máximo de toque (1 MB no Windows 10).
5 = o arquivo excede o limite de duração de 40 segundos.
6 = o arquivo está protegido pelo gerenciamento de direitos digitais.
7 = parâmetros inválidos.		 O resultado da operação de seletor.

Exemplo: salvar um arquivo de música local como um toque

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;
          }
      }
 }

Tarefa: converter um token de tom em seu nome amigável

Os argumentos que você pode passar para obter o nome amigável de um tom são os seguintes:

Parâmetro Type Obrigatório Valores possíveis Descrição
Ação string sim "GetToneName" Indica que você deseja obter o nome amigável de um tom.
ToneToken string sim O token de tom O token de tom de onde obter um nome de exibição.

Valores que são retornados em LaunchUriResults.Result:

Valor retornado Type Valores possíveis Descrição
Resultado Int32 0 = operação de seletor bem-sucedida.
7 = parâmetro incorreto (por exemplo, nenhum ToneToken fornecido).
9 = erro ao ler o nome do token especificado.
10 = não é possível encontrar o token de tom especificado.		 O resultado da operação de seletor.
DisplayName string Nome amigável do tom. Retorna o nome de exibição do tom selecionado. Esse parâmetro será retornado no ValueSet somente se Resultado for 0.

Exemplo: recuperar um token de tom de Contact.RingToneToken e exibir o nome amigável no cartão de visita.

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
        }
    }
}