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

工作：顯示音調選擇器

您可以傳遞來顯示音調選擇器的參數如下：

參數	類型​	必要	可能值	描述
動作	字串	是	"PickRingtone"	開啟音調選擇器。
CurrentToneFilePath	字串	否	現有的音調標記。	要顯示為音調選擇器中目前音調的音調。 如果未設定此值，則預設選擇清單中的第一個鈴聲。 嚴格來說，這不是檔案路徑。 您可以從音調選擇器傳回的 ToneToken 值中取得 CurrenttoneFilePath 適當的值。
TypeFilter	字串	否	"Ringtones", "Notifications", "Alarms", "None"	選取要新增至選擇器中的音調。 如果未指定任何篩選，則會顯示所有音調。

LaunchUriResults.Result 中傳回的值：

傳回值	類型	可能值	描述
結果	Int32	0-成功。 1-取消。 7-無效參數。 8 - 沒有符合篩選條件的音調。 255 - 未實作指定的動作。	選擇器操作的結果。+
ToneToken	字串	所選音調的標記。 如果使用者在選擇器中選取預設值，則字串是空的。	此權杖可用於快顯通知負載，也可指定為聯絡人的鈴聲或簡訊鈴聲。 只有當 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
     }
}

工作：顯示鈴聲保護程序

您可以傳遞來顯示音調保護程式的參數如下：

參數	類型​	必要	可能值	描述
動作	字串	是	"SaveRingtone"	開啟選擇器以儲存鈴聲。
ToneFileSharingToken	字串	是	SharedStorageAccessManager 用於儲存鈴聲檔案的檔案共用權杖。	將特定聲音檔案儲存為鈴聲。 此檔案支援的內容類型為 mpeg 音訊和 x-ms-wma 音訊。
DisplayName	字串	否	指定音調的友善名稱。	設定儲存指定鈴聲時要使用的顯示名稱。

LaunchUriResults.Result 中傳回的值：

傳回值	類型	可能值	描述
結果	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;
          }
      }
 }

工作：將音調標記轉換為其易記名稱

您可以傳遞來獲取音調的友好名稱的參數如下：

參數	類型​	必要	可能值	描述
動作	字串	是	“GetToneName”	表示您想要取得鈴聲的易記名稱。
ToneToken	字串	是	音調	從中取得顯示名稱的音調權杖。

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