ESim.Discover Метод

Ссылка

Определение

Пространство имен:: Windows.Networking.NetworkOperators

Важно!

Некоторые сведения относятся к предварительной версии продукта, в которую до выпуска могут быть внесены существенные изменения. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

Перегрузки

Discover()

Выполняет операцию обнаружения профиля eSIM, используя адрес SMDS по умолчанию.

Примечание

Эта функция доступна только для приложений мобильных операторов и приложений UWP с привилегированным доступом со стороны операторов мобильной сети.

Если вы хотите использовать этот API и опубликовать приложение в Microsoft Store, вам потребуется запросить специальное утверждение для использования пользовательской возможности Microsoft.eSIMManagement_8wekyb3d8bbwe. Дополнительные сведения см. в разделе Пользовательские возможности.

Discover(String, String)

Выполняет операцию обнаружения профиля eSIM для указанного адреса RSP-сервера и соответствующего идентификатора.

Примечание

Discover()

Изменить

Выполняет операцию обнаружения профиля eSIM, используя адрес SMDS по умолчанию.

Примечание

public:
 virtual ESimDiscoverResult ^ Discover() = Discover;

/// [Windows.Foundation.Metadata.Overload("Discover")]
ESimDiscoverResult Discover();

[Windows.Foundation.Metadata.Overload("Discover")]
public ESimDiscoverResult Discover();

function discover()

Public Function Discover () As ESimDiscoverResult

Возвращаемое значение

ESimDiscoverResult

Объект ESimDiscoverResult , представляющий результат операции.

Атрибуты: OverloadAttribute

Требования к Windows

Семейство устройств	Windows 10, version 1903 (появилось в 10.0.18362.0)
API contract	Windows.Foundation.UniversalApiContract (появилось в v8.0)
Возможности приложения	Microsoft.eSIMManagement_8wekyb3d8bbwe

Примеры

Сценарий 1

Обнаружение профиля с заданным адресом SM-DP+ и соответствующим идентификатором. Оператор мобильной связи предоставляет приложению адрес SMDP, который является полным доменным именем сервера, например smdp.contoso.com , и MatchingID abcd1234 для поиска профиля. Предполагается, что клиент уже получил объект ESim из ESimWatcher.

async void Scenario1_DiscoverWithSmdpAddress(ESim esim, String smdpAddress, String matchingId)
{
    ESimDiscoverResult discoverResult = await esim.DiscoverAsync(
        smdpAddress,
        matchingId);

    if (discoverResult.Result.Status != ESimOperationStatus.Success)
    {
        discoveryStatusBar.Text = GetDiscoveryResultString("Discover failed", discoverResult.Result.Status);
        return;
    }

    if (discoverResult.Kind == ESimDiscoverResultKind.ProfileMetadata )
    {
        ESimProfileMetadata profileMetadata = discoverResult.ProfileMetadata;
        ESimOperationResult result = await profileMetadata.ConfirmInstallAsync();
        if (result.Status != ESimOperationStatus.Success)
        {
            discoveryStatusBar.Text = GetDiscoveryResultString("Couldn't install profile", result.Status);
        }
        else
        {
            discoveryStatusBar.Text = "Success";
        }

    }
    else
    {
        // If an SMDP address is given, the app will expect a profile.
        discoveryStatusBar.Text = "Unexpected result from server";
    }
}

Сценарий 2

Обнаружение профиля без сведений о сервере. Оператор мобильной связи не предоставляет сведения о сервере для скачивания профиля. В этом случае приложение по-прежнему может запустить процесс обнаружения. Приложение просматривает все доступные профили для eSIM. Это может привести к касаниям профилей, которые не принадлежат оператору мобильной связи, если eSIM может обнаружить несколько профилей. Однако при отсутствии информации от оператора мобильной связи этот метод можно использовать.

async Task<bool> Scenario2_DiscoverProfile(ESim esim, String rspServerAddress, String matchingId)
{
    ESimDiscoverResult discoverResult = await esim.DiscoverAsync(
        rspServerAddress,
        matchingId);

    if (discoverResult.Result.Status != ESimOperationStatus.Success)
    {
        discoveryStatusBar.Text = GetDiscoveryResultString("Discover failed", discoverResult.Result.Status);
        return false;
    }

    if (discoverResult.Kind == ESimDiscoverResultKind.Events)
    {
        IList<ESimDiscoverEvent> discoveryEvents = discoverResult.Events;
        foreach (ESimDiscoverEvent discoverEvent in discoveryEvents)
        {
            // Recursively visit the server hops in event list.
            foundProfile = await Scenario2_DiscoverProfile(
                esim,
                discoverEvent.RspServerAddress,
                discoverEvent.MatchingId);

            if (foundProfile) break;
        }
    }
    else if (discoverResult.Kind == ESimDiscoverResultKind.ProfileMetadata)
    {
        ESimProfileMetadata profileMetadata = discoverResult.ProfileMetadata;

        // There can be multiple profiles waiting for download. In a general profile
        // discovery, the app may ask the user's consent for each profile (metadata). 
        bool okToInstall = await GetUserConsentForProfileDownload(profileMetadata);

        // OR ...
        // In the use case where the app is expecting a certain profile, the app may 
        // check the Id, ProviderName and ProviderId of the returned profile metadata 
        // to determine whether it is the expected profile.
        //
        // For example:
        // okToInstall = IsExpectedProfile(profileMetadata);

        if (okToInstall)
        {
            ESimOperationResult result = await profileMetadata.ConfirmInstallAsync();
            if (result.Status != ESimOperationStatus.Success)
            {
                discoveryStatusBar.Text = GetDiscoveryResultString("Couldn't install profile", result.Status);
            }

            // Regardless of installation result, the desired profile has been found.
            // Return early to avoid touching other profiles unnecessarily.
            return true;
        }
        else
        {
            ESimOperationResult result = await profileMetadata.PostponeInstallAsync();
            if (result.Status != ESimOperationStatus.Success)
            {
                // App can choose to ignore the result as this is to postpone 
                // installation. Error can be caused by a timeout or bad connection 
                // with the remote server. All these causes will effectively postpone
                // the install.
            }
        }
    }

    return false;
}

async void Scenario2_DiscoverWithDefault(ESim esim)
{
    await Scenario2_DiscoverProfile(esim, null, null);
}

Сценарий 3

Обнаружение профилей с заданным подфиксом адреса сервера. Оператор мобильной связи размещает много серверов профилей, но он отказывается предоставить адрес сервера профиля приложению по соображениям безопасности. Приложению предлагается проверка профили, сохраненные на сервере с доменным именем, заканчивающееся contoso.comна . Некоторые логики совпадают с логикой сценария 2. В примере кода здесь вызывается функция Scenario2_DiscoverProfile().

async void Scenario3_DiscoverProfileWithServerInfo(ESim esim, String serverDomainNameSubfix)
{
    ESimDiscoverResult discoverResult = await esim.DiscoverAsync();

    if (discoverResult.Result.Status != ESimOperationStatus.Success)
    {
        discoveryStatusBar.Text = GetDiscoveryResultString("Discover failed", discoverResult.Result.Status);
        return;
    }

    if (discoverResult.Kind == ESimDiscoverResultKind.Events)
    {
        IList<ESimDiscoverEvent> discoverEvents = discoverResult.Events;
        foreach (ESimDiscoverEvent discoverEvent in discoverEvents)
        {
            // Check if this is the expected event.
            if (discoverEvent.RspServerAddress.EndsWith(serverDomainNameSubfix))
            {
                bool foundProfile = await Scenario2_DiscoveryProfile(
                    esim,
                    discoverEvent.RspServerAddress,
                    discoverEvent.MatchingId);

                if (foundProfile) break;
            }
        }
    }
    else 
    {
        // The first discovery is guaranteed to return event list.
        discoveryStatusBar.Text = "Unexpected result from server";
    }

    return;
}

Сценарий 4

Пробирающийся обзор доступных результатов обнаружения. Служебная программа eSIM отображает список результатов обнаружения для пользователя. Позже пользователь может выбрать следующий прыжок в зависимости от своих интересов. Чтобы получить список, приложение вызывает API обнаружения без каких-либо параметров.

Task<IList<ESimDiscoverEvent>> void Scenario4_ReviewDiscoveryResults(ESim esim)
{
    ESimDiscoverResult discoverResult = await esim.DiscoverAsync();

    if (discoverResult.Result.Status != ESimOperationStatus.Success)
    {
        discoveryStatusBar.Text = GetDiscoveryResultString("Discover failed", discoverResult.Result.Status);

        return new List<ESimDiscoverResult>();
    }

    if (discoverResult.Kind == ESimDiscoverResultKind.Events)
    {
        return discoverResult.Events;
    }
    else
    {
        // The first discovery is guaranteed to return event list.
        discoveryStatusBar.Text = "Unexpected result from server";
    }

    return new List<ESimDiscoverResult>();
}

Сценарий 5

Синхронизированный вызов API. Служебная программа пытается проверить, доступны ли результаты обнаружения для eSIM. Они создают функцию с именем HasAvailableEventsToDiscover(). Он гарантированно выполняется в пуле потоков приложения и хочет, чтобы результат возвращался синхронно.

bool Scenario5_HasAvailableEventsToDiscover(ESim esim)
{
    ESimDiscoverResult discoverResult = esim.Discover();

    if (discoverResult.Result.Status != ESimOperationStatus.Success)
    {
        discoveryStatusBar.Text = GetDiscoveryResultString("Discover failed", discoverResult.Result.Status);
        return false;
    }

    // The discover result will always return the default SMDP+ address as
    // the first result so that it can be considered by the caller as one
    // possible profile source. Any more events in the list mean that the
    // discovery server has discovery events available.
    if (discoverResult.Kind == ESimDiscoverResultKind.Events
        && discoverResult.Count > 1)
    {
        return true;
    }

    return false;
}

Операция обнаружения профилей включает в себя обращение к удаленному серверу. Это может быть либо сервер обнаружения, адрес которого предопределен в eSIM, либо адрес сервера, предоставленный оператором мобильной связи (MO). Сервер может вернуть список событий, содержащих сведения о следующем прыжке сервера, или скачать метаданные профиля. После того как приложение получит метаданные профиля, вы можете установить или отклонить профиль на основе собственной бизнес-логики. Обнаружение профилей выполняется последовательно. Это означает, что до тех пор, пока приложение не примет решение об установке текущего профиля, оно не сможет обнаруживать другие профили.

Для каждого прыжка приложение должно посетить прыжок, чтобы узнать, какой тип данных возвращается сервером. Однако метаданные профиля могут иметь ограничения по времени скачивания. Таким образом, приложение должно избегать ненужного скачивания других метаданных профиля, если оно имеет некоторое указание на то, где должен находиться интересующий профиль.

Применяется к

Discover(String, String)

Изменить

Примечание

public:
 virtual ESimDiscoverResult ^ Discover(Platform::String ^ serverAddress, Platform::String ^ matchingId) = Discover;

/// [Windows.Foundation.Metadata.Overload("DiscoverWithServerAddressAndMatchingId")]
ESimDiscoverResult Discover(winrt::hstring const& serverAddress, winrt::hstring const& matchingId);

[Windows.Foundation.Metadata.Overload("DiscoverWithServerAddressAndMatchingId")]
public ESimDiscoverResult Discover(string serverAddress, string matchingId);

function discover(serverAddress, matchingId)

Public Function Discover (serverAddress As String, matchingId As String) As ESimDiscoverResult

Параметры

serverAddress: String
Platform::String

winrt::hstring

Строка, содержащая адрес сервера RSP. Если serverAddress параметр пуст, API использует адрес SMDS по умолчанию.

matchingId: String
Platform::String

winrt::hstring

Строка, содержащая соответствующий идентификатор.

Возвращаемое значение

ESimDiscoverResult

Объект ESimDiscoverResult , представляющий результат операции.

Атрибуты: OverloadAttribute

Требования к Windows

Семейство устройств	Windows 10, version 1903 (появилось в 10.0.18362.0)
API contract	Windows.Foundation.UniversalApiContract (появилось в v8.0)
Возможности приложения	Microsoft.eSIMManagement_8wekyb3d8bbwe

Примеры

Примеры кода см. в разделе Обнаружение .

Применяется к

ESim.Discover Метод

Определение

Перегрузки

Discover()

Возвращаемое значение

Требования к Windows

Примеры

Сценарий 1

Сценарий 2

Сценарий 3

Сценарий 4

Сценарий 5

Комментарии

Применяется к

Discover(String, String)

Параметры

Возвращаемое значение

Требования к Windows

Примеры

Комментарии

Применяется к

Обратная связь

Обратная связь

Дополнительные ресурсы