通过

使用 ms-tonepicker URI 方案选择并保存音调

本主题介绍如何使用 ms-tonepicker： URI 结构。 此 URI 方案可用于：

  • 确定音调选取器是否在设备上可用。
  • 显示音调选取器，列出可用的铃声、系统声音、文本音调和警报声音;并获取表示用户选择的声音的音调标记。
  • 显示音调保存器，它将声音文件令牌作为输入，并将其保存到设备。 然后，可以通过音调选取器获取保存的音调。 用户还可以为语气命名一个友好的名称。
  • 将音调标记转换为其友好名称。

ms-tonepicker: URI 协议参考

此 URI 方案不通过 URI 方案字符串传递参数，而是通过 ValueSet传递参数。 所有字符串都区分大小写。

以下各节指示应传递哪些参数来完成指定的任务。

任务：确定音调选取器是否在设备上可用

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

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

任务：显示音调选取器

可以传递以显示音调选取器的参数如下所示：

参数 类型 必选 可能的值 DESCRIPTION
行动 字符串 是的 “PickRingtone” 打开音调选取器。
当前音调文件路径 字符串 否 现有的音调标记。 在音调选取器中显示为当前音调的音调。 如果未设置此值，则默认选择列表中的第一个音调。
严格地说，这不是文件路径。 可以从音调选取器返回的 CurrenttoneFilePath 值中获取 ToneToken 的合适值。
类型过滤器 字符串 否 “铃声”、“通知”、“警报”、“无” 选择要在选取器中添加的色调。 如果未指定任何筛选器，则会显示所有色调。

LaunchUriResults.Result中返回的值：

返回值 类型 可能的值 DESCRIPTION
结果 Int32 0成功。
取消-1。
7 个无效的参数。
8 - 没有音调与筛选条件匹配。
255 - 未实现指定的操作。		 选取器操作的结果。
ToneToken 字符串 所选音调的符号。
如果用户在选取器中选择 默认，则字符串为空。		 此令牌可用于 Toast 通知有效负载，也可以分配为联系人的铃声或文本音调。 仅当 结果 为 0 时，才在 ValueSet 中返回该参数。
显示名称 字符串 指定音调的友好名称。 可以向用户显示以表示所选音调的字符串。 仅当 结果 为 0 时，才在 ValueSet 中返回该参数。

示例：打开音调选取器，以便用户可以选择音调

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

任务：显示音调保存器

可以传递以显示音调保存器的参数如下所示：

参数 类型 必选 可能的值 DESCRIPTION
行动 字符串 是的 “SaveRingtone” 打开选取器以保存铃声。
Tone文件共享令牌 字符串 是的 SharedStorageAccessManager 要保存的铃声文件的文件共享令牌。 将特定声音文件另存为铃声。 该文件支持的内容类型是 mpeg 音频和 x-ms-wma 音频。
显示名称 字符串 否 指定音调的友好名称。 设置保存指定铃声时要使用的显示名称。

LaunchUriResults.Result中返回的值：

返回值 类型 可能的值 DESCRIPTION
结果 Int32 0成功。
1-被用户取消。
2-文件无效。
3-文件内容类型无效。
文件 4 超过了 Windows 10 中的最大铃声大小（1MB）。
5 文件超过 40 秒长度限制。
6 文件受数字权限管理保护。
7 个无效的参数。		 选取器操作的结果。

示例：将本地音乐文件另存为铃声

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

任务：将音调标记转换为其友好名称

可以传递以获取音调的友好名称的参数如下所示：

参数 类型 必选 可能的值 DESCRIPTION
行动 字符串 是的 “GetToneName” 表示您想获取一个音调的友好名称。
ToneToken 字符串 是的 音调标记 要从中获取显示名称的音调标记。

LaunchUriResults.Result中返回的值：

返回值 类型 可能的值 DESCRIPTION
结果 Int32 0-选取器操作成功。
7-不正确的参数（例如，未提供 ToneToken）。
9-读取指定令牌的名称时出错。
10 - 找不到指定的音调标记。		 选取器操作的结果。
显示名称 字符串 音调的友好名称。 返回所选音调的显示名称。 仅当 Result 为 0 时，才在 ValueSet 中返回此参数。

示例：从 Contact.RingToneToken 检索音调令牌，并在联系人卡片中显示其友好名称。

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