石頭閒語:Openchange/libmapi API 用例

在 libmapi 中，主要的封包結構是 mapi_object_t。使用 mapi_object_init() 建構內容。主要的函數回傳值是 enum MAPISTATUS，並以 MAPI_E_SUCCESS 表示成功執行。通常在呼叫 libmapi API 後使用 if (retval != MAPI_E_SUCCESS) return false; 判斷程式流程。

就設計架構而言， libmapi 運作時會管理記憶體資源。使用 MAPIFreeBuffer(), mapi_object_release() 便可釋放閒置的記憶體空間。但就我實測結果顯示，它目前存有 memory lack 問題。以擷取連絡人清單為例，在擁有 256MB 實際記憶體與 384MB Swap 空間的 GNU/Linux 系統上，大約在擷取200筆訊息後，就會因為記憶體不足而被系統中止程序。

openchangeclient -p rock --fetch-items=contact

這是目前使用 libmapi 開發大型客戶軟體時必須注意之處。其他Bug可以參考 Openchange開發工具補遺。

初始化

配置記憶體資源。透過 talloc library 管理記憶體。
配置會期資源，並開啟指定的帳號簡介資料檔。
使用者登入。
建構預設的回傳訊息封包。

開啟信箱資料夾或指定功能的預設資料夾: Mailbox

enum MAPISTATUS     retval;
    uint32_t            type_of_folder; //指定要抓取的資料夾型態
    mapi_id_t           folder_id; //儲存取得的資料夾id (數值型態)
    mapi_object_t       obj_store; //儲存取得的訊息封包

mapi_object_init(&obj_store);
    type_of_folder = olFolderTopInformationStore; //Root of mailbox     
	retval = GetDefaultFolder(&obj_store, &folder_id, type_of_folder);
	if (retval != MAPI_E_SUCCESS) return false;

mapi_object_t       obj_folder; //儲存取得的資料夾封包
	mapi_object_init(&obj_folder);
	retval = OpenFolder(&obj_store, folder_id, &obj_folder);
	// obj_store 是 父資料夾的封包 (parent folder)
	if (retval != MAPI_E_SUCCESS) return false;

/*
The following types of folders are supported:

* olFolderTopInformationStore
    * olFolderDeletedItems
    * olFolderOutbox
    * olFolderSentMail
    * olFolderInbox
    * olFolderCommonView
    * olFolderCalendar
    * olFolderContacts
    * olFolderJournal
    * olFolderNotes
    * olFolderTasks
    * olFolderDrafts
    * olFolderReminders
    * olFolderFinder
*/

取得訊息 (Message) 的屬性內容

在 Exchange 中，包含電子郵件、行事曆、連絡人等等各類文件，都被視為「訊息(message)」，訊息的內容則歸屬於「訊息屬性(message property)」。故要取得訊息內容時，就要以 GetProps(), GetPropsAll() 等取得指定的屬性清單。再以 get_SPropValue() 自屬性清單中取得指定的屬性值。

取得資料夾或階層式個體的屬性內容

以 QueryRows() 或 SeekRow() 讀取項目的屬性內容。以 find_SPropValue_data() 讀取 SRow_t aRow 結構的內容。

mapi_object_t		obj_htable;
	mapi_object_t		obj_table;

struct SPropTagArray	*SPropTagArray;
	struct SRowSet		rowset;

uint32_t    start_position, end_position, current_position, seekRowResult;

mapi_object_init(&obj_htable);
	retval = GetHierarchyTable(obj_folder, &obj_htable, 0, NULL);
	if (retval != MAPI_E_SUCCESS) return false;

/**
     * 設定要取得的屬性。
     * 以 SQL 的概念說明的話，這是在設定 SELECT 的欄位。
     * 此處的設定會影嚮接下來的 QueryRows() 與 SeekRow() 的結果。          
     */
	SPropTagArray = set_SPropTagArray(mem_ctx, 0x6,
					  PR_DISPLAY_NAME,
					  PR_FID,
					  PR_COMMENT,
					  PR_CONTENT_UNREAD,
					  PR_CONTENT_COUNT,
					  PR_FOLDER_CHILD_COUNT);
	retval = SetColumns(&obj_htable, SPropTagArray);
	MAPIFreeBuffer(SPropTagArray);
	if (retval != MAPI_E_SUCCESS) return false;

while (((retval = QueryRows(&obj_htable, 0x32, TBL_ADVANCE, &rowset)) 
        != MAPI_E_NOT_FOUND) && rowset.cRows) 
    {
		for (index = 0; index < rowset.cRows; index++) {
			fid = (const uint64_t *)find_SPropValue_data(&rowset.aRow[index], PR_FID);
			name = (const char *)find_SPropValue_data(&rowset.aRow[index], PR_DISPLAY_NAME);
		}
	}

mapi_object_init(&obj_table);
    for (current_position = start_position - 1; 
        current_position < end_position; 
        ++current_position) 
    {
        SeekRow(&obj_table, BOOKMARK_BEGINNING, current_position, &seekRowResult);
        //SeekRow(&obj_table, BOOKMARK_CURRENT, 0, &seekRowResult);

retval = QueryRows(&obj_table, 1, TBL_ADVANCE, &rowset);
        if (retval == MAPI_E_NOT_FOUND || rowset.cRows == 0)
            break;
    }

輸出屬性值

可參考 libmapi/mapidump.c 的程式碼。

/**
 * 輸出資料型態為字串的屬性。
 */ 
void put_str(struct mapi_SPropValue_array *properties, 
    uint32_t mapitag, 
    const char *label,
    const char *pad) 
{
    const uchar_t *p;

p = (const uchar_t *)find_mapi_SPropValue_data(properties, mapitag);
    if ( !p )
        return;
    printf("%s%s: %s\n", pad, label, p); 
}

/**
 * 輸出資料型態為日期的屬性。
 */ 
void put_datetime(TALLOC_CTX *mem_ctx, 
    struct mapi_SPropValue_array *properties, 
    uint32_t mapitag,
    const char*label,
    const char*pad) 
{
	NTTIME                 time;
	const struct FILETIME  *filetime;
	char                   *date;

filetime = (const struct FILETIME *) find_mapi_SPropValue_data(properties, mapitag);
	
	if (filetime) {
        time = filetime->dwHighDateTime;
        time = time << 32;
        time |= filetime->dwLowDateTime;
        date = (char*)nt_time_string(mem_ctx, time);
        printf("%s%s: %s\n", pad, label, date);
        talloc_free(date);
	}
    return;
}

/**
 * 輸出資料型態為無號整數的屬性。
 */ 
void put_uint32(struct mapi_SPropValue_array *properties, 
    uint32_t mapitag, 
    const char *label,
    const char *pad) 
{
    const uint32_t *p;

p = (const uint32_t *)find_mapi_SPropValue_data(properties, mapitag);
    if ( !p )
        return;
    printf("%s%s: %u\n", pad, label, *p); 
}

/**
 * 輸出資料型態為實數的屬性。
 */ 
void put_double(struct mapi_SPropValue_array *properties, 
    uint32_t mapitag, 
    const char *label,
    const char *pad) 
{
    const double *p;

p = (const double *)find_mapi_SPropValue_data(properties, mapitag);
    if ( !p )
        return;
    printf("%s%s: %f\n", pad, label, *p); 
}

/**
 * 以十六進位格式輸出資料型態為長整數的屬性。
 */ 
void put_longhex(struct mapi_SPropValue_array *properties, 
    uint32_t mapitag, 
    const char *label,
    const char *pad) 
{
    const uint64_t *p;

p = (const uint64_t *)find_mapi_SPropValue_data(properties, mapitag);
    if ( !p )
        return;
    printf("%s%s: %"PRIx64"\n", pad, label, *p); 
}

Openchange官方範例: examples@Openchange. 而 libmapi/openchangeclient.c 則是一個集大成的範例，極具實用性。

姓名 :
Email :
URL :
回應狀態:	公開私密
驗證碼 :	( 請依顯示文字填入 ) 重新產生驗證碼
	記住我的資訊顯示我的圖像 ( 登入或申請個人圖像 )
回應內容 :

石頭閒語

2009年04月15日

Openchange/libmapi API 用例

初始化

開啟信箱資料夾或指定功能的預設資料夾: Mailbox

取得訊息 (Message) 的屬性內容

取得資料夾或階層式個體的屬性內容

輸出屬性值

引用URL