در Android 9، میاناهای برنامه‌سازی کاربردی مدیریت نمایه (عمومی و
@SystemApi) ازطریق کلاس EuiccManager دردسترس است. ارتباط eUICC
واسط‌های برنامه‌نویسی کاربردی (@SystemApi only) ازطریق کلاس EuiccCardManager دردسترس است.
درباره eUICC
شرکت‌های مخابراتی می‌توانند بااستفاده از EuiccManager برنامه‌های شرکت مخابراتی برای مدیریت نمایه‌ها بسازند، همان‌طور که در «شکل ۱» نشان داده شده است. برنامه‌های شرکت مخابراتی لازم نیست برنامه سیستم باشند اما باید امتیازات شرکت مخابراتی را که نمایه‌های eUICC اعطا کرده‌اند داشته باشند. برنامه LPA (زیرینه LUI و LPA) برای فراخوانی @SystemApi باید برنامه سیستم باشد (یعنی در تصویر سیستم گنجانده شده باشد).
شکل ۱. تلفن‌های Android با برنامه شرکت مخابراتی و OEM LPA
علاوه‌بر منطق تماس با EuiccCardManager و صحبت کردن با eUICC، برنامه‌های LPA باید موارد زیر را پیاده‌سازی کنند:
- کارخواه SM-DP+ با سرور SM-DP+ صحبت می‌کند تا نمایه‌ها را اصالت‌سنجی و بارگیری کند
- [اختیاری] SM-DS برای دریافت نمایه‌های بارگیری‌شدنی بالقوه بیشتر
- مدیریت اعلان برای ارسال اعلان‌ها به سرور به‌منظور به‌روزرسانی وضعیت نمایه
- [اختیاری] مدیریت شکاف‌ها ازجمله جابه‌جایی بین منطق سیم‌کارت داخلی و سیم‌کارت فیزیکی. اگر تلفن فقط تراشه سیم‌کارت داخلی داشته باشد، این کار اختیاری است.
- سیم‌کارت داخلی OTA
اگرچه ممکن است بیش از یک برنامه LPA در تلفن Android وجود داشته باشد، فقط یک LPA می‌تواند به‌عنوان LPA کاری واقعی انتخاب شود که این انتخاب براساس اولویت تعریف‌شده در فایل AndroidManifest.xml هر برنامه انجام می‌شود.
استفاده از EuiccManager
میاناهای برنامه‌سازی کاربردی LPA ازطریق EuiccManager عمومی هستند (در بسته
android.telephony.euicc). برنامه شرکت مخابراتی می‌تواند نمونه EuiccManager را دریافت کند،
و روش‌های EuiccManager را برای دریافت اطلاعات eUICC و مدیریت
اشتراک‌ها (که در اسناد GSMA RSP به‌عنوان نمایه‌های
SubscriptionInfo نامیده می‌شوند) فراخوانی کند.
برای فراخوانی میاناهای برنامه‌سازی کاربردی عمومی، ازجمله عملیات‌های بارگیری، تعویض، و حذف اشتراک، برنامه شرکت مخابراتی باید امتیازهای لازم را داشته باشد. شرکت مخابراتی امتیازات را در فراداده نمایه اضافه می‌کند. eUICC API قوانین امتیاز شرکت مخابراتی را بر همین اساس اجرا می‌کند.
پلاتفرم Android قوانین خط‌مشی نمایه را مدیریت نمی‌کند. اگر قانون خط‌مشی‌ای در فراداده نمایه اعلام شده باشد، LPA می‌تواند نحوه مدیریت روند بارگیری و نصب نمایه را انتخاب کند. برای مثال، ممکن است LPA طرف سوم سازنده تجهیزات اصلی بااستفاده از کد خطای ویژه (کد خطا از LPA سازنده تجهیزات اصلی به پلاتفرم منتقل می‌شود، سپس پلاتفرم کد را به LUI سازنده تجهیزات اصلی منتقل می‌کند) قوانین خط‌مشی را مدیریت کند.
برای کسب اطلاعات درباره میاناهای برنامه‌سازی کاربردی چند نمایه فعال، به چند نمایه فعال مراجعه کنید.
میاناهای برنامه‌سازی کاربردی
میاناهای برنامه‌سازی کاربردی زیر را می‌توانید در
EuiccManager مستندات مرجع
و
EuiccManager.java پیدا کنید.
دریافت نمونه (عمومی)
نمونه EuiccManager را ازطریق Context#getSystemService دریافت می‌کند.
برای جزئیات، به
getSystemService مراجعه کنید.
EuiccManager mgr = (EuiccManager) context.getSystemService(Context.EUICC_SERVICE);
بررسی فعال (عمومی)
بررسی می‌کند که آیا اشتراک جاسازی‌شده فعال است یا خیر. این باید قبل‌از دسترسی به LPA APIs بررسی شود. برای جزئیات، به
isEnabled مراجعه کنید.
boolean isEnabled = mgr.isEnabled();
if (!isEnabled) {
return;
}
دریافت سند شناسایی جاسازی‌شده (عمومی)
شناسه 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 به‌عنوان «نمایه» نامیده می‌شود). اشتراک را می‌توان از کد فعال‌سازی ایجاد کرد. برای مثال، کد فعال‌سازی می‌تواند از رمزینه پاسخ‌سریع تجزیه شود. بارگیری اشتراک عملیاتی ناهمگام است.
فرد تماس‌گیرنده باید اجازه 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);
پاک کردن همه اشتراک‌ها (میانای برنامه‌سازی کاربردی سیستم)
همه اشتراک‌های دستگاه را پاک می‌کند. از Android 11، باید مقدار EuiccCardManager#ResetOption
enum را ارائه دهید تا مشخص کنید که آیا همه اشتراک‌های آزمایشی، عملیاتی، یا هر دو نوع اشتراک پاک شوند. تماس‌گیرنده باید اجازه 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، به
ثابت‌ها مراجعه کنید.