msn機器人訊息控制開發套件使用手冊
訊息控制開發套件v1.03 |
版權聲明
本手冊內容僅做為系統操作學習之用。
商標聲明
本手冊內容中所引用之各商標及商品稱名稱分屬合法註冊公司所有,絕為侵權之意,特此聲明。
目 錄
1. 注意事項
2. 示意圖
3. 程式介面型態
3.1 SOAP
3.2 CGI
3.3 ADO
4. SOAP 程式介面
4.1. WSDL 位置
4.2. API Functions
5. CGI/ADO程式介面
6. 附錄
1. 注意事項
1.0. 系統本身有unix/linux/win32版本,如需測試可聯繫 http://www.imoo.tw /service@imoo.tw 1.1. msn機器人/gtalk/機器人/yahoo即時通 同時適用,api發送訊息/註冊聯絡人…功能 1.2. 實務應用中,MSN 要能發送訊息,必須先將欲發送的MSN帳號設定為聯絡人(請參考下面 表列中REGISTER指令),也請參考這個資訊 http://rd-program.blogspot.com/2008/08/msn-bug.html 1.3. 範例中網路連接位置請依照實際情況處理,文件以http://127.0.0.1:8080示意 1.4. 範例中慣例以luke@hotmail.com為msn機器人服務帳號 xue@hotmail.com…為一般聯絡人 1.5. 以下\t 代表tab \n代表unix斷行格式 1.6. 範例中所提到的參數 uids 為多個帳號組合之意,分隔符號為 逗點(,) 但;當只有一個帳號時,不應在後方留置逗點,uids意指msn passport帳號（包含網域）--例:account@hotmail.com 1.7. SOAP範例中使用 func_name(‘parameter’) ; 意指parameter為參數,單引號為標示之用,實際的參數並不包含單引號(‘) 1.8. 回應值除了ADO介面必為big5以外,其餘皆以utf-8字集回應 1.9. 範例中對於目錄的標示 / 與 \ 相同,代表相同的目錄標示 1.a. 範例中如使用到相對路徑 ./ ,其根目錄為c:/msnSDK 1.b. 本文建置放於 ./doc/之下 1.c. 線上狀況(Presence)代碼與中文對照(GTalk/Yahoo即時通已會對應成下列代碼) YAL 已註冊為聯絡人;但對方尚未核准 NLN 線上 BSY 忙碌中 IDL 未使用電腦 FLN 離線 PHN 通話中 AWY 離開 BRB 立刻回來 LUN 外出用餐 HDN 顯示為離線 1.d. CGI範例中常用之URL-encoded對照表(僅供參考,實際應使用您的程式語言函式轉換) 底線(_) -> %5F 逗點(,) -> %2C AT (@) -> %40 空白( ) -> %20 點 (.) -> %2E |
2. 示意圖
※ MSN與MSN小圖均為Microsoft微軟公司在美國和其他國家使用之商標 ※
3. 程式介面型態
3.1. SOAP
3.2. CGI
3.3. ADO(可適用vb6 delphi asp)
4. SOAP 程式介面
4.1. WSDL 位置
http://127.0.0.1:8080/msnSDK/genwsdl-win32
4.2. API Functions
Method | Description |
MSNSDK_VERSION | 查詢msnSDK版本,此版本資訊與文件命名相符,當使用相關方法(Method)前,應先確認版本後才開始呼叫使用,這樣才能讓程式在不同版本之間向下相容 |
GETSPID | 取得授權碼,確認是否可使用API,取得的認證碼有效期限為6小時 |
SENDMSG | 傳送MSN 訊息,其內容msg中文編碼為(utf-8/big5/gbk/gb2312),傳給uids;flags (0 對方離線則不送訊息 1對方離線則訊息是否傳送由系統決定),而uids 允許傳遞給多人,當傳給多人時應使用逗點隔開 備註1:flags 預設為0對方離線則不送訊息 備註2:訊息如需換行,請使用 \n (2個字元) mmsimtype決定訊息的顏色/字型…屬性,請參考最下方的附錄說明: (X-MMS-IM-Format).Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為細明體,當此參數未填時,系統會使用預設值 |
SENDNUDGEMSG | 先傳送來電震動,再傳送MSN 訊息,其內容msg中文編碼為(utf-8/big5/gbk/gb2312),傳給uids;flags (0 對方離線則不送訊息 1對方離線則訊息是否傳送由系統決定),而uids 允許傳遞給多人,當傳給多人時應使用逗點隔開 備註1:flags 預設為0對方離線則不送訊息 備註2:訊息如需換行,請使用 \n (2個字元) mmsimtype決定訊息的顏色/字型…屬性,請參考最下方的附錄說明: (X-MMS-IM-Format).Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為細明體,當此參數未填時,系統會使用預設值 |
PRESENCE | 查詢某個帳號(或全部)的線上狀況 |
REGISTER | 依照系統自動隨機選擇msnSDK服務帳號來註冊帳號聯絡人 備註:MSN本身有一個bugs,請參考http://rd-program.blogspot.com/2008/08/msn-bug.html |
REGISTER_ATMSN | 依照系統自動隨機選擇msnSDK服務帳號來註冊帳號聯絡人,但強制此帳號註冊在MSN 備註:這個函式用於使用yahoo帳號作為MSN使用 |
UNREGISTER | 取消聯絡人註冊 |
SERVICEID_STATISTIC | 每個msnSDK serviceID目前註冊的人數 |
KW2PASSPORT_ADD | 新增一組關鍵字(群組/個別非MSN帳號)與MSN帳號的對應 |
KW2PASSPORT_DELETE | 刪除一組關鍵字(群組/個別非MSN帳號)與MSN帳號的對應 |
KW2PASSPORT_MODIFY | 修改一組關鍵字(群組/個別非MSN帳號)與MSN帳號的對應 |
KW2PASSPORT_APPEND | 在一組關鍵字(群組/個別非MSN帳號)與MSN帳號的對應裏添加MSN帳號資訊 |
KW2PASSPORT_FIND | 尋找關鍵字與MSN帳號的對應的內容 |
KW2PASSPORT_KWLIST | 表列系統中所有關鍵字 |
SENDMSG_BY_KEYWORD | 使用關鍵字對應出來的MSN帳號傳送訊息 備註1:flags 預設為0對方離線則不送訊息 備註2:訊息如需換行,請使用 \n (2個字元) 錄說明: (X-MMS-IM-Format).Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為細明體,當此參數未填時,系統會使用預設值 |
SENDNUDGEMSG_BY_KEYWORD | 使用關鍵字對應出來的MSN帳號傳送來電震動與訊息 備註1:flags 預設為0對方離線則不送訊息 備註2:訊息如需換行,請使用 \n (2個字元) 錄說明: (X-MMS-IM-Format).Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為細明體,當此參數未填時,系統會使用預設值 |
MOD_NICKNAME | 修改暱稱(希望其他人看到的名稱) |
MOD_PSM | 修改個人資訊(希望聯絡人看到的個人資訊) |
QRY_NICKNAME | 查詢暱稱 |
QRY_PSM | 查詢個人資訊 |
MSNSERVICE_STOP | 關閉 msnSDK 服務 |
MSNSERVICE_START | 啟動 msnSDK 服務 |
MSG_SUSPEND | 關閉/啟用/查詢 訊息通知,一經關閉,所有訊息不再傳遞 |
ADPUSH | 資訊推撥,取代選單上的<ad id=’訊息編號’/>標籤 |
ADCANCEL | 取消推撥訊息 |
MSNSDK_VERSION
參數(Parameters) | MSNSDK_VERSION 沒有任何參數 |
回應值(Returns) | (成功) 1\tVersion: 1.0.3\n |
GETSPID
Parameters | Description |
userid | 認證所使用的帳號 |
passwd | 認證所使用的密碼 |
回應值(Returns) : (成功) 1\tsession\n 如為CGI/ADO 程式介面,同時會設定Cookie,取得的認有效期限為6小時 (失敗) 0\t錯誤的認證資訊\n |
SENDMSG
Parameters | Description |
uids | 傳遞訊息的目的帳號,uids 允許傳遞給多人,當為多人時應使用逗點隔開 |
msg | 欲傳遞的訊息內容,訊息如需換行,請使用 \n (2個字元) |
encoding | 傳遞的訊息中文編碼(utf-8/big5/gbk/gb2312) |
flags | 0 對方離線則不送訊息 1對方離線則訊息是否傳送由系統決定 |
mmsimtype | 決定訊息的顏色/字型…屬性,請參考最下方的附錄說明: (X-MMS-IM-Format) Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為新細明體 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: SENDMSG(‘*’,'測試訊息’,'utf-8’,’0’,’CO=ff0000; FN=Verdana’,’53ik4w45FPeMiZb2’) 送給所有已註冊的人員,但不在線上者不傳送訊息,訊息的字型為Verdana 顏色為藍色(ff0000) SENDMSG('xue@hotmail.com’, ‘測試訊息’, ‘utf-8’,1,’CO=ff;FN=Verdana’,’53ik4w45FPeMiZb2’) SENDMSG(‘xue1@hotmail.com’,’xue2@hotmail.com’, ‘測試訊息’, ‘utf-8’,1,’CO=ff; FN=Verdana,’53ik4w45FPeMiZb2’)
回應值(Returns): (成功) 1\t資料已送進MQUEUE排程\t傳送帳號\n (失敗) 0\t失敗原因\t傳送帳號\n |
SENDNUDGEMSG
Parameters | Description |
uids | 傳遞訊息的目的帳號, uids 允許傳遞給多人,當為多人時應使用逗點隔開 |
msg | 欲傳遞的訊息內容,訊息如需換行,請使用 \n (2個字元) |
encoding | 傳遞的訊息中文編碼(utf-8/big5/gbk/gb2312) |
flags | 0 對方離線則不送訊息 1對方離線則訊息是否傳送由系統決定 |
mmsimtype | 決定訊息的顏色/字型…屬性,請參考最下方的附錄說明: (X-MMS-IM-Format) Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為新細明體 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: SENDNUDGEMSG(‘*’,'測試訊息’,'utf-8’,1,’CO=ff0000; FN=Verdana’,’53ik4w45FPeMiZb2’) 送給所有已註冊的人員,而不在線上者依照系統設定決定是否傳送離線訊息,訊息的字型為Verdana顏色為藍色 SENDNUDGEMSG('xue@hotmail.com’, '測試訊息’, 'utf-8’,0,’CO=ff; FN=Verdana’, ’53ik4w45FPeMiZb2’) SENDNUDGEMSG('xue1@hotmail.com,xue2@hotmail.com’, '測試訊息’, 'utf-8’,0,’CO=ff; FN=Verdana’, ’53ik4w45FPeMiZb2’)
回應值(Returns): (成功) 1\t資料已送進MQUEUE排程\t傳送帳號\n (失敗) 0\t失敗原因\t傳送帳號\n |
PRESENCE
Parameters | Description |
uids | 欲查詢線上狀態的帳號,uids 允許傳遞給多人,當為多人時應使用逗點隔開, * 代表所有人 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: PRESENCE(‘*’, ’53ik4w45FPeMiZb2’) 查詢所有人員在線狀況 PRESENCE(`xue1@hotmail.com`,’53ik4w45FPeMiZb2’) 查詢xue1@hotmail.com 的在線狀況, PRESENCE(`xue1@hotmail.com,xue2@hotmail.com`,’53ik4w45FPeMiZb2’) 查詢xue1@hotmail.com , xue2@hotmail.com 兩個人線上的狀況
回應值(Returns): (成功) 1\t註冊的機器人帳號\t線上狀況代碼\t查詢的帳號\n (失敗) 0,失敗原因\t查詢的帳號\n |
REGISTER
Parameters | Description |
uids | 欲設定為聯絡人的msn帳號,uids 允許傳遞多人,當為多人時應使用逗點隔開 |
msg | 邀請對方時顯示的訊息 |
encoding | 邀請對方時顯示訊息的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: REGISTER(‘xue@hotmail.com’ ,’請加入我為聯絡人’ ,’big5’,’53ik4w45FPeMiZb2’) 邀請xue@hotmail.com 為msnSDK的聯絡人,且在邀請時顯示 ”請加入我為聯絡人” 這個訊息 REGISTER(‘xue1@hotmail.com,xue2@hotmail.com’,’ msnSDK邀請您’,’big5’,’53ik4w45FPeMiZb2’) 邀請 xue1@hotmail.com, xue2@hotmail.com為msnSDK的聯絡人,且在邀請時顯示 ”msnSDK邀請您” 這個訊息 回應值(Returns): (成功) 1\tmsnSDK服務帳號\t欲註冊帳號\n (失敗) 0\t失敗原因\t欲註冊帳號\n |
REGISTER_ATMSN
Parameters | Description |
uids | 欲設定為聯絡人的msn帳號,uids 允許傳遞多人,當為多人時應使用逗點隔開 |
msg | 邀請對方時顯示的訊息 |
encoding | 邀請對方時顯示訊息的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: REGISTER_ATMSN(‘xue@yahoo.com.tw’ ,’請加入我為聯絡人’ ,’big5’,’53ik4w45FPeMiZb2’) 邀請xue@yahoo.com.tw 為msnSDK的聯絡人,並強制此帳號使用於msn, 且在邀請時顯示 ”請加入我為聯絡人” 這個訊息 REGISTER_ATMSN (‘xue1@ yahoo.com.tw,xue2@ yahoo.com.tw’ ’ msnSDK邀請您’,’big5’,’53ik4w45FPeMiZb2’) 邀請 xue1@ yahoo.com.tw, xue2@yahoo.com.tw為msnSDK的聯絡人,並強制此帳號使用於msn, 且在邀請時顯示 ”請加入我為聯絡人” 這個訊息
回應值(Returns): (成功) 1\tmsnSDK服務帳號\t欲註冊帳號\n (失敗) 0\t失敗原因\t欲註冊帳號\n |
UNREGISTER
Parameters | Description |
uids | 欲移除聯絡人的msn帳號,uids 允許傳遞多人,當為多人時應使用逗點隔開 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: UNREGISTER(‘xue@hotmail.com’ ,’53ik4w45FPeMiZb2’) 將xue@hotmail.com自msnSDK的聯絡人移除 UNREGISTER(‘xue1@hotmail.com,xue2@hotmail.com’ ,’53ik4w45FPeMiZb2’) 將 xue1@hotmail.com, xue2@hotmail.com 自msnSDK的聯絡人移除
回應值(Returns): (成功) 1\tmsnSDK服務帳號\t欲移除聯絡人帳號\n (失敗) 0\t失敗原因\t欲移除聯絡人帳號\n |
SERVICEID_STATISTIC
Parameters | Description |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功)1\tmsnSDK serviceID\t註冊人數\n |
KW2PASSPORT_ADD
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號,請注意！關鍵字不得包含逗點(,) |
uids | 對應的msn聯絡人帳號,遇多人時請以逗點隔開 |
encoding | 關鍵字的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_ADD(‘我的常用聯絡人’,’xue0@hotmail.com, xue1@hotmail.com’,’utf-8’ ,’53ik4w45FPeMiZb2’) 將關鍵字 “我的常用聯絡人”關聯到 xue0@hotmail.com, xue1@hotmail.com 這2個MSN帳號
回應值(Returns): (成功) 1\t對應資訊已建立\n (失敗) 0\t失敗原因\n |
KW2PASSPORT_DELETE
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號,請注意！關鍵字不得包含逗點(,) |
encoding | 關鍵字的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_DELETE(‘我的常用聯絡人’,’utf-8’ ,’53ik4w45FPeMiZb2’) 將關鍵字 “我的常用聯絡人”刪除
回應值(Returns): (成功) 1\t對應資訊已刪除\n (失敗) 0\t失敗原因\n |
KW2PASSPORT_MODIFY
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號,請注意！關鍵字不得包含逗點(,) |
uids | 對應的msn聯絡人帳號,遇多人時請以逗點隔開 |
encoding | 關鍵字的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_MODIFY(‘我的常用聯絡人’ ,’xue3@hotmail.com, xue2@hotmail.com’,’utf-8’ ,’53ik4w45FPeMiZb2’) 修改關鍵字 “我的常用聯絡人”關聯到 xue3@hotmail.com, xue2@hotmail.com 這2個MSN帳號
回應值(Returns): (成功) 1\t對應資訊已修改\n (失敗) 0\t失敗原因\n |
KW2PASSPORT_APPEND
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號,請注意！關鍵字不得包含逗點(,) |
uids | 對應的msn聯絡人帳號,遇多人時請以逗點隔開 |
encoding | 關鍵字的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_APPEND(‘我的常用聯絡人’ ,’xue5@hotmail.com, xue6@hotmail.com’,’utf-8’ ,’53ik4w45FPeMiZb2’) 將 xue5@hotmail.com, xue6@hotmail.com 這2個MSN帳號, 加到關鍵字 “我的常用聯絡人”內
回應值(Returns): (成功) 1\t對應資訊已加入\n (失敗) 0\t失敗原因\n |
KW2PASSPORT_APPEND
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號,請注意！關鍵字不得包含逗點(,) |
uids | 對應的msn聯絡人帳號,遇多人時請以逗點隔開 |
encoding | 關鍵字的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_APPEND(‘我的常用聯絡人’ ,’xue5@hotmail.com, xue6@hotmail.com’,’utf-8’ ,’53ik4w45FPeMiZb2’) 將 xue5@hotmail.com, xue6@hotmail.com 這2個MSN帳號, 加到關鍵字 “我的常用聯絡人”內
回應值(Returns): (成功) 1\t對應資訊已加入\n (失敗) 0\t失敗原因\n |
KW2PASSPORT_FIND
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號,請注意！關鍵字不得包含逗點(,) |
encoding | 關鍵字的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_FIND(‘我的常用聯絡人’ ,’53ik4w45FPeMiZb2’) 查詢關鍵字 “我的常用聯絡人”內的MSN帳號對應
回應值(Returns): (成功) 1\tMSN帳號對應\n (失敗) 0\t失敗原因\n |
KW2PASSPORT_KWLIST
Parameters | Description |
encoding | 回應時使用的中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: KW2PASSPORT_KWLIST(‘utf-8’ ,’53ik4w45FPeMiZb2’) 表列系統目前所有關鍵字,並以utf-8字集做為回應字集
回應值(Returns): (成功) 1\t關鍵字1,關鍵字2,關鍵字3\n (失敗) 0\t沒有找到任何關鍵字\n |
SENDMSG_BY_KEYWORD
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號 |
msg | 欲傳送的訊息,訊息如需換行,請使用 \n (2個字元) |
encoding | 關鍵字與傳送的訊息中文編碼(utf-8/big5/gbk/gb2312) |
flags | 0 對方離線則不送訊息 1對方離線則訊息是否傳送由系統決定 |
mmsimtype | 決定訊息的顏色/字型…屬性,請參考最下方的附錄說明: (X-MMS-IM-Format) Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為新細明體 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: SENDMSG_BY_KEYWORD(‘我的常用聯絡人’,’測試訊息’,’utf-8’,1,’CO=ff; FN=Verdana’,’53ik4w45FPeMiZb2’) 將 測試訊息 這四個字傳遞給 關鍵字 “我的常用聯絡人”所對應的MSN帳號,如果此帳號不在線上則由系統決定是否傳送離線訊息,且訊息為紅色字型為Verdana
回應值(Returns): (成功) 1\t資料已送進MQUEUE排程\t傳送帳號\n (失敗) 0\t失敗原因\t傳送帳號\n |
SENDNUDGEMSG_BY_KEYWORD
Parameters | Description |
keyword | 關鍵字,可能是群組 或是某個非msn帳號 |
msg | 欲傳送的訊息,訊息如需換行,請使用 \n (2個字元) |
encoding | 關鍵字與傳送的訊息中文編碼(utf-8/big5/gbk/gb2312) |
flags | 0 對方離線則不送訊息 1對方離線則訊息是否傳送由系統決定 |
mmsimtype | 決定訊息的顏色/字型…屬性,請參考最下方的附錄說明: (X-MMS-IM-Format) Ex. CO=ff; FN=%E7%B4%B0%E6%98%8E%E9%AB%94; ->訊息為紅色字型為新細明體 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: SENDNUDGEMSG_BY_KEYWORD(‘我的常用聯絡人’,’測試訊息’,’utf-8’,0,’CO=ff; FN=Verdana’,’53ik4w45FPeMiZb2’) 將 來電震動與測試訊息 這四個字傳遞給 關鍵字 “我的常用聯絡人”所對應的MSN帳號,如果此帳號不在線上則不送訊息,且訊息為紅色字型為Verdana
回應值(Returns): (成功) 1\t資料已送進MQUEUE排程\t傳送帳號\n (失敗) 0\t失敗原因\t傳送帳號\n |
MOD_NICKNAME
Parameters | Description |
nickname | 修改想讓其他人看到的暱稱,如果長度>255則系統自動截斷多餘字元 |
encoding | 暱稱所使用中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: MOD_NICKNAME(‘測試1’ ,’utf-8’ ,’53ik4w45FPeMiZb2’) 想讓其他人看到的暱稱修改為測試1
回應值(Returns): (成功) 1\t其他人看到的名稱修改為$nickname\n |
MOD_PSM
Parameters | Description |
Psm | 修改想讓聯絡人看到的名稱,如果長度>255則系統自動截斷多餘字元 |
Encoding | 名稱所使用中文編碼(utf-8/big5/gbk/gb2312) |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
範例: MOD_PSM(‘測試2’ ,’utf-8’ ,’53ik4w45FPeMiZb2’) 想讓聯絡人看到的名稱修改為測試2
回應值(Returns): (成功) 1\t聯絡人看到的個人資訊修改為$psm\n |
QRY_NICKNAME
Parameters | Description |
uid | 要查詢暱稱的msn帳號,若要查機器人現在的帳號,請使用ME |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t暱稱\n (失敗) 0\t失敗原因\n |
QRY_PSM
Parameters | Description |
uid | 要查詢個人資訊的msn帳號,若要查機器人現在的帳號,請使用ME |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t個人資訊\n (失敗) 0\t失敗原因\n |
MSNSDK_STOP
Parameters | Description |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t準備關閉mpmsn service\n |
MSNSDK _START
Parameters | Description |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t準備啟動mpmsn service\n |
MSG_SUSPEND
Parameters | Description |
suspend | 0 暫停訊息傳遞 1開啟訊息傳遞 2查詢狀態 |
uid | 暫停/開啟 的帳號,動作只能處理單一帳號 |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t暫停訊息傳遞\t帳號名稱\n 1\t開啟訊息傳遞\t帳號名稱\n 1\t開啟/暫停\t帳號名稱\n (失敗) 0\t失敗原因\n |
ADPUSH
Parameters | Description |
AdId | 對應互動選單上的訊息編號 <ad id=’adId’/> |
AdText | 訊息資訊 |
AdUrl | 訊息相關連結 |
Encoding | 訊息內容所使用中文編碼(utf-8/big5/gbk/gb2312) |
Session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t已將廣告資訊(adId)放置到伺服器上\n (失敗) 0\t失敗原因\n |
ADCANCEL
Parameters | Description |
adId | 刪除對應互動選單上的訊息編號 <ad id=’adId’/> |
session | SOAP程式介面,需要使用GETSPID所得到的session值,CGI/ADO程式介面則會在GETSPID時得到cookie延續其認證 |
回應值(Returns) : (成功) 1\t已將廣告資訊(adId)移除\n (失敗) 0\t失敗原因\n |
5. CGI/ADO程式介面
5.1. 連接網址: http://127.0.0.1:8080/msnSDK/msn_cgi-win32 實際位置不在127.0.0.1:8080(請參考前述測試申請資訊)
5.2. CGI 程式介面同時支援POST/GET, 但伺服器對於GET的資料傳遞有長度限制,因此雖然msnSDK同時支援POST/GET但使用POST應為比較適當之選擇,而傳遞參數應依據HTTP/1.1標準,對所傳遞之標頭/內容做URL-encoded 例如: V1=1&V1=xue0@hotmail.com, xue1@hotmail.com應為V1=1&V2= xue0%40hotmail%2Ecom %2Cxue1%40hotmail%2Ecom V1=測試訊息 應為 V1=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF <-請注意這個範例所使用的中文編碼為utf-8 5.3. CGI與ADO 介面的參數唯一的不同為,ADO介面多一個額外的參數 RETTYPE=ADO 5.4. 參數傳遞無順序性 V1=1&V2=2 與 V2=2&V1=1 結果相同 5.5. 使用POST方法應指定Content-Type 標頭的值為 application/x-www-form-urlencoded,且標頭應包含Content-Length 5.6. 有關CGI與ADO的參數;可參考SOAP 介面說明,例如: 傳送MSN 訊息,把內容msg,中文編碼為(utf-8/big5/gbk/gb2312),傳給uids,且當flags=0 對方離線則不送訊息, flags=1對方離線則訊息是否傳送由系統決定 ps.請注意！以下範例;參數uids為了顯示方便沒有做URL-encoded
CGI程式介面(POST BODY/GET Header): FUNC=SENDMSG&UIDS=xue0@hotmail.com,xue1@hotmail.com&msg=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF&encoding=utf-8&flags=0&mmsimtype=&session=53ik4w45FPeMiZb2
(GET Request) :網路封包範例 GET /msnSDK/msn_cgi-win32?FUNC=SENDMSG&UIDS=xue0@hotmail.com,xue1 @hotmail.com&msg=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF&encoding=utf-8&flags=0&mmsimtype=&session=53ik4w45FPeMiZb2 HT TP/1.1 User-Agent: msnSDK Host: 127.0.0.1:8080 Content-Length: 0 Ps.不指定 mmsimtype,則訊息的字型顏色…使用預設值 (POST Request) :網路封包範例 POST /msnSDK/msn_cgi-win32 HTTP/1.1 User-Agent: msnSDK Content-Type: application/x-www-form-urlencoded Host: 127.0.0.1:8080 Content-Length: 126 FUNC=SENDMSG&UIDS=xue0@hotmail.com,xue1@hotmail.com&msg=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF&encoding=utf-8&flags=0&mmsimtype=&session=53ik4w45FPeMiZb2 Ps.不指定 mmsimtype,則訊息的字型顏色…使用預設值 (Response) :網路封包範例 HTTP/1.1 200 OK Date: Fri, 10 Oct 2008 16:44:46 GMT Server: Apache Expires: Mon, 26 Jul 1997 05:00:00 GMT Cache-Control: no-cache, no-store Pragma: no-cache, no-cache Connection: close Content-Type: text/html; charset=utf-8 1 資料已送進MQUEUE排程 xue0@hotmail.com 1 資料已送進MQUEUE排程 xue1@hotmail.com ADO程式介面(POST BODY/GET Header): FUNC=SENDMSG&UIDS=xue0@hotmail.com,xue1@hotmail.com&msg=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF&encoding=utf-8&flags=0&mmsimtype=&session=53ik4w45FPeMiZb2&RETTYPE=ADO Ps.不指定 mmsimtype,則訊息的字型顏色…使用預設值 (GET Request) :網路封包範例 GET /msnSDK/msn_cgi-win32?FUNC=SENDMSG&UIDS=xue0@hotmail.com,xue1 @hotmail.com&msg=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF&encoding=utf-8&flags=0&mmsimtype=&session=53ik4w45FPeMiZb2&retype=ADO HTTP/1.1 User-Agent: msnSDK Host: 127.0.0.1:8080 Content-Length: 0 Ps.不指定 mmsimtype,則訊息的字型顏色…使用預設值 (POST Request):網路封包範例 POST /msnSDK/msn_cgi-win32 HTTP/1.1 User-Agent: msnSDK Content-Type: application/x-www-form-urlencoded Host: 127.0.0.1:8080 Content-Length: 138 FUNC=SENDMSG&UIDS=xue0@hotmail.com,xue1@hotmail.com&msg=%E6%B8%AC%E8%A9%A6%E8%A8%8A%E6%81%AF&encoding=utf-8&flags=0&mmsimtype=&session=53ik4w45FPeMiZb2&rettype=ADO Ps.不指定 mmsimtype,則訊息的字型顏色…使用預設值 (Response) :網路封包範例 HTTP/1.1 200 OK Date: Fri, 10 Oct 2008 16:51:46 GMT Server: Apache Expires: Mon, 26 Jul 1997 05:00:00 GMT Cache-Control: no-cache, no-store Pragma: no-cache, no-cache Connection: close Content-Type: text/html; charset=big5 <?xml version="1.0" encoding="big5" ?> <xml xmlns:s="uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882" xmlns:dt="uuid:C2F41010-65B3-11d1-A29F-00AA00C14882" xmlns:rs="urn:schemas-microsoft-com:rowset" xmlns:z="#RowsetSchema"> <s:Schema id="RowsetSchema"> <s:ElementType name="row" content="eltOnly"> <s:AttributeType name="rcode" rs:number="1" rs:nullable="true" rs:write="true"> <s:datatype dt:type="integer" dt:maxLength="1" /> </s:AttributeType> <s:AttributeType name="message" rs:number="2" rs:nullable="true" rs:write="true"> <s:datatype dt:type="string" dt:maxLength="200" /> </s:AttributeType> <s:AttributeType name="info" rs:number="3" rs:nullable="true" rs:write="true"> <s:datatype dt:type="string" dt:maxLength="200" /> </s:AttributeType> <s:extends type="rs:rowbase" /> </s:ElementType> </s:Schema> <rs:data> <z:row rcode="0" message="資料已送進MQUEUE排程" info="xue0@hotmail.com"/> </rs:data> <rs:data> <z:row rcode="0" message="資料已送進MQUEUE排程" info="xue1@hotmail.com"/> </rs:data> </xml> …其餘Function可參考前面表列 |
6. 附錄
X-MMS-IM-Format
The value of the X-MMS-IM-Format field is a list of parameters. You should not expect the paramaters to be arranged in any particular order, or for all the parameters to be included. As of summer 2003, the switchboard server requires FN to be the first parameter if it's included. If it is not, the switchboard will close the connectionwithout sending the message. This is presumably because of a font name bug that existed in older versions of the official client. Because server software constantly changes, third party clients should not rely on this.
The official client always sends these fields in this given order: FN, EF, CO, CS, PF. TheRL parameter is included at the end if right-alignment is used, otherwise it is not included. The official client will accept parameters in any order. The official client always sends uppercase parameter names. Results are unpredictable when sending lowercase or mixed-case parameter names to the official client, but third party clients should still expect names to be in any case. Note that it is impossible to specify font sizes. A client is expected to determine the size of the font in all messages based on user preferences.
Font Name (FN) The FN parameter specifies a font name. The font name must be URL-encoded. For example, to have a font of "MS Sans Serif", you would have to specifyFN=MS%20Sans%20Serif. Font names are not case sensitive, and only spaces should be URL-encoded. URL-encoding other characters such as numbers and letters cause unpredictable results. If the receiving client does not have the specified font, it should make judgment based on the PF and CS parameters. Basically, the client should select whichever available font supports the character set specified in CS and is closest to the category specified in PF. If those parameters are not present, the client should just use a default font. There used to be a bug in the official client that caused it to crash upon receiving a message with a font that contained many %20s. To prevent this from happening, MSN patched the switchboard server so that it would close the connection if a principal attempts to do this.
Effects (EF) The EF parameter specifies optional style effects. Possible effects are bold, italic, underline, and strikethrough. Each effect is referred to by its first letter. For example, to make bold-italic text, include the parameter EF=IB or EF=BI. The order does not matter. Any unknown effects are to be ignored. The official client always sends effects in uppercase, and the results are unpredictable when it receives lowercase effects. If there are no effects, just leave the parameter value blank.
Color (CO) The CO parameter specifies a font color. Many versions of the official client limit you to sending only a few select font colors, but it is possible to specify any one of almost 17 million colors (24-bit color). The value of the CO field is a six-character hexadecimal BGR (blue-green-red, the reverse of the standard RGB order seen in HTML) string. The first two characters represent a hexadecimal number from 00 ff (hexadecimal for 255) for the intensity of blue, the second two are for green, and the third two are for red. For example, to make a full red color, send CO=0000ff. The official client always sends lowercase hexadecimal letters, but it will accept uppercase letters just the same. The official client also cuts off all leading zeros in outgoing messages. For example, 0000ff could be expressed as ff, but both are valid. Black may be expressed as simply 0. Other variations such as 7-character strings or unusual characters cause unpredictable results. If you are used to dealing with colors in HTML, just omit the hash sign and reverse the order of the colors. If you are not used to expressing colors in hexadecimal like this, you might findthis tutorial useful, but remember that MSN expresses colours in the order of blue-green-red and can omit leading zeros.
Character Set (CS) The term "character set" is quite ambiguous. The charset=UTF-8 in the Content-Typefield has a completely different meaning to the CS parameter in the X-MMS-IM-Formatfield. "Character set", as used in the X-MMS-IM-Format field, refers to the set of characters which a font must know how to translate into squiggles ("glyphs") on the screen. It's used mostly in the Windows world, and is increasingly a legacy from the time before Unicode was well supported. A font must support at least one character set, but may support more than one - for example, "Wingdings" supports the Symbol character set, "Verdana" supports the Western, Greek, Turkish, Central European, and Cyrillic character sets. Some background information on character sets is available on this MSDN page. Character sets are identified in the CS parameter with one or two hexadecimal digits (leading zeros are dropped by the official client and are ignored if present), representing the numerical value Windows uses for the character set. Here is the full list of Windows' predefined character sets:
0 - ANSI_CHARSET ANSI characters 1 - DEFAULT_CHARSET Font is chosen based solely on name and size. If the described font is not available on the system, Windows will substitute another font. 2 - SYMBOL_CHARSET Standard symbol set 4d - MAC_CHARSETLT Macintosh characters 80 - SHIFTJIS_CHARSET Japanese shift-JIS characters 81 - HANGEUL_CHARSET Korean characters (Wansung) 82 - JOHAB_CHARSET Korean characters (Johab) 86 - GB2312_CHARSET Simplified Chinese characters (Mainland China) 88 - CHINESEBIG5_CHARSET Traditional Chinese characters (Taiwanese) a1 - GREEK_CHARSET Greek characters a2 - TURKISH_CHARSET Turkish characters a3 - VIETNAMESE_CHARSET Vietnamese characters b1 - HEBREW_CHARSET Hebrew characters b2 - ARABIC_CHARSET Arabic characters ba - BALTIC_CHARSET Baltic characters cc - RUSSIAN_CHARSET_DEFAULT Cyrillic characters de - THAI_CHARSET Thai characters ee - EASTEUROPE_CHARSET Sometimes called the "Central European" character set, this includes diacritical marks for Eastern European countries ff - OEM_DEFAULT Depends on the codepage of the operating system You should not assume that clients receiving your messages will understand all character sets (for example, Windows NT 3.51 has very poor character set support). MSN Messenger only allows you to specify a single character set in a CS field. This charset is arbitrary, but it is advisable to make it the one which will cause the most characters to be displayed correctly. The official client just offers the user a list of character sets supported by your chosen font.
Pitch and Family (PF) The PF family defines the category that the font specified in the FN parameter falls into. This parameter is used by the receiving client if it does not have the specified font installed. The value is a two-digit hexadecimal number. When programming with Windows APIs, this value is the PitchAndFamily value in RichEdit and LOGFONT. The first digit of the value represents the font family. Below is a list of numbers for the first digit and the font families they represent. This list was adapted from this MSDN page.
0_ - FF_DONTCARE Specifies a generic family name. This name is used when information about a font does not exist or does not matter. The default font is used. 1_ - FF_ROMAN Specifies a proportional (variable-width) font with serifs. An example is Times New Roman. 2_ - FF_SWISS Specifies a proportional (variable-width) font without serifs. An example is Arial. 3_ - FF_MODERN Specifies a monospace font with or without serifs. Monospace fonts are usually modern; examples include Pica, Elite, and Courier New. 4_ - FF_SCRIPT Specifies a font that is designed to look like handwriting; examples include Script and Cursive. 5_ - FF_DECORATIVE Specifies a novelty font. An example is Old English. The second digit represents the pitch of the font - in other words, whether it is monospace or variable-width. _0 - DEFAULT_PITCH Specifies a generic font pitch. This name is used when information about a font does not exist or does not matter. The default font pitch is used. _1 - FIXED_PITCH Specifies a fixed-width (monospace) font. Examples are Courier New and Bitstream Vera Sans Mono. _2 - VARIABLE_PITCH Specifies a variable-width (proportional) font. Examples are Times New Roman and Arial. Below are some PF values and example fonts that fit the category. 12 Times New Roman, MS Serif, Bitstream Vera Serif 22 Arial, Verdana, MS Sans Serif, Bitstream Vera Sans 31 Courier New, Courier 42 Comic Sans MS
Right alignment (RL) The RL parameter specifies whether a message should be right-aligned or not. It's value is1 if the message is right-aligned. The official client always omits this parameter unless the value is 1, but any other value does nothing and keeps the message left-aligned.
Examples X-MMS-IM-Format: FN=MS%20Sans%20Serif; EF=; CO=0; CS=0; PF=22 This X-MMS-IM-Format field expresses the MS Sans Serif font with no effects and a black colour. X-MMS-IM-Format: FN=Comic%20Sans%20MS; EF=S; CO=800000; CS=0; PF=42 This field expresses the Comic Sans MS font in a dark blue colour, underlined, and bold. X-MMS-IM-Format: FN=Verdana; CO=ff; EF=UB; PF=22; CS=cc This field expresses the Verdana font in full red colour, with the strikeout effect, and with a Cyrillic charset. The parameters are in an unusual order, but as long as FN is in the front, it's all right. X-MMS-IM-Format: FN=Courier%20New; EF=; CO=ff00ff; CS=0; PF=31 This field expresses the Courier New font in a bright magenta colour with no effects. X-MMS-IM-Format: FN=My%20Hebrew%20Font; EF=; CS=b1; PF=00; RL=1 This field expresses a made up font called My Hebrew Font with no specified colour, no effects, a Hebrew charset, and right-alignment. |
中文字體對照
標楷體 | FN=%E6%A8%99%E6%A5%B7%E9%AB%94; |
細明體 | FN=%E7%B4%B0%E6%98%8E%E9%AB%94; |
新細明體 | FN=%E6%96%B0%E7%B4%B0%E6%98%8E%E9%AB%94; |
微軟正黑 | FN=%E5%BE%AE%E8%BB%9F%E6%AD%A3%E9%BB%91%E9%AB%94; |
下一篇：成為電丸機器人的好友