ESim.Discover 方法

参考

定义

命名空间:: Windows.Networking.NetworkOperators

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

重载

Discover()

使用默认 SMDS 地址执行 eSIM 配置文件发现操作。

注意

此功能仅适用于移动运营商应用和由移动网络运营商授予特权访问权限的 UWP 应用。

如果要使用此 API 并将应用发布到 Microsoft Store，则需要请求特殊批准才能 Microsoft.eSIMManagement_8wekyb3d8bbwe使用自定义功能。有关详细信息，请参阅自定义功能。

Discover(String, String)

对提供的 RSP 服务器地址和匹配的 ID 执行 eSIM 配置文件发现操作。

注意

此功能仅适用于移动运营商应用和由移动网络运营商授予特权访问权限的 UWP 应用。

Discover()

编辑

使用默认 SMDS 地址执行 eSIM 配置文件发现操作。

注意

此功能仅适用于移动运营商应用和由移动网络运营商授予特权访问权限的 UWP 应用。

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+ 地址和匹配 ID 的配置文件。移动运营商为应用提供 SMDP 地址，该地址是服务器（例如 smdp.contoso.com ）的 FQDN，以及用于查找配置文件的 MatchingID abcd1234 。假设客户端已从 ESimWatcher 获取 ESim 对象。

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)

编辑

对提供的 RSP 服务器地址和匹配的 ID 执行 eSIM 配置文件发现操作。

注意

此功能仅适用于移动运营商应用和由移动网络运营商授予特权访问权限的 UWP 应用。

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

包含匹配 ID 的字符串。

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 要求

示例

注解

适用于

反馈

反馈

其他资源