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
}

작업: 톤 선택기 표시하기

톤 선택기를 표시하기 위해 전달할 수 있는 인수는 다음과 같습니다.

매개 변수 Type Required 사용 가능한 값: 설명
작업 string 예 "PickRingtone" 톤 선택기를 엽니다.
CurrentToneFilePath string 아니요 기존 톤 토큰입니다. 톤 선택기에서 현재의 톤으로 표시할 톤입니다. 이 값을 설정하지 않으면 목록의 첫 번째 톤이 기본적으로 선택됩니다.
이 값은 엄밀히 말해 파일 경로가 아닙니다. 톤 선택기에서 반환된 ToneToken 값으로부터 CurrenttoneFilePath에 적합한 값을 가져올 수 있습니다.
TypeFilter string 아니요 "벨소리", "알림", "알람", "없음" 선택기에 추가할 톤을 선택합니다. 필터를 지정하지 않으면 모든 톤이 표시됩니다.

다음은 LaunchUriResults.Result에서 반환되는 값입니다.

반환 값 Type 사용 가능한 값: 설명
결과 Int32 0 - 성공입니다.
1 - 취소되었습니다.
7 - 유효하지 않은 매개변수입니다.
8 - 필터 조건과 일치하는 톤이 없습니다.
255 - 지정된 작업이 구현되지 않습니다.		 선택기 작업의 결과입니다.
ToneToken string 선택한 톤의 토큰입니다.
사용자가 선택기에서 기본값을 선택하면 문자열이 비어 있습니다.		 이 토큰은 알림 메시지 페이로드에서 사용하거나 연락처의 벨소리 또는 텍스트 톤으로 할당할 수 있습니다. 이 매개변수는 결과가 0인 경우에만 ValueSet에 반환됩니다.
DisplayName string 지정된 톤의 친숙한 이름입니다. 선택한 톤을 나타내도록 사용자에게 표시할 수 있는 문자열입니다. 이 매개변수는 결과가 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
     }
}

작업: 톤 저장기 표시하기

톤 저장기를 표시하기 위해 전달할 수 있는 인수는 다음과 같습니다.

매개 변수 Type Required 사용 가능한 값: 설명
작업 string 예 "SaveRingtone" 선택기를 열어서 벨소리를 저장합니다.
ToneFileSharingToken string 예 저장할 벨소리 파일에 대한 SharedStorageAccessManager 파일 공유 토큰입니다. 특정 사운드 파일을 벨소리로 저장합니다. 이 파일에 대해 지원되는 콘텐츠 형식은 mpeg 오디오 및 x-ms-wma 오디오입니다.
DisplayName string 아니요 지정된 톤의 친숙한 이름입니다. 지정된 벨소리를 저장할 때 사용할 표시 이름을 설정합니다.

다음은 LaunchUriResults.Result에서 반환되는 값입니다.

반환 값 Type 사용 가능한 값: 설명
결과 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;
          }
      }
 }

작업: 톤 토큰을 톤의 친숙한 이름으로 변환하기

친숙한 톤 이름을 가져오기 위해 전달할 수 있는 인수는 다음과 같습니다.

매개 변수 Type Required 사용 가능한 값: 설명
작업 string 예 "GetToneName" 친숙한 톤 이름을 가져와야 한다는 것을 나타냅니다.
ToneToken string 예 톤 토큰 표시 이름을 가져올 출처가 되는 톤 토큰입니다.

다음은 LaunchUriResults.Result에서 반환되는 값입니다.

반환 값 Type 사용 가능한 값: 설명
결과 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
        }
    }
}