Compartilhar via

Escolha e salve tons usando o esquema de URI ms-tonepicker

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

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

ms-tonepicker: referência ao esquema de URI

Esse esquema de URI não passa argumentos por meio da cadeia de caracteres do esquema URI, mas passa argumentos por meio de um ValueSet. Todas as cadeias de caracteres são sensíveis a maiúsculas e minúsculas.

As seções abaixo indicam quais argumentos devem ser passados 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 Tipo Obrigatório Valores possíveis Descrição
Ação corda Sim "PickRingtone" Abre o seletor de tom.
CurrentToneFilePath corda Não Um token de tom existente. O tom a ser exibido como o tom atual no seletor de tons. Se esse valor não estiver definido, o primeiro tom da lista será selecionado por padrão.
Este não é, estritamente falando, um caminho de arquivo. Você pode obter um valor apropriado para CurrenttoneFilePath a partir do valor de ToneToken retornado pelo seletor de tom.
Filtro de Tipo corda Não "Toques", "Notificações", "Alarmes", "Nenhum" Seleciona quais tons adicionar ao seletor. Se nenhum filtro for especificado, todos os tons serão exibidos.

Os valores retornados no LaunchUriResults.Result:

Valores retornados Tipo Valores possíveis Descrição
Resultado Int32 0-êxito.
1 cancelado.
Parâmetros inválidos 7.
8 – nenhum tom corresponde aos critérios de filtro.
255 – a ação especificada não é implementada.		 O resultado da operação do seletor.
ToneToken corda O token do tom selecionado.
A cadeia de caracteres estará 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 de texto de um contato. O parâmetro será retornado no ValueSet somente se Result for 0.
Nome Visível corda O nome amigável do tom especificado. Uma cadeia de caracteres que pode ser mostrada ao usuário para representar o tom selecionado. O parâmetro será retornado no ValueSet somente se Result for 0.

Exemplo: abra 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 recurso de salvamento de tom são os seguintes:

Parâmetro Tipo Obrigatório Valores possíveis Descrição
Ação corda Sim "SaveRingtone" Abre o seletor de toques para salvar um toque.
ToneFileSharingToken corda Sim token de compartilhamento de arquivo sharedStorageAccessManager para salvar o arquivo de toque. 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.
Nome Visível corda Não O nome amigável do tom especificado. Define o nome de exibição a ser usado ao salvar o toque definido.

Os valores retornados no 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.
Arquivo 4 excede o tamanho máximo de toque (1 MB no Windows 10).
5-Arquivo excede o limite de comprimento de 40 segundos.
O arquivo 6 é protegido pelo gerenciamento de direitos digitais.
Parâmetros inválidos 7.		 O resultado da operação do seletor.

Exemplo: Salvar um arquivo de música local como o 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 Tipo Obrigatório Valores possíveis Descrição
Ação corda Sim "GetToneName" Indica que você deseja obter o nome amigável de um tom.
ToneToken corda Sim O token de tom O token de tom a partir do qual se obtém um nome de exibição.

Os valores retornados no LaunchUriResults.Result:

Valor de retorno Tipo Valores possíveis Descrição
Resultado Int32 0-A operação do seletor foi 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 localizar o token de tom especificado.		 O resultado da operação do seletor.
Nome Visível corda O nome amigável do tom. Retorna o nome de exibição do tom selecionado. Esse parâmetro só será retornado no ValueSet se Result for 0.

Exemplo: recupere um token de tom de Contact.RingToneToken e exiba seu 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
        }
    }
}