J2ME PIM API 開發指南：通訊錄、行事曆與待辦事項存取全解析

PIM (Personal Information Management) 可選包概覽

JSR-75 PIM 部分定義了 javax.microedition.pim 套件，提供對裝置原生個人資訊的標準化存取：聯絡人 (Contact)、事件、待辦事項。屬於 MIDP 擴展，需裝置實作支援，且受 MIDP 安全模型管控 (僅受信任 MIDlet 可存取)。

環境檢測與 PIM 實例獲取

// 1. 檢測 PIM 可用性
String version = System.getProperty("microedition.pim.version");
if (version == null) {
    // 裝置不支援 PIM Optional Package
    return;
}

// 2. 獲取 PIM 單例
PIM pim = PIM.getInstance(); // 工廠模式，非建構子

開啟 PIM 列表 (三種列表類型)

// 列表類型常數
PIM.CONTACT_LIST  // 聯絡人
PIM.EVENT_LIST    // 行事曆事件
PIM.TODO_LIST     // 待辦事項

// 存取模式
PIM.READ_ONLY
PIM.READ_WRITE

// 開啟聯絡人列表示例
ContactList contactList = null;
try {
    contactList = (ContactList) pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_ONLY);
} catch (PIMException e) {
    // 無可用聯絡人資料庫 (裝置不支援此類型)
} catch (SecurityException e) {
    // MIDlet 未獲授權存取 PIM 資料 (需簽名/受信任)
}

重要：裝置至少需支援三種列表類型中的一種，不保證全支援。

遍歷與讀取 PIM 項目資料

// 通用遍歷模式
Enumeration enum = contactList.items();
while (enum.hasMoreElements()) {
    Contact contact = (Contact) enum.nextElement();
    // 處理單一聯絡人
}

// 字段存取：必須先檢查 isSupportedField()
if (contact.isSupportedField(Contact.TEL)) {
    String phone = contact.getString(Contact.TEL, 0); // 索引 0 取第一個電話
}

// 常見 Contact 字段與資料類型
// 字串類型：getString(field, index)
// NAME, TEL, EMAIL, ADDR, URL, NOTE, ORG, TITLE, UID...
// 長整數類型：getDate(field, index) (毫秒時間戳)
// BIRTHDAY, REVISION...
// 整數類型：getInt(field, index)
// 陣列類型：getStringArray(field, index) (如 ADDR 返回 [街道,城市,郵遞區號...])

建立與修改 PIM 項目

// 建立新聯絡人 (需 READ_WRITE 模式開啟列表)
Contact newContact = contactList.createContact();

// 設定姓名 (結構化字段)
String[] name = { "王", "小明", "", "", "" }; // {姓, 名, 中間名, 前綴, 後綴}
newContact.addString(Contact.NAME, PIMItem.ATTR_NONE, name[0]); // 姓
newContact.addString(Contact.NAME, PIMItem.ATTR_NONE, name[1]); // 名
// 或使用格式化姓名
newContact.addString(Contact.FORMATTED_NAME, PIMItem.ATTR_NONE, "王小明");

// 設定電話 (支援屬性標記)
newContact.addString(Contact.TEL, Contact.ATTR_MOBILE, "0912-345-678");
newContact.addString(Contact.TEL, Contact.ATTR_HOME, "02-2345-6789");

// 設定生日
newContact.addDate(Contact.BIRTHDAY, PIMItem.ATTR_NONE, 
                   new java.util.Date(90, 0, 1).getTime()); // 1990/1/1

// 提交儲存
newContact.commit(); // 同步至原生資料庫

分類與搜尋進階功能

• 分組管理：ContactList.getCategories()、addToCategory()、removeFromCategory()
• 字串搜尋：ContactList.stringSearch("關鍵字", fields, exactMatch)
• 版本控制：Contact.getRevision() 獲取最後修改時間戳，支援增量同步

安全與移植性考量

1. 權限模型：MIDP 2.0 信任域機制決定 PIM 存取權，未簽名 MIDlet 通常被拒絕
2. 字段支援差異：務必呼叫 isSupportedField() 再存取，避免運行期異常
3. 資料格式：日期統一用 UTC 毫秒長整數，字串編碼遵循平台預設 (通常 UTF-8)
4. 並發存取：原生 PIM 應用與 MIDlet 同時修改可能導致衝突，建議讀取後立即處理、快速提交