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

工作：顯示音調選擇器

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

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

LaunchUriResults.Result 中傳回的值：

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

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

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

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

LaunchUriResults.Result 中傳回的值：

傳回值 類型 可能值 描述
結果 Int32 0-選擇器操作成功。
7-參數不正確 (例如，沒有提供 ToneToken)。
9-讀取指定權杖的名稱時發生錯誤。
10-無法找到指定的音調權杖。		 選擇器操作的結果。+
DisplayName string 音調的易記名稱。 傳回所選音調的顯示名稱。 只有當 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
        }
    }
}