J2ME 訪問手機通訊錄：從廠商私有 API 到 JSR-75 PIM 標準

背景與挑戰

早期 J2ME (CLDC/MIDP 1.0/2.0) 無標準通訊錄 API，各廠商 (Nokia、Moto、Sony Ericsson) 提供私有庫，導致碎片化嚴重。JSR-75 (PIM API) 於 2006 年左右普及，成為訪問聯繫人、日曆、待辦事項的標準接口，但僅限較新機型 (約 2006 年後出廠)。

方案一：Nokia S40 系列私有技巧 —— TextField.PHONENUMBER

import javax.microedition.lcdui.*;

public class PhoneBookDemo extends MIDlet {
    private Form form;
    private TextField phoneField;

    public PhoneBookDemo() {
        form = new Form("通訊錄測試");
        // 關鍵：constraint 設置為 PHONENUMBER
        phoneField = new TextField("電話", "", 20, TextField.PHONENUMBER);
        form.append(phoneField);
    }

    protected void startApp() { Display.getDisplay(this).setCurrent(form); }
    protected void pauseApp() {}
    protected void destroyApp(boolean unconditional) {}
}

支援機型：Nokia 6600, N72 等 S40/S60 早期機型。
局限：Moto E680/A1200, SE K700, Nokia 3100 等不支援；僅能「選取」號碼填入輸入框，無法讀取姓名、多號碼、寫入修改。

方案二：JSR-75 PIM API —— 標準、強大、可移植

核心步驟

1. PIM.getInstance() 獲取 PIM 管理器。
2. listPIMLists(PIM.CONTACT_LIST) 列出所有聯繫人數據庫 (SIM 卡、手機內存等)。
3. openPIMList(PIM.CONTACT_LIST, PIM.READ_ONLY, dbName) 打開指定數據庫獲取 ContactList。
4. 遍歷 ContactList.items() 獲取 Contact 對象。
5. 使用 Contact.getString(Contact.FORMATTED_NAME, 0)、Contact.getString(Contact.TEL, 0) 讀取字段。
6. 完成後調用 ContactList.close() 釋放資源。

完整代碼範例

import javax.microedition.pim.*;
import java.util.Enumeration;

public class PIMContactReader {
    public void readAllContacts() {
        try {
            String[] databases = PIM.getInstance().listPIMLists(PIM.CONTACT_LIST);
            for (String dbName : databases) {
                System.out.println("數據庫: " + dbName);
                ContactList clist = (ContactList) PIM.getInstance()
                        .openPIMList(PIM.CONTACT_LIST, PIM.READ_ONLY, dbName);
                int count = 0;
                for (Enumeration e = clist.items(); e.hasMoreElements(); ) {
                    Contact c = (Contact) e.nextElement();
                    String name = c.getString(Contact.FORMATTED_NAME, 0);
                    String tel = c.getString(Contact.TEL, 0);
                    System.out.println(name + " - " + tel);
                    count++;
                }
                System.out.println("共 " + count + " 條記錄");
                clist.close();
            }
        } catch (PIMException ex) {
            ex.printStackTrace();
        }
    }
}

PIM 進階能力

• 寫入/修改：openPIMList(..., PIM.READ_WRITE)，調用 Contact.addString()/setString()，最後 ContactList.commit()。
• 字段分類：Contact.TEL 支援 ATTR_HOME, ATTR_MOBILE, ATTR_WORK 等屬性區分號碼類型。
• 多值字段：同一字段可有多個值 (如多個電話)，索引從 0 開始。

兼容性策略建議

最佳實踐提示

• 運行前檢測 System.getProperty("microedition.pim.version") 確認 JSR-75 支援。
• 捕獲 SecurityException：用戶可能拒絕授權訪問通訊錄。
• 大量讀取時分批處理，避免阻塞 UI 線程導致系統判定「無響應」殺死 MIDlet。
• 寫入操作務必在 finally 中 close()，防止數據庫鎖死。