eUICC API'leri

Android 9'da profil yönetimi API'leri (public ve @SystemApi) EuiccManager sınıfı aracılığıyla kullanılabilir. eUICC iletişimi API'leri (yalnızca @SystemApi) EuiccCardManager sınıfı üzerinden kullanılabilir.

eUICC hakkında

Şekil 1'de gösterildiği gibi, operatörler profilleri yönetmek için EuiccManager'ı kullanarak operatör uygulamaları oluşturabilir. Operatör uygulamalarının sistem uygulaması olması gerekmez ancak eUICC profilleri tarafından verilen operatör ayrıcalıklarına sahip olması gerekir. Bir LPA uygulaması (LUI ve LPA arka ucu), @SystemApi'yi çağırmak için sistem uygulaması (ör. sistem görüntüsüne dahil edilmiş) olmalıdır.

Operatör uygulaması ve OEM LPA'sı olan Android telefon

Şekil 1. Operatör uygulaması ve OEM LPA'sı olan Android telefonlar

LPA uygulamaları, EuiccCardManager numarası aranıp eUICC ile konuşulması mantığının yanı sıra aşağıdakileri de uygulamalıdır:

  • Kimlik doğrulama ve profilleri indirmek için SM-DP+ sunucusuyla iletişim kuran SM-DP+ istemcisi
  • [İsteğe bağlı] Daha fazla indirilebilir profil elde etmek için SM-DS
  • Profil durumunu güncellemek için sunucuya bildirim göndermeye yönelik bildirim işleme
  • [İsteğe bağlı] eSIM ve pSIM mantığı arasında geçiş yapma dahil olmak üzere yuva yönetimi. Telefon yalnızca eSIM çipine sahipse bu adım isteğe bağlıdır.
  • eSIM OTA

Bir Android telefonda birden fazla LPA uygulaması bulunabilir ancak her uygulamanın AndroidManifest.xml dosyasında tanımlanan önceliğe göre yalnızca bir LPA, gerçek çalışan LPA olarak seçilebilir.

EuiccManager'ı kullanma

LPA API'leri EuiccManager (paket altında android.telephony.euicc) üzerinden herkese açıktır. Bir operatör uygulaması EuiccManager örneğini alabilir, ve eUICC bilgilerini almak ve abonelikleri (GSMA RSP belgelerinde profiller olarak adlandırılır) SubscriptionInfo örnekleri olarak yönetmek için EuiccManager içindeki yöntemleri çağırabilir.

Abonelik indirme, değiştirme ve silme işlemleri dahil olmak üzere herkese açık API'leri çağırmak için operatör uygulamasının gerekli ayrıcalıklara sahip olması gerekir. Operatör ayrıcalıkları, profil meta verilerine mobil operatör tarafından eklenir. eUICC API'si, operatör ayrıcalığı kurallarını buna göre uygular.

Android platformu, profil politikası kurallarını işlemez. Profil meta verilerinde bir politika kuralı beyan edilirse LPA, profil indirme ve yükleme prosedürünün nasıl ele alınacağını seçebilir. Örneğin, üçüncü taraf bir OEM LPA'nın, özel bir hata kodu kullanarak politika kurallarını işlemesi mümkündür (hata kodu, OEM LPA'dan platforma, ardından platformdan OEM LUI'ye iletilir).

Birden fazla etkinleştirilmiş profil API'si hakkında bilgi edinmek için Birden fazla etkinleştirilmiş profil başlıklı makaleyi inceleyin.

API'ler

Aşağıdaki API'leri EuiccManager referans belgelerinde ve EuiccManager.java içinde bulabilirsiniz.

Örnek alma (herkese açık)

Context#getSystemService aracılığıyla EuiccManager örneğini alır. Ayrıntılı bilgi için getSystemService başlıklı makaleyi inceleyin.

EuiccManager mgr = (EuiccManager) context.getSystemService(Context.EUICC_SERVICE);

Etkin (herkese açık)

Yerleştirilmiş aboneliğin etkin olup olmadığını kontrol eder. Bu, LPA API'lerine erişmeden önce kontrol edilmelidir. Ayrıntılı bilgi için isEnabled başlıklı makaleyi inceleyin.

boolean isEnabled = mgr.isEnabled();
if (!isEnabled) {
    return;
}

EID'yi (ortak) alma

eUICC donanımını tanımlayan EID'yi alır. eUICC hazır değilse bu değer boş olabilir. Arayanın operatör ayrıcalığına veya READ_PRIVILEGED_PHONE_STATE iznine sahip olması gerekir. Ayrıntılı bilgi için getEid başlıklı makaleyi inceleyin.

String eid = mgr.getEid();
if (eid == null) {
  // Handle null case.
}

GetEuiccInfo (herkese açık)

eUICC hakkında bilgi alır. Bu, işletim sistemi sürümünü içerir. Ayrıntılı bilgi için getEuiccInfo başlıklı makaleyi inceleyin.

EuiccInfo info = mgr.getEuiccInfo();
String osVer = info.getOsVersion();

Aboneliği indirme (herkese açık)

Belirli bir aboneliği indirir (GSMA RSP belgelerinde "profil" olarak adlandırılır). Abonelik, etkinleştirme koduyla oluşturulabilir. Örneğin, etkinleştirme kodu bir QR kodundan ayrıştırılabilir. Abonelik indirme işlemi eşzamansızdır.

Arayanın WRITE_EMBEDDED_SUBSCRIPTIONS izni olmalı veya hedef abonelik için operatör ayrıcalıklarına sahip olması gerekir. Ayrıntılı bilgi için downloadSubscription başlıklı makaleyi inceleyin.

// Register receiver.
String action = "download_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(
        receiver,
        new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);

// Download subscription asynchronously.
DownloadableSubscription sub =
        DownloadableSubscription.forActivationCode(code /* encodedActivationCode*/);
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.downloadSubscription(sub, true /* switchAfterDownload */, callbackIntent);

Aboneliği değiştirme (herkese açık)

Belirtilen aboneliğe geçer (etkinleştirir). Arayan kullanıcının, etkin olan mevcut abonelik ve hedef abonelik için WRITE_EMBEDDED_SUBSCRIPTIONS veya operatör ayrıcalıkları olmalıdır. Ayrıntılı bilgi için switchToSubscription başlıklı makaleyi inceleyin.

// Register receiver.
String action = "switch_to_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, 0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);

// Switch to a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.switchToSubscription(1 /* subscriptionId */, callbackIntent);

Taşıma işlemiyle aboneliği değiştirme (herkese açık)

(Android 13'ten itibaren kullanılabilir) Belirtilen bağlantı noktası dizinine sahip aboneliğe geçer (etkinleştirir). Arayanın, etkinleştirilmiş mevcut abonelik ve hedef abonelik için WRITE_EMBEDDED_SUBSCRIPTIONS veya operatör ayrıcalıkları olmalıdır. Ayrıntılı bilgi için switchToSubscription başlıklı makaleyi inceleyin.

// Register receiver.
String action = "switch_to_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE, 0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/, null /* handler */);

// Switch to a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.switchToSubscription(1 /* subscriptionId */, 0 /*portIndex*/, callbackIntent);

SIM bağlantı noktası kullanılabilir mi (herkese açık)?

public boolean isSimPortAvailable(int portIndex)

(Android 13'ten itibaren kullanılabilir) Geçiş kartı bağlantı noktası dizininin kullanılabilir olup olmadığını döndürür. Bir bağlantı noktası, abonelik etkinleştirilmemişse veya arama uygulamasının, seçilen bağlantı noktasına yüklenen abonelik üzerinde operatör ayrıcalığı varsa kullanılabilir. Ayrıntılı bilgi için isSimPortAvailable başlıklı makaleyi inceleyin.

Aboneliği silme (herkese açık)

Abonelik kimliğiyle aboneliği siler. Abonelik şu anda etkinse önce devre dışı bırakılır. Arayanın, hedef abonelik için WRITE_EMBEDDED_SUBSCRIPTIONS veya operatör ayrıcalıklarına sahip olması gerekir. Ayrıntılı bilgi için deleteSubscription başlıklı makaleyi inceleyin.

// Register receiver.
String action = "delete_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/,
        null /* handler */);

// Delete a subscription asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.deleteSubscription(1 /* subscriptionId */, callbackIntent);

Tüm abonelikleri silme (sistem API'si)

Cihazdaki tüm abonelikleri siler. Android 11'den itibaren, tüm test, operasyonel veya her iki tür aboneliğin de silinip silinmeyeceğini belirtmek için bir EuiccCardManager#ResetOptionenum değeriEuiccCardManager#ResetOption sağlamanız gerekir. Arayanın WRITE_EMBEDDED_SUBSCRIPTIONS izni olmalıdır.

// Register receiver.
String action = "delete_subscription";
BroadcastReceiver receiver =
        new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
                if (!action.equals(intent.getAction())) {
                    return;
                }
                resultCode = getResultCode();
                detailedCode = intent.getIntExtra(
                    EuiccManager.EXTRA_EMBEDDED_SUBSCRIPTION_DETAILED_CODE,
                    0 /* defaultValue*/);
                resultIntent = intent;
            }
        };
context.registerReceiver(receiver, new IntentFilter(action),
        "example.broadcast.permission" /* broadcastPermission*/,
        null /* handler */);

// Erase all operational subscriptions asynchronously.
Intent intent = new Intent(action);
PendingIntent callbackIntent = PendingIntent.getBroadcast(
        getContext(), 0 /* requestCode */, intent, PendingIntent.FLAG_UPDATE_CURRENT);
mgr.eraseSubscriptions(
        EuiccCardManager.RESET_OPTION_DELETE_OPERATIONAL_PROFILES, callbackIntent);

Çözümleme etkinliğini başlatma (herkese açık)

Kullanıcı tarafından çözülebilen bir hatayı düzeltmek için etkinlik başlatır. Bir işlem EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR döndürürse kullanıcıdan sorunu çözmesini istemek için bu yöntem çağrılabilir. Bu yöntem, belirli bir hata için yalnızca bir kez çağrılabilir.

...
mgr.startResolutionActivity(getActivity(), 0 /* requestCode */, resultIntent, callbackIntent);

Sabitler

public içindeki EuiccManager sabitlerinin listesini görmek için Sabitler başlıklı makaleyi inceleyin.