Выбор и сохранение звуковых сигналов с помощью схемы URI ms-tonepicker

  • Статья

В этом разделе описывается, как использовать схему URI ms tonepicker:. Эту схему URI можно использовать для указанных ниже целей.

  • Определение доступности средства выбора звуковых сигналов на устройстве.
  • Отображение средства выбора звуковых сигналов для вывода доступных мелодий звонка, системных звуков, мелодий SMS и звуковых сигналов, а также для получения маркера звукового сигнала, который представляет выбранный пользователем звук.
  • Отображение средства сохранения звукового сигнала, которое в качестве входных данных получает маркер звукового файла и сохраняет его на устройстве. Сохраненные звуковые сигналы становятся доступными через средство выбора звуковых сигналов. Пользователи могут также присвоить звуковому сигналу понятное имя.
  • Преобразование маркера звукового сигнала в его понятное имя.

Справка по схеме URI ms-tonepicker:

Эта схема 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 строка нет Маркер существующего звукового сигнала. Звуковой сигнал, который должен отображаться как текущий в средстве выбора звуковых сигналов. Если это значение не задано, по умолчанию выбирается первый звуковой сигнал в списке.
Строго говоря, это не является путем к файлу. Подходящее значение для параметра CurrenttoneFilePath можно получить из значения ToneToken, возвращаемого средством выбора звуковых сигналов.
TypeFilter строка нет "Ringtones", "Notifications", "Alarms", "None" Выбор звуковых сигналов, добавляемых в средство выбора. Если никакой фильтр не задан, отображаются все звуковые сигналы.

Значения, возвращаемые в LaunchUriResults.Result:

Возвращаемые значения Тип Возможные значения Описание
Результат Int32 0 – успех.
1 – отменено.
7 – недопустимые параметры.
8 – нет звуковых сигналов, удовлетворяющих условиям фильтра.
255 – указанное действие не реализовано.		 Результат операции в средстве выбора.
ToneToken строка Маркер выбранного звукового сигнала.
Эта строка будет пустой, если пользователь выбирает в средстве выбора значение по умолчанию.		 Этот маркер может использоваться в полезных данных всплывающего уведомления, или его можно назначить мелодии звонка или мелодию SMS контакта. Этот параметр возвращается в ValueSet только в случае, если Result равен 0.
DisplayName строка Понятное имя указанного звукового сигнала. Строка, которая может отображаться пользователю для представления выбранного звукового сигнала. Этот параметр возвращается в ValueSet только в случае, если Result равен 0.

Пример. Открытие средства выбора, чтобы пользователь мог выбрать звуковой сигнал

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 – размер файла превышает максимальный размер мелодии звонка (1 МБ в Windows 10).
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 строка Понятное имя звукового сигнала. Возвращает отображаемое имя выбранного звукового сигнала. Этот параметр возвращается в ValueSet только в случае, если Result равен 0.

Пример: получение маркера звукового сигнала из 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
        }
    }
}