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

项目
07/05/2024

本主题介绍了如何使用 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
}

任务：显示音调选取器

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

参数	类型	必须	可能值	说明
操作	string	是	“PickRingtone”	打开音调选取器。
CurrentToneFilePath	string	否	现有音调标记。	在音调选取器中显示为当前音调的音调。如果未设置此值，默认情况下将选择列表上的第一个音调。严格来讲，这不是文件路径。你可以在从音调选取器中返回的 `ToneToken` 值中，为 `CurrenttoneFilePath` 获取一个适合的值。
TypeFilter	string	否	“Ringtones”、“Notifications”、“Alarms”、“None”	选择要添加到选取器的音调。如果未指定筛选器，将显示所有音调。

在 LaunchUriResults.Result 中返回的值：

返回值	类型	可能值	说明
结果	Int32	0 - 成功。 1 - 已取消。 7 - 参数无效。 8 - 没有匹配筛选条件的音调。 255 - 未实现指定的操作。	选取器操作的结果。
ToneToken	string	所选音调的标记。如果用户在选取器中选择“默认值”，该字符串为空。	此标记可用于 Toast 通知负载，或者可以指定为联系人的铃声或短信铃声。如果 Result 为 0，仅在 ValueSet 中返回参数。
DisplayName	字符串	指定的音调的友好名称。	可显示给用户并用于表示所选音调的字符串。如果 Result 为 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
     }
}

任务：显示音调保存器

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

参数	类型	必须	可能值	说明
操作	string	是	“SaveRingtone”	打开选取器以保存铃声。
ToneFileSharingToken	string	是	用于要保存的铃声文件的 SharedStorageAccessManager 文件共享标记	将特定的声音文件另存为铃声。支持的文件内容类型为 mpeg 音频和 x-ms-wma 音频。
DisplayName	string	否	指定的音调的友好名称。	设置要在保存指定铃声时使用的友好名称。

在 LaunchUriResults.Result 中返回的值：

返回值	类型	可能值	说明
结果	Int32	0 - 成功。 1 - 已由用户取消。 2 - 文件无效。 3 - 文件内容类型无效。 4 - 文件超过最大铃声大小（在 Windows 10 中为 1 MB）。 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;
          }
      }
 }

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

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

参数	类型	必须	可能值	说明
操作	string	是	“GetToneName”	指示你想要获取音调的友好名称。
ToneToken	string	是	音调标记	从中获取显示名称的音调标记。

在 LaunchUriResults.Result 中返回的值：

返回值	类型	可能值	说明
结果	Int32	0 - 选取器操作成功。 7 - 参数不正确（例如，未提供 ToneToken）。 9 - 从指定的标记读取名称时出错。 10 - 无法找到指定的音调标记。	选取器操作的结果。
DisplayName	字符串	音调的友好名称。	返回所选音调的显示名称。如果 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
        }
    }
}

通过

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

ms-tonepicker: URI 方案引用

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

任务：显示音调选取器

任务：显示音调保存器

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

反馈

其他资源