Escolher e salvar 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:
- 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
}
}
}