次の方法で共有


ESim.Discover メソッド

定義

オーバーロード

Discover()

既定の SMDS アドレスを使用して eSIM プロファイル検出操作を実行します。

注意

この機能は、モバイル ネットワーク オペレーターによる特権アクセス権を持つモバイル オペレーター アプリと UWP アプリでのみ使用できます。

この API を使用してアプリを Microsoft Store に発行する場合は、カスタム機能 Microsoft.eSIMManagement_8wekyb3d8bbweを使用するために特別な承認を要求する必要があります。 詳細については、「 カスタム機能」を参照してください。

Discover(String, String)

指定された RSP サーバー アドレスと一致する ID に対して eSIM プロファイル検出操作を実行します。

注意

この機能は、モバイル ネットワーク オペレーターによる特権アクセス権を持つモバイル オペレーター アプリと UWP アプリでのみ使用できます。

この API を使用してアプリを Microsoft Store に発行する場合は、カスタム機能 Microsoft.eSIMManagement_8wekyb3d8bbweを使用するために特別な承認を要求する必要があります。 詳細については、「 カスタム機能」を参照してください。

Discover()

既定の SMDS アドレスを使用して eSIM プロファイル検出操作を実行します。

注意

この機能は、モバイル ネットワーク オペレーターによる特権アクセス権を持つモバイル オペレーター アプリと UWP アプリでのみ使用できます。

この API を使用してアプリを Microsoft Store に発行する場合は、カスタム機能 Microsoft.eSIMManagement_8wekyb3d8bbweを使用するために特別な承認を要求する必要があります。 詳細については、「 カスタム機能」を参照してください。

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 オブジェクト。

属性

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 アプリでのみ使用できます。

この API を使用してアプリを Microsoft Store に発行する場合は、カスタム機能 Microsoft.eSIMManagement_8wekyb3d8bbweを使用するために特別な承認を要求する必要があります。 詳細については、「 カスタム機能」を参照してください。

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 オブジェクト。

属性

Windows の要件

デバイス ファミリ
Windows 10, version 1903 (10.0.18362.0 で導入)
API contract
Windows.Foundation.UniversalApiContract (v8.0 で導入)
アプリの機能
Microsoft.eSIMManagement_8wekyb3d8bbwe

コード例については、「 検出 」を参照してください。

注釈

詳細については、「 検出 」を参照してください。

適用対象