萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android 從 SIM 卡讀取聯絡人完整實作指南

SIM 卡聯絡人存儲特性

SIM 卡聯絡人儲存在 ADN (Abbreviated Dialing Numbers) 檔案中,透過 content://icc/adn Content Provider 存取。特點:

  • 容量有限 (通常 250-500 條)
  • 欄位簡單:姓名、號碼、類型標識 (通常編碼在姓名尾部)
  • 不支援多號碼、Email、地址、頭像等豐富資料
  • 需 READ_CONTACTS 權限 (API 23+ 需動態申請)

權限宣告與動態申請

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Android 10+ 讀取 SIM 聯絡人可能需要 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
// 動態申請權限 (Activity/Fragment 中)
private static final int REQUEST_READ_CONTACTS = 100;

private void requestContactsPermission() {
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.READ_CONTACTS)
            != PackageManager.PERMISSION_GRANTED) {
        ActivityCompat.requestPermissions(this,
            new String[]{Manifest.permission.READ_CONTACTS}, REQUEST_READ_CONTACTS);
    } else {
        loadSimContacts();
    }
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions,
                                       @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (requestCode == REQUEST_READ_CONTACTS) {
        if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            loadSimContacts();
        } else {
            Toast.makeText(this, "需要聯絡人權限才能讀取 SIM 卡", Toast.LENGTH_SHORT).show();
        }
    }
}

核心實作:SimContactHelper 完整類別

public class SimContactHelper {
    private static final String TAG = "SimContactHelper";
    
    // SIM 卡 ADN URI
    private static final Uri SIM_URI = Uri.parse("content://icc/adn");
    
    // 欄位索引 (依據 TelephonyProvider 實作)
    private static final int NAME_COLUMN = 0;      // name 欄位 (含類型後綴)
    private static final int NUMBER_COLUMN = 1;    // number 欄位
    private static final int EMAIL_COLUMN = 2;     // email (通常為空)
    private static final int ANR_COLUMN = 3;       // additional number (通常為空)
    
    private final Context context;
    private final ContentResolver resolver;

    public SimContactHelper(Context context) {
        this.context = context.getApplicationContext();
        this.resolver = context.getContentResolver();
    }

    /** 檢查 SIM 卡狀態是否就緒 */
    public boolean isSimReady() {
        TelephonyManager telephonyManager = (TelephonyManager) 
            context.getSystemService(Context.TELEPHONY_SERVICE);
        int state = telephonyManager.getSimState();
        return state == TelephonyManager.SIM_STATE_READY;
    }

    /** 讀取所有 SIM 卡聯絡人 */
    public List getAllSimContacts() {
        List contacts = new ArrayList<>();
        
        if (!isSimReady()) {
            Log.w(TAG, "SIM card not ready");
            return contacts;
        }

        // 查詢投影:只取需要的欄位
        String[] projection = new String[]{"name", "number"};
        
        try (Cursor cursor = resolver.query(SIM_URI, projection, null, null, null)) {
            if (cursor == null) {
                Log.w(TAG, "Cursor is null, possibly no SIM contacts or permission issue");
                return contacts;
            }

            int nameIndex = cursor.getColumnIndex("name");
            int numberIndex = cursor.getColumnIndex("number");
            
            if (nameIndex == -1 || numberIndex == -1) {
                Log.e(TAG, "Column index not found: name=" + nameIndex + ", number=" + numberIndex);
                return contacts;
            }

            while (cursor.moveToNext()) {
                String rawName = cursor.getString(nameIndex);
                String number = cursor.getString(numberIndex);
                
                if (TextUtils.isEmpty(number)) continue; // 跳過無號碼記錄
                
                // 解析姓名與類型 (SIM 卡慣例: "姓名/類型後綴")
                SimContact contact = parseSimContact(rawName, number);
                contacts.add(contact);
            }
            
            Log.d(TAG, "Loaded " + contacts.size() + " SIM contacts");
        } catch (SecurityException e) {
            Log.e(TAG, "Permission denied reading SIM contacts", e);
        } catch (Exception e) {
            Log.e(TAG, "Error reading SIM contacts", e);
        }
        
        return contacts;
    }

    /** 解析 SIM 卡姓名欄位 (格式: "姓名/類型後綴") */
    private SimContact parseSimContact(String rawName, String number) {
        SimContact contact = new SimContact();
        contact.number = number;
        
        if (TextUtils.isEmpty(rawName)) {
            contact.name = "未知";
            contact.type = SimContactType.OTHER;
            return contact;
        }

        // 檢查是否包含類型後綴 (格式: "Name/W" 或 "Name/H" 等)
        int slashIndex = rawName.lastIndexOf('/');
        if (slashIndex > 0 && slashIndex == rawName.length() - 2) {
            char typeChar = Character.toUpperCase(rawName.charAt(slashIndex + 1));
            contact.name = rawName.substring(0, slashIndex);
            contact.type = parseTypeFromSuffix(typeChar);
        } else {
            contact.name = rawName;
            contact.type = SimContactType.OTHER;
        }
        
        return contact;
    }

    private SimContactType parseTypeFromSuffix(char suffix) {
        switch (suffix) {
            case 'H': return SimContactType.HOME;
            case 'W': return SimContactType.WORK;
            case 'M': return SimContactType.MOBILE;
            case 'F': return SimContactType.FAX;
            case 'P': return SimContactType.PAGER;
            default: return SimContactType.OTHER;
        }
    }

    /** 寫入聯絡人到 SIM 卡 (需 WRITE_CONTACTS 權限) */
    public boolean addSimContact(String name, String number, SimContactType type) {
        if (!isSimReady()) return false;
        
        ContentValues values = new ContentValues();
        // SIM 卡慣例:姓名加上類型後綴
        values.put("name", name + "/" + type.getSuffix());
        values.put("number", number);
        
        try {
            Uri result = resolver.insert(SIM_URI, values);
            return result != null;
        } catch (Exception e) {
            Log.e(TAG, "Failed to add SIM contact", e);
            return false;
        }
    }

    /** 刪除 SIM 卡聯絡人 */
    public boolean deleteSimContact(String name, String number) {
        if (!isSimReady()) return false;
        
        String selection = "name=? AND number=?";
        String[] args = new String[]{name, number};
        
        try {
            int deleted = resolver.delete(SIM_URI, selection, args);
            return deleted > 0;
        } catch (Exception e) {
            Log.e(TAG, "Failed to delete SIM contact", e);
            return false;
        }
    }

    /** 資料模型 */
    public static class SimContact {
        public String name;
        public String number;
        public SimContactType type = SimContactType.OTHER;
        
        @Override
        public String toString() {
            return name + " (" + type + "): " + number;
        }
    }

    public enum SimContactType {
        HOME('H'), WORK('W'), MOBILE('M'), FAX('F'), PAGER('P'), OTHER('O');
        private final char suffix;
        SimContactType(char suffix) { this.suffix = suffix; }
        public char getSuffix() { return suffix; }
    }
}

在 UI 中顯示 SIM 聯絡人

public class SimContactActivity extends AppCompatActivity {
    private RecyclerView recyclerView;
    private SimContactAdapter adapter;
    private SimContactHelper helper;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_sim_contacts);
        
        recyclerView = findViewById(R.id.recycler_view);
        recyclerView.setLayoutManager(new LinearLayoutManager(this));
        adapter = new SimContactAdapter();
        recyclerView.setAdapter(adapter);
        
        helper = new SimContactHelper(this);
        loadContacts();
    }

    private void loadContacts() {
        // 在背景執行緒查詢
        Executors.newSingleThreadExecutor().execute(() -> {
            List contacts = helper.getAllSimContacts();
            runOnUiThread(() -> adapter.submitList(contacts));
        });
    }

    static class SimContactAdapter extends ListAdapter {
        SimContactAdapter() {
            super(DIFF_CALLBACK);
        }

        @NonNull
        @Override
        public ViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
            View view = LayoutInflater.from(parent.getContext())
                .inflate(R.layout.item_sim_contact, parent, false);
            return new ViewHolder(view);
        }

        @Override
        public void onBindViewHolder(@NonNull ViewHolder holder, int position) {
            SimContactHelper.SimContact contact = getItem(position);
            holder.bind(contact);
        }

        static class ViewHolder extends RecyclerView.ViewHolder {
            TextView nameText, numberText, typeText;
            ViewHolder(View itemView) {
                super(itemView);
                nameText = itemView.findViewById(R.id.contact_name);
                numberText = itemView.findViewById(R.id.contact_number);
                typeText = itemView.findViewById(R.id.contact_type);
            }
            void bind(SimContactHelper.SimContact contact) {
                nameText.setText(contact.name);
                numberText.setText(contact.number);
                typeText.setText(contact.type.name());
            }
        }

        private static final DiffUtil.ItemCallback DIFF_CALLBACK =
            new DiffUtil.ItemCallback<>() {
                @Override
                public boolean areItemsTheSame(@NonNull SimContactHelper.SimContact old, 
                                               @NonNull SimContactHelper.SimContact nw) {
                    return old.number.equals(nw.number) && old.name.equals(nw.name);
                }
                @Override
                public boolean areContentsTheSame(@NonNull SimContactHelper.SimContact old, 
                                                  @NonNull SimContactHelper.SimContact nw) {
                    return old.equals(nw);
                }
            };
    }
}

多 SIM 卡 (雙卡雙待) 處理

Android 5.1+ (API 22) 支援多 SIM,需使用 SubscriptionManager 區分卡槽:

public List getSimContactsForSlot(int slotIndex) {
    SubscriptionManager subManager = (SubscriptionManager) 
        context.getSystemService(Context.TELEPHONY_SUBSCRIPTION_SERVICE);
    List subs = subManager.getActiveSubscriptionInfoList();
    
    if (subs == null || slotIndex >= subs.size()) return Collections.emptyList();
    
    int subId = subs.get(slotIndex).getSubscriptionId();
    // Android 7.0+ 可使用 subId 查詢特定 SIM
    Uri slotUri = Uri.withAppendedPath(SIM_URI, "subId/" + subId);
    // 後續查詢邏輯相同,使用 slotUri 替代 SIM_URI
}

常見問題與解決方案

  1. 查詢回傳空 Cursor:檢查權限、SIM 卡狀態 (SIM_STATE_READY)、嘗試 content://icc/adn 與 content://sim/adn 兩種 URI
  2. 姓名亂碼:SIM 卡編碼通常為 GSM 7-bit 或 UCS-2,Android 會自動轉換,極少數舊卡需手動處理
  3. 雙卡設備只讀到一張卡:使用 SubscriptionManager 遍歷所有 subId
  4. 寫入失敗:SIM 卡滿、權限不足 (需 WRITE_CONTACTS)、SIM 卡鎖定 (PIN 未解鎖)

總結

讀取 SIM 卡聯絡人核心在於 content://icc/adn Content Provider,配合正確權限管理、背景執行緒查詢、姓名後綴解析。現代應用建議優先讀取裝置聯絡人 (ContactsContract),SIM 卡聯絡人作為補充或遷移來源。雙卡場景需使用 SubscriptionManager 區分卡槽。

copyright © 萬盛學電腦網 all rights reserved