ms-tonepicker URI スキームを使ったトーンの選択と保存

  • [アーティクル]

ここでは、ms-tonepicker: URI スキームの使い方について説明します。 この URI スキームを使って実行できる操作は次のとおりです。

  • トーンの選択コントロールがデバイスにあるかどうかを確認します。
  • トーンの選択コントロールを表示して、利用可能な着信音、システム サウンド、SMS 着信音、アラーム音の一覧を表示したり、ユーザーが選択したサウンドを表すトーン トークンを取得します。
  • サウンド ファイル トークンを入力として受け取り、デバイスに保存するトーン セーバーを表示します。 保存されたトーンは、トーンの選択コントロールから利用できるようになります。 トーンにはフレンドリ名を付けることもできます。
  • トーン トークンをフレンドリ名に変換します。

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 yes "PickRingtone" トーン選択コントロールを開きます。
CurrentToneFilePath string no 既存のトーン トークン。 トーンの選択コントロールに現在のトーンとして表示されるトーン。 この値が設定されていない場合、既定では、一覧の最初のトーンが選ばれます。
これは厳密にはファイル パスではありません。 トーンの選択コントロールから返された ToneToken の値から、CurrenttoneFilePath に適した値を取得できます。
TypeFilter string no "Ringtones"、"Notifications"、"Alarms"、"None" 選択コントロールに追加するトーンを選択します。 フィルターが指定されていない場合は、すべてのトーンが表示されます。

LaunchUriResults.Result に返される値は次のとおりです。

戻り値 型 指定できる値 説明
結果 Int32 0 - 成功しました。
1 - 取り消されました。
7 - 無効なパラメーターです。
8 - フィルター条件に一致するトーンがありません。
255 - 指定された操作が実装されていません。		 選択コントロールの操作の結果。
ToneToken string 選択されたトーンのトークン。
ユーザーが選択コントロールで既定を選択している場合、この文字列は空です。		 このトークンはトースト通知のペイロードで使用したり、任意の連絡先の着信音や SMS 着信音として割り当てたりすることができます。 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 yes "SaveRingtone" 選択コントロールを開いて着信音を保存します。
ToneFileSharingToken string yes 保存する着信音ファイルの SharedStorageAccessManager ファイル共有トークン。 特定のサウンド ファイルを着信音として保存します。 サポートされるファイル コンテンツの種類は、MPEG オーディオと x-ms-wma オーディオです。
DisplayName string no 指定したトーンのフレンドリ名。 指定した着信音を保存するときに使用する表示名を設定します。

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 yes "GetToneName" トーンのフレンドリ名を取得することを示します。
ToneToken string yes トーンのトークン 表示名を取得する対象となるトーン トークン。

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