ESim.Discover 方法

參考

定義

命名空間:: Windows.Networking.NetworkOperators

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

多載

Discover()

使用預設 SMDS 位址執行 eSIM 設定檔探索作業。

注意

這項功能僅適用于行動電信業者應用程式，以及行動網路操作員提供特殊許可權存取的 UWP 應用程式。

如果您想要使用此 API 並將您的應用程式發佈至 Microsoft Store，則必須要求特殊核准，才能使用自訂功能 Microsoft.eSIMManagement_8wekyb3d8bbwe。如需詳細資訊，請參閱自訂功能。

Discover(String, String)

針對提供的 RSP 伺服器位址和相符識別碼執行 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+ 位址和相符識別碼的設定檔。行動電信業者會提供應用程式 SMDP 位址，這是伺服器 FQDN，例如 smdp.contoso.com 和 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 伺服器位址和相符識別碼執行 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

包含相符識別碼的字串。

傳回

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

範例

備註

適用於

意見反應

其他資源