API های eUICC

در اندروید 9، APIهای مدیریت نمایه (عمومی و @SystemApi) از طریق کلاس EuiccManager در دسترس هستند. APIهای ارتباطی eUICC (فقط @SystemApi) از طریق کلاس EuiccCardManager در دسترس هستند.

درباره eUICC

شرکت‌های مخابراتی می‌توانند با استفاده از EuiccManager برای مدیریت نمایه‌ها، برنامه‌های حامل ایجاد کنند، همانطور که در شکل 1 نشان داده شده است. برنامه‌های حامل نیازی به برنامه‌های سیستمی ندارند، بلکه باید دارای امتیازات اپراتور توسط نمایه‌های eUICC باشند. یک برنامه LPA (LUI و LPA backend) برای فراخوانی @SystemApi باید یک برنامه سیستمی باشد (یعنی در تصویر سیستم موجود باشد).

شکل 1. تلفن های اندرویدی با برنامه حامل و OEM LPA

علاوه بر منطق تماس EuiccCardManager و صحبت با eUICC، برنامه های LPA باید موارد زیر را اجرا کنند:

• کلاینت SM-DP+ در حال صحبت با سرور SM-DP+ برای احراز هویت و دانلود پروفایل ها
• [اختیاری] SM-DS برای دریافت نمایه های بالقوه قابل دانلود بیشتر
• مدیریت اعلان برای ارسال اعلان‌ها به سرور برای به‌روزرسانی وضعیت نمایه
• [اختیاری] مدیریت اسلات از جمله جابجایی بین eSIM و منطق pSIM. اگر گوشی فقط دارای تراشه eSIM باشد، این اختیاری است.
• eSIM OTA

اگرچه بیش از یک برنامه LPA می تواند در یک تلفن Android وجود داشته باشد، تنها یک LPA را می توان بر اساس اولویت تعریف شده در فایل AndroidManifest.xml هر برنامه به عنوان LPA واقعی انتخاب کرد.

با استفاده از EuiccManager

APIهای LPA از طریق EuiccManager عمومی هستند (تحت بسته android.telephony.euicc ). یک برنامه حامل می‌تواند نمونه EuiccManager را دریافت کند و روش‌های موجود در EuiccManager را برای دریافت اطلاعات eUICC و مدیریت اشتراک‌ها (که در اسناد GSMA RSP به آن‌ها نمایه می‌شود) به عنوان نمونه‌های SubscriptionInfo فراخوانی کند.

برای فراخوانی APIهای عمومی از جمله عملیات دانلود، تغییر و حذف اشتراک، برنامه شرکت مخابراتی باید امتیازات لازم را داشته باشد. امتیازات حامل توسط شرکت مخابراتی تلفن همراه در فراداده نمایه اضافه می شود. eUICC API قوانین امتیاز حامل را بر این اساس اعمال می کند.

پلتفرم Android قوانین خط مشی نمایه را کنترل نمی کند. اگر یک قانون خط مشی در فراداده نمایه اعلام شده باشد، LPA می تواند نحوه مدیریت مراحل دانلود و نصب نمایه را انتخاب کند. به عنوان مثال، ممکن است یک OEM LPA شخص ثالث قوانین خط مشی را با استفاده از یک کد خطای خاص مدیریت کند (کد خطا از OEM LPA به پلتفرم منتقل می شود، سپس پلت فرم کد را به OEM LUI ارسال می کند).

برای اطلاعات در مورد API های چند پروفایل فعال، به نمایه های چندگانه فعال مراجعه کنید.

API ها

API های زیر را می توان در مستندات مرجع EuiccManager و EuiccManager.java یافت.

دریافت نمونه (عمومی)

نمونه EuiccManager را از طریق Context#getSystemService دریافت می کند. برای جزئیات، به getSystemService مراجعه کنید.

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

بررسی فعال (عمومی)

بررسی می کند که آیا اشتراک جاسازی شده فعال است یا خیر. این باید قبل از دسترسی به APIهای LPA بررسی شود. برای جزئیات، به isEnabled مراجعه کنید.

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

دریافت EID (عمومی)

EID شناسایی سخت افزار eUICC را دریافت می کند. اگر eUICC آماده نباشد، ممکن است باطل باشد. تماس‌گیرنده باید دارای امتیاز شرکت مخابراتی یا مجوز READ_PRIVILEGED_PHONE_STATE باشد. برای جزئیات، به getEid مراجعه کنید.

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

دریافت EuiccInfo (عمومی)

اطلاعاتی در مورد eUICC دریافت می کند. این شامل نسخه سیستم عامل است. برای جزئیات، به getEuiccInfo مراجعه کنید.

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

دانلود اشتراک (عمومی)

اشتراک داده شده را دانلود می کند (که در اسناد GSMA RSP به آن "نمایه" گفته می شود). اشتراک را می توان از طریق یک کد فعال سازی ایجاد کرد. به عنوان مثال، یک کد فعال سازی را می توان از یک کد QR تجزیه کرد. دانلود اشتراک یک عملیات ناهمزمان است.

تماس‌گیرنده یا باید مجوز WRITE_EMBEDDED_SUBSCRIPTIONS داشته باشد یا از امتیاز شرکت مخابراتی برای اشتراک هدف برخوردار باشد. برای جزئیات، downloadSubscription ببینید.

// 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);

تغییر اشتراک (عمومی)

اشتراک داده شده را به (فعال می کند) تغییر می دهد. تماس‌گیرنده باید یا WRITE_EMBEDDED_SUBSCRIPTIONS داشته باشد یا برای اشتراک فعال فعلی و اشتراک هدف دارای امتیازات شرکت مخابراتی باشد. برای جزئیات، به switchToSubscription مراجعه کنید.

// 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);

تغییر اشتراک با پورت (عمومی)

(در دسترس از Android 13) اشتراک داده شده را با نمایه پورت مشخص شده به (فعال می‌کند) تغییر می‌دهد. تماس‌گیرنده باید یا WRITE_EMBEDDED_SUBSCRIPTIONS داشته باشد یا برای اشتراک فعال فعلی و اشتراک هدف دارای امتیازات شرکت مخابراتی باشد. برای جزئیات، به switchToSubscription مراجعه کنید.

// 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);

درگاه سیم کارت موجود است (عمومی)

public boolean isSimPortAvailable(int portIndex)

(در دسترس از Android 13) نشان می دهد که آیا نمایه پورت عبور موجود است یا خیر. یک پورت در صورتی در دسترس است که هیچ اشتراکی در آن فعال نباشد یا برنامه تماس گیرنده دارای امتیاز شرکت مخابراتی نسبت به اشتراک نصب شده در درگاه انتخابی باشد. برای جزئیات، به isSimPortAvailable مراجعه کنید.

حذف اشتراک (عمومی)

اشتراک با شناسه اشتراک را حذف می کند. اگر اشتراک در حال حاضر فعال باشد، ابتدا غیرفعال می شود. تماس‌گیرنده باید WRITE_EMBEDDED_SUBSCRIPTIONS یا امتیازات شرکت مخابراتی را برای اشتراک هدف داشته باشد. برای جزئیات، deleteSubscription را ببینید.

// 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);

پاک کردن همه اشتراک ها (سیستم API)

تمام اشتراک های موجود در یک دستگاه را پاک می کند. با شروع اندروید 11، باید یک مقدار EuiccCardManager#ResetOption برای پاک کردن تمام اشتراک‌های آزمایشی، عملیاتی یا هر دو نوع، ارائه دهید. تماس‌گیرنده باید WRITE_EMBEDDED_SUBSCRIPTIONS مجوز داشته باشد.

// 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);

شروع فعالیت وضوح (عمومی)

فعالیتی را برای حل یک خطای قابل حل توسط کاربر شروع می کند. اگر عملیاتی EuiccManager#EMBEDDED_SUBSCRIPTION_RESULT_RESOLVABLE_ERROR را برگرداند، می‌توان این روش را فراخوانی کرد تا از کاربر بخواهد مشکل را حل کند. این روش فقط یک بار برای یک خطای خاص قابل فراخوانی است.

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

ثابت ها

برای مشاهده لیستی از ثابت های public در EuiccManager ، Constants را ببینید.