# 九、C 函數庫 ## 9.1 API 清單 ### 9.1.1 界面版本 --- #### 9.1.1.1 mdca_version 方法 取得函數庫相容版本 **函數原型:** ``` Mdca_Version mdca_version(); ``` **返回值:** 函數庫相容版本號。 **相容性問題:** 當您取得的 版本號 & Mdca_Compatibility == Mdca_CurrVer，表示你建置時所引用的標頭檔資料結構，與目前的庫 (dll/so) 相容，您才可以安心叫用。 --- #### 9.1.1.2 mdca_file_version 方法 取得函數庫檔案版本 **函數原型:** ``` Mdct_CPChar mdca_file_version(); ``` **返回值:** 函數庫檔案版本號字串。 ### 9.1.2 資源管理 --- #### 9.1.2.1 mdca_initial 方法 初始化庫資源 **函數原型:** ``` Mdca_Bool mdca_initial(); ``` **返回值:** 成功，返回true，第一次呼叫或是已經呼叫。 失敗，返回false，建立初始化資源失敗。 --- #### 9.1.2.2 mdca_terminal 方法 釋放資源 **函數原型:** ``` Mdca_Bool mdca_terminal(); ``` **返回值:** 成功，返回true，第一次呼叫或是已經呼叫。 失敗，返回false，回收資源失敗。 **備註:** 此方法會導致所有還未釋放的連線全部中斷回收。 ### 9.1.3 連線資訊 --- #### 9.1.3.1 mdca_connection_create 方法 建立連線物件 **函數原型:** ``` Mdca_Handle mdca_connection_create(const mdca_listener* listener, Mdct_Bool auto_reconnect, Mdct_Bool keep_subscribe); ``` **參數:** listener: 提供庫回叫事件的位址 (參 [mdca_listener](/3jSr3fihTyCjq2eTkUKUcw#921-mdca_listener-%E4%BA%8B%E4%BB%B6%E4%BD%8D%E5%9D%80%E6%8F%8F%E8%BF%B0%E7%B5%90%E6%A7%8B)) auto_reconnect: 自動重連 keep_subscribe: 保留訂閱資訊(自動重訂閱) **返回值:** 成功，返回值 > Mdca_H_Fail 即為Handle。 失敗，返回值 = Mdca_H_Fail。 --- #### 9.1.3.2 mdca_connection_start 方法 要求物件開始連線登入程序 **函數原型:** ``` Mdca_Result mdca_connection_start(Mdca_Handle handle, Mdct_CPChar domain, Mdct_CPChar id, Mdct_CPChar password); ``` **參數:** handle: 連線物件的 Handle domain: 連線的 domain (ip:port or domain:port)或是多個以 ; 號串接 (ip:port;ip:port; … ;ip:port)，實作輪流連線備援 id: 登入連線的帳號 password: 登入連線的密碼 **返回值:** 成功，Mdca_R_Success 表示連線動作已開始。 失敗，Mdca_R_SessionNotExist 表示不存在這 Handle 連線。 失敗，Mdca_R_NotSupported 表示已經處於 start 狀態或期間。 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) --- #### 9.1.3.3 mdca_connection_close 方法 要求回收連線物件 **函數原型:** ``` Mdca_Result mdca_connection_close(Mdca_Handle handle); ``` **參數:** handle: 連線物件的 Handle **返回值:** 成功，Mdca_R_Success 表示連線已回收。 失敗，Mdca_R_SessionNotExist 表示不存在這 Handle 連線。 **備註:** 此方法會導致存在的連線也一併中斷。 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) --- #### 9.1.3.4 mdca_connection_start2 方法 要求物件開始連線登入程序 **函數原型:** ``` Mdca_Result mdca_connection_start2(Mdca_Handle handle, Mdct_CPChar domain, Mdct_CPChar id, Mdct_CPChar password, Mdct_CPChar subsys); ``` **參數:** handle: 連線物件的 Handle domain: 連線的 domain (ip:port or domain:port)或是多個以 ; 號串接 (ip:port;ip:port; … ;ip:port)，實作輪流連線備援 id: 登入連線的帳號 password: 登入連線的密碼 subsys: 登入子系統名稱 **返回值:** 成功，Mdca_R_Success 表示連線動作已開始。 失敗，Mdca_R_SessionNotExist 表示不存在這 Handle 連線。 失敗，Mdca_R_NotSupported 表示已經處於 start 狀態或期間。 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) --- #### 9.1.3.5 mdca_get_account_info 方法 取得帳號資訊 **函數原型:** ``` Mdca_Result mdca_get_account_info(Mdca_Handle handle, Mdct_PChar& out_info, Mdct_Size& out_length); ``` **參數:** handle: 連線物件的 Handle out_info: 回傳資料字串指標 out_length: 回傳資料字串長度 **返回值:** 成功，Mdca_R_Success (out_info 需要 mdca_free 釋放) 失敗，Mdca_R_SessionNotExist，表示不存在這Handle 連線。 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **特別說明:** out_info 字串內容格式如下 Key: Value \n (換行) **Key: Value** | Key | Description | | -------- | -------- | | ID | 登入帳號 | | Name | 使用者名稱 | | Expire | 使用到期日 | | Exchange | Exch,Bound,Days,Minutes,Ticks,Depths <br>Exch: 支援交易所代碼<br>Bound: 可以訂閱的上限 (-1 = 無限制)<br>Days: 可回補 日線 的極限日期<br>Minutes: 可回補 分線 的極限日期<br>Ticks: 可回補 Tick 的極限日期<br>Depths: 可回補 Depth 的極限日期 | ### 9.1.4 錯誤資訊 --- #### 9.1.4.1 mdca_get_last_errmsg 方法 取得最後錯誤訊息 **函數原型:** ``` Mdct_CPChar mdca_get_last_errmsg(Mdca_Handle handle); ``` **參數:** handle: 連線物件的 Handle **返回值:** 成功，字串指標。 失敗，NULL，沒有錯誤說明。 **備註:** handle 為指定連線代碼，若不屬於連線服務時，參數 0 可以取得錯誤訊息。 ### 9.1.5 商品資訊 --- #### 9.1.5.1 mdca_commodity_request 方法 商品資訊查詢 **函數原型:** ``` Mdca_Result mdca_commodity_request(Mdca_Handle handle, const Mdct_RequestId rid, Mdct_CPChar exchange, Mdct_CPChar commodity_root, Mdct_CPChar commodity); ``` **參數:** handle: 連線物件的 Handle rid: 查詢唯一識別碼 exchange: 交易所代碼 commodity_root: 商品根(品種)代碼 commodity: 商品代碼 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_MissImplement, mdca_listener::mdcal_commodity_response 事件 未設定, 呼叫無意義 失敗，Mdca_R_SessionNotComplete, 連線尚未準備好,無法使用 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) --- #### 9.1.5.2 mdca_get_continuous 方法 取出連續月資訊 **函數原型:** ``` Mdca_Result mdca_get_continuous(Mdca_Handle handle, LPMdcs_ContinuousCode& out_continuous_array, Mdct_Size& out_length); ``` **參數:** handle: 連線物件的 Handle out_continuous_array: 回傳連續月資訊的指標陣列 out_length: 回傳資料數量 **返回值:** 成功，Mdca_R_Success (out_continuous_array 需 mdca_free 釋放) 失敗，Mdca_R_SessionNotExist，不存在這 Handle 連線。 失敗，Mdca_R_SessionNotComplete，連線尚未準備好,無法使用 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) ### 9.1.6 行情快照訂閱 --- #### 9.1.6.1 mdca_quotation_subscribe 方法 訂閱即時行情 **函數原型:** ``` Mdct_Result mdca_quotation_subscribe(Mdca_Handle handle, Mdct_CPChar exchange, Mdct_CPChar commodity_list, Mdca_Quotation_Type type_flag); ``` **參數:** handle: 連線物件的 Handle exchange: 交易所代碼 commodity_list: 訂閱商品字串串列 (code \t code \t code \t .... \t code) type_flag: 訂閱行情的類型旗號 (參 [QuotationType](/dU9xSl1YTW2oYjzsjHtSZQ#713-QuotationType-%E8%A1%8C%E6%83%85%E8%99%95%E7%90%86%E6%97%97%E8%99%9F)) **返回值:** Mdca_R_Success , 成功! Mdca_R_MissImplement , mdca_listener::mdcal_quotation_change 事件未設定, 呼叫無意義 Mdca_R_SessionNotComplete , 連線尚未準備好,無法使用 Mdca_R_InvalidArgument , 參數不合法 Mdca_R_SubscribeDenied , 沒有訂閱權限或已達上限 Mdca_R_SubscribeExist , 訂閱已經存在 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **特別說明:** code 支援全交易所訂閱，只是使用 “*” 為code 即可。 --- #### 9.1.6.2 mdca_quotation_unsubscribe 方法 解訂閱即時行情 **函數原型:** ``` Mdct_Result mdca_quotation_unsubscribe(Mdca_Handle handle, Mdct_CPChar exchange, Mdct_CPChar commodity_list, Mdca_Quotation_Type type_flag); ``` **參數:** handle: 連線物件的 Handle exchange: 交易所代碼 commodity_list: 解訂閱商品字串串列 (code \t code \t code \t .... \t code) type_flag: 解訂閱行情的類型旗號 (參 [QuotationType](/dU9xSl1YTW2oYjzsjHtSZQ#713-QuotationType-%E8%A1%8C%E6%83%85%E8%99%95%E7%90%86%E6%97%97%E8%99%9F)) **返回值:** Mdca_R_Success , 成功! Mdca_R_SessionNotComplete , 連線尚未準備好,無法使用 Mdca_R_InvalidArgument , 參數不合法 Mdca_R_UnsubscribeNotExist , 解訂閱對象不存在 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **特別說明:** 支援全交易所解訂閱，代碼同訂閱。 --- #### 9.1.6.3 mdca_quotation_request 方法 行情快照查詢 **函數原型:** ``` Mdct_Result mdca_quotation_request (Mdca_Handle handle, const Mdct_RequestId rid, Mdct_CPChar exchange, Mdct_CPChar commodity_list); ``` **參數:** handle: 連線物件的 Handle rid: 查詢識別ID exchange: 交易所代碼 commodity_list: 查詢商品字串串列 (code \t code \t code \t .... \t code) **返回值:** Mdca_R_Success , 成功! Mdca_R_MissImplement , mdca_listener::mdcal_quotation_response 事件未設定, 呼叫無意義 Mdca_R_SessionNotComplete , 連線尚未準備好,無法使用 Mdca_R_InvalidArgument , 參數不合法 Mdca_R_RequestDenied , 沒有查詢權限或已達上限 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **特別說明:** 支援全交易所查詢，代碼同訂閱。 ### 9.1.7 即時與歷史查詢 --- #### 9.1.7.1 mdca_history_request 方法 歷史資料查詢訂閱 **說明:** 此呼叫向伺服端要求資料，取得伺服回應時，會從 [mdca_listener::history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95)中得到一次性完整的資料結構內容。 **函數原型:** ``` Mdca_Result mdca_history_request(Mdca_Handle handle, LPMdcs_RequestArgument request_argument); ``` **參數:** handle: 連線物件的 Handle request_argument: 查詢參數 (參 [Mdcs_RequestArgument](/v-KO6tAmRqmK8ykncHtxSQ#89-QuotationBasic-%E8%A1%8C%E6%83%85%E9%9D%9C%E6%85%8B%E8%B3%87%E6%96%99%E7%B5%90%E6%A7%8B)) **返回值:** Mdca_R_Success , 成功! 已回收連線物件 Mdca_R_MissImplement , mdca_listener::history_response 事件未設定, 呼叫無意 義 Mdca_R_SessionNotComplete , 連線尚未準備好,無法使用 Mdca_R_RequestDenied , 沒有查詢權限或超出查詢範圍 Mdca_R_SubscribeDenied , 查詢所包含的訂閱, 沒有訂閱權限或已達上限 Mdca_R_InvalidRId , 失敗! 查詢識別碼已經存在 Mdca_R_InvalidArgument , 失敗! 參數錯誤，請用 get_last_errmsg 得到說明 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **說明:** 返回成功時，表示參數的邏輯性正確，並向伺服端要求資料，當伺服器成功回應時[mdca_listener::history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 將會觸發供資料的取得，若伺服器無法完成，或是您的查詢超出權限時，您將會收到 [mdca_listener::history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 事件，並取得錯誤碼 (error_code) 與 錯誤說明 (error_message)。 **特別說明 request_argument** argument.Realtime = ture，會訂閱並維護資料型態的資料內容，並多次進入 [mdca_listener::history_response](/3jSr3fihTyCjq2eTkUKUcw#9213-history_response-%E4%BA%8B%E4%BB%B6%E6%96%B9%E6%B3%95) 供使用。 **注意:** argument.Realtime = ture，不使用時呼叫 mdca_history_unsubscribe 方法，來釋放 資源。 --- #### 9.1.7.2 mdca_history_unsubscribe 方法 取消歷史資料訂閱 **說明:** 此呼叫會解除即時行情的訂閱活動，並回收工作。 **函數原型:** ``` Mdca_Result mdca_history_unsubscribe(Mdca_Handle handle, Mdca_RequestId rid); ``` **參數:** handle: 連線物件的 Handle rid: 查詢唯一識別碼 **返回值:** 成功，Mdca_R_Success: 請求成功送出。 失敗，Mdca_R_SessionNotExist: Handle 不存在。 失敗，Mdca_R_InvalidRId: rid 不存在。 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) ### 9.1.8 價格處理函式 --- #### 9.1.8.1 mdca_price_string 方法 價格轉換字串 **說明:** 因為價格存在多種進制與分母，而 MDC 主要提供的價格都是實數 (便於程式交 易計算與應用)，所以你可以透過這個方法，將 Mdct_Price 型態的實數轉換成字 串。 **函數原型:** ``` Mdca_Result mdca_price_string(const LPMdcs_CommodityRoot commodity_root, const LPMdcs_Commodity commodity, const Mdct_Price price, Mdct_PChar io_buffer, Mdct_Int& out_size); ``` **參數:** commodity_root: 商品根資訊 commodity: 商品資訊 price: 價格 io_buffer: 回傳字串緩衝空間 out_size: 指定緩衝長度,並回傳字串長度 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_InvalidArgument: commodity_root = NULL 失敗，Mdca_R_InvalidArgument: commodity = NULL 失敗，Mdca_R_InvalidArgument: commodity_root->PriceScaleCount = 0 失敗，Mdca_R_InvalidArgument: *out_buffer = NULL 失敗，Mdca_R_BufferNotEnough: out_size < output string 失敗，Mdca_R_Fail: 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **舉列:** 若為10 進制，分母為 100 (即小數二位)，10.5 會格式化為 “10.50” 若為32 進制，10.5 => 10 +16/32，會格式化為 “10’16” --- #### 9.1.8.2 mdca_string_price 方法 字串轉換為價格 說明: mdca_price_string 反函式，將字串轉回價格。 **函數原型:** ``` Mdca_Result mdca_string_price(const LPMdcs_CommodityRoot commodity_root, const LPMdcs_Commodity commodity, Mdct_PChar in_price, Mdct_Price& out_price); ``` **參數:** commodity_root: 商品根資訊 commodity: 商品資訊 in_price: 價格字串 out_price: 輸出價格值 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_InvalidArgument: commodity_root = NULL 失敗，Mdca_R_InvalidArgument: commodity = NULL 失敗，Mdca_R_InvalidArgument: commodity_root-> PriceScaleCount = 0 失敗，Mdca_R_InvalidArgument: in_price = NULL 失敗，Mdca_R_Fail: 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) --- #### 9.1.8.3 mdca_pricescale_offset 方法 價格檔位偏移工具 說明: 若想取得某個價格的上一檔 (減少 tick_offset=-1)，或要取得某個價格的下N 檔 (增加 tick_offset=N)。 **函數原型:** ``` Mdca_Result mdca_pricescale_offset(const LPMdcs_CommodityRoot commodity_root, const LPMdcs_Commodity commodity, Mdct_Price& io_price, Mdct_Int tick_offset); ``` **參數:** commodity_root: 商品根資訊 commodity: 商品資訊 io_price: 輸入與傳出價格 tick_offset: 跳動 Tick 數量,正數為加,負數為減 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_InvalidArgument: commodity_root = NULL 失敗，Mdca_R_InvalidArgument: commodity = NULL 失敗，Mdca_R_InvalidArgument: commodity_root-> PriceScaleCount = 0 失敗，Mdca_R_Fail: 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) --- #### 9.1.8.4 mdca_pricescale_values 方法 展開價格檔位至價格陣列 說明: 將價格從小到大 (lower_limit_price 至 upper_limit_price) 展開成價格陣列。 **函數原型:** ``` Mdca_Result mdca_pricescale_values(const Mdct_Price lower_limit_price, const Mdct_Price upper_limit_price, const LPMdcs_CommodityRoot commodity_root, const LPMdcs_Commodity commodity, Mdct_Int& out_count, Mdct_Price** out_point); ``` **參數:** lower_limit_price: 跌停價 (起始展價的價格) upper_limit_price: 跌停價 (起始展價的價格) commodity_root: 商品根資訊 commodity: 商品資訊 out_count: 回傳數量 out_point: 回傳價格陣列資源指標 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_InvalidArgument: lower_limit_price > upper_limit_price 失敗，Mdca_R_InvalidArgument: commodity_root = NULL 失敗，Mdca_R_InvalidArgument: commodity = NULL 失敗，Mdca_R_InvalidArgument: commodity_root-> PriceScaleCount= 0 失敗，Mdca_R_InvalidArgument: *out_point = NULL 失敗，Mdca_R_Fail , 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) 注意: out_point 指標資源為 MDC 建立，你必須使用 [mdca_free](/3jSr3fihTyCjq2eTkUKUcw#9191-mdca_free-%E6%96%B9%E6%B3%95) 釋放資源。 --- #### 9.1.8.5 mdca_pricescale_strings 方法 展開價格檔位至字串串列 **說明:** 將價格從小到大 (lower_limit_price 至 upper_limit_price) 展開成價格字串串 列。 **函數原型:** ``` Mdca_Result mdca_pricescale_strings(const Mdct_Price lower_limit_price, const Mdct_Price upper_limit_price, const LPMdcs_CommodityRoot commodity_root, const LPMdcs_Commodity commodity, Mdct_Int& out_count, Mdct_Char** out_strings); ``` **參數:** lower_limit_price: 跌停價 (起始展價的價格) upper_limit_price: 跌停價 (起始展價的價格) commodity_root: 商品根資訊 commodity: 商品資訊 out_count: 回傳數量 out_strings: 回傳價格字串串列 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_InvalidArgument: lower_limit_price > upper_limit_price 失敗，Mdca_R_InvalidArgument: commodity_root = NULL 失敗，Mdca_R_InvalidArgument: commodity = NULL 失敗，Mdca_R_InvalidArgument: commodity_root-> PriceScaleCount = 0 失敗，Mdca_R_InvalidArgument: *out_strings = NULL 失敗，Mdca_R_Fail: 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **備註:** out_strings 為字串串列，串列即字串接續於 (null-terminal) 為下一個字串，連續 二個 (null-terminal) 即為結束。 Ex: [Text] \0 [Text] \0 ….. \0 [Text] \0 \0 注意: out_strings 指標資源為 MDC 建立，你必須使用 [mdca_free](/3jSr3fihTyCjq2eTkUKUcw#9191-mdca_free-%E6%96%B9%E6%B3%95) 釋放資源。 --- #### 9.1.8.6 mdca_pricescale_detail 方法 取出價格資訊 **說明:** 將價格依檔位資訊拆分出 整數、分子、分母、小數位數。 **函數原型:** ``` Mdca_Result mdca_pricescale_detai (const LPMdcs_CommodityRoot commodity_root, const LPMdcs_Commodity commodity, const Mdct_Price price, Mdct_Price& out_integer, Mdct_Float& out_numerator, Mdct_Float& out_denominator, Mdct_Int& out_numerator_decimal_place, Mdct_Int& out_denominator_digit_place); ``` **參數:** commodity_root: 商品根資訊 commodity: 商品資訊 price: 價格 out_integer: 整數 out_numerator: 分子 out_denominator: 分母 out_numerator_decimal_place: 分子小數位數 out_denominator_digit_place: 分母整數位數 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_InvalidArgument: commodity_root = NULL 失敗，Mdca_R_InvalidArgument: commodity = NULL 失敗，Mdca_R_InvalidArgument: commodity_root-> PriceScaleCount = 0 失敗，Mdca_R_Fail: 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/u5StsYCRRZOMSEVORg_hWg) **舉例:** 10 進制跳動 0.05 (即 5/100 , 分子/分母) 價格 10.15 呼叫後取得 out_integer = 10 (整數 10) out_numerator = 15 (分子 15) out_denominator = 100 (分母 100) out_numerator_decimal_place = 0 (分子小數位數 0) out_denominator_digit_place = 2 (分母整數位數 2) 64 進制跳動 0.015625 (即 1/64, 分子/分母) 價格 30.5 呼叫後取得 out_integer = 30 (整數 30) out_numerator = 32 (分子 32) out_denominator = 64 (分母 64) out_numerator_decimal_place = 0 (分子小數位數 0) out_denominator_digit_place = 2 (分母整數位數 2) 320 進制跳動 0.003125 (即 1/320, 分子/分母) 價格 20.5 呼叫後取得 out_integer = 20 (整數 20) out_numerator = 160 (分子 160) out_denominator = 320 (分母 320) out_numerator_decimal_place = 0 (分子小數位數 0) out_denominator_digit_place = 3 (分母整數位數 3) 32 進制跳動 0.25 時 0.0078125 (即 0.25/32, 分子/分母) 價格 20.5 呼叫後取得 out_integer = 20 (整數 20) out_numerator = 16 (分子 16) out_denominator = 32 (分母 32) out_numerator_decimal_place = 2 (分子小數位數 2) out_denominator_digit_place = 2 (分母整數位數 2) 32 進制跳動 0.5 時 0.015625 (即 0.5/32, 分子/分母) 價格 20.5 呼叫後取得 out_integer = 20 (整數 20) out_numerator = 16 (分子 16) out_denominator = 32 (分母 32) out_numerator_decimal_place = 1 (分子小數位數 1) out_denominator_digit_place = 2 (分母整數位數 2) ### 9.1.9 共用函式 --- #### 9.1.9.1 mdca_free 方法 釋放 api 中建立回傳的資源指標 **函數原型:** ``` Mdct_Void mdca_free(Mdct_Void *point); ``` **參數:** point: api 建立的資源指標 --- #### 9.1.9.2 mdca_log_file 方法 釋放 Log 檔案路徑及檔名 **函數原型:** ``` Mdca_Result mdca_log_file (Mdct_CPChar file_path); ``` **參數:** file_path: 要指定 Log 檔絕對路徑檔案位置 **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_Fail: 不合理的檔案路徑, 或是重開檔案失敗 --- #### 9.1.9.3 mdca_log_flag 方法 設定 Log 項目旗號 **函數原型:** ``` Mdca_Result mdca_log_flag (const Mdct_LogFlag flag); ``` **參數:** flag: 指定 Log 項目旗號值 (請參考 [Mdct_LogFlag]()) **返回值:** 成功，Mdca_R_Success 失敗，Mdca_R_Fail: 開啟檔案失敗 --- ## 9.2 事件回叫 ### 9.2.1 mdca_listener 事件位址描述結構 此結構收納了所有事件的回呼位址，供連線物件回叫事件並處理之，以下為本結構的成員方法。 --- #### 9.2.1.1 connection_state 事件方法 連線狀態事件 **函數原型:** ``` Mdct_Void MdcCallback mdcal_connection_state(const Mdca_Handle handle, const Mdca_Connection_State cstate, Mdct_CPChar description); ``` **參數:** handle: 連線物件的 Handle cstate: 狀態值 ([Mdca_CS_XXXXXX](/dU9xSl1YTW2oYjzsjHtSZQ)) description: 狀態說明 --- #### 9.2.1.2 quotation_change 事件方法 初始化快照資料 及 即時行情變動 事件 **函數原型:** ``` Mdct_Void MdcCallback mdcal_quotation_change(const Mdca_Handle handle, Mdct_CPChar exchange_abbr, Mdct_CPChar commodity_code, const LPMdcs_QuotationPtr cpQuotation, const Mdca_Quotation_State state); ``` **參數:** handle: 連線物件的 Handle exchange_abbr: 交易所縮寫 commodity_code: 商品代碼 cpQuotation: 行情資料結構 (參 [QuotationPtr](/dU9xSl1YTW2oYjzsjHtSZQ#74-QuotationState-%E8%A1%8C%E6%83%85%E8%AE%8A%E5%8B%95%E7%8B%80%E6%85%8B%E6%97%97%E8%99%9F)) state: 異動資料狀態 (參 [Mdca_QS_XXXXXX](/dU9xSl1YTW2oYjzsjHtSZQ#74-QuotationState-%E8%A1%8C%E6%83%85%E8%AE%8A%E5%8B%95%E7%8B%80%E6%85%8B%E6%97%97%E8%99%9F)) **說明:** cpQuotation 分類成員中，有二個重要的旗號說明 cpQuotation->###->_flag.Exist 欄位值存在判斷用旗號 (你可用 & 邏輯來判斷) cpQuotation->###->_flag.Update 欄位值有變動時旗號 (你可用 & 邏輯來判斷) |Exist|Update|說明| |---|---|---| |1|0|本次事件下，並無異動| |1|1|本次事件下，有欄位變動| |0|0|無值 (不使用,或是沒資料)| |0|1|被清為空值 (多半為清盤時)| <font color="#FF5353">※有值->無值，一樣會有 Update flag ※清除數值欄位的值會被設為 0</font> 以下我們以 state 旗號 Mdca_QS_Realtime(即時)，來說明幾個情境 **【成交】** 觸發時 cpQuotation->Deal 至少有幾個欄位必須存在（Exist => Date, Time, LastPrice, Volume, TotalVolume） 當成交時，有可能同日期時間、同價、同單量，所以唯一確定會異動的，應該只 有累加的總量（Update => TotalVolume） C/C++ 判斷程式 ``` #define DealExist (Mdcs_Quot_Deal_Date|Mdcs_Quot_Deal_Time|Mdcs_Quot_Deal_LastPrice|Mdcs_Quot_Deal_Volu me|Mdcs_Quot_Deal_TotalVolume) #define DealUpdate (Mdcs_Quot_Deal_TotalVolume) if ((cpQuotation->Deal->_flag.Exist & DealExist) == DealExist) { // 有成交資料的欄位 if (cpQuotation->Deal->_flag.Update & DealUpdate) { // 有成交資料的即時資料 } } ``` C# 判斷程式 ``` // 判斷即時行情 if ((State & QuotationState.Realtime) == QuotationState.Realtime) { // 判斷成交(Deal) if (Quotation.Deal._flag.IsExistAll(QuotColumnDeal.Date | QuotColumnDeal.Time | QuotColumnDeal.LastPrice | QuotColumnDeal.Volume | QuotColumnDeal.TotalVolume) && Quotation.Deal._flag.IsUpdateAll(QuotColumnDeal.TotalVolume)) { // 有成交, 因為 Date, Time, LastPrice, Volume, TotalVolume 都存在, 而且 TotalVolume 變動 // TODO Deal } } ``` **【清盤】** 觸發時 cpQuotation->Basic->TsState 會有變動，值為 Mdcs_TSS_Clear C/C++ 判斷程式 ``` if (cpQuotation->Basic->_flag.Exist & Mdcs_Quot_Basic_TsState && cpQuotation->Basic->TsState == Mdcs_TSS_Clear) { // 清盤 } ``` C# 判斷程式 ``` if (Quotation.Basic._flag.IsUpdateAll(QuotColumnBasic.TsState) && Quotation.Basic.TsState == TradeSessionState.Clear) { // 清盤 } ``` **【委託檔位】** 只要有 Update 而且 Exist 便是 C/C++ 判斷程式 ``` if (cpQuotation->Depth->_flag.Exist != 0 && cpQuotation->Depth->_flag.Update != 0) { // 有委託檔位的欄位, 而且有變動 } ``` C# 判斷程式 ``` if (Quotation.Depth._flag.Exist != 0 && Quotation.Depth._flag.Update != 0) { // 有檔位變動,而且又都有值存在 } ``` --- #### 9.2.1.3 history_response 事件方法 歷史資料查詢訂閱回應 **函數原型:** ``` Mdct_Void MdcCallback mdcal_history_response(const Mdca_Handle handle, const Mdct_RequestId rid, const LPMdcs_CommodityResponse response); ``` **參數:** handle: 連線物件的 Handle argument: 請求時參數 ([LPMdcs_RequestArgument](/v-KO6tAmRqmK8ykncHtxSQ#89-QuotationBasic-%E8%A1%8C%E6%83%85%E9%9D%9C%E6%85%8B%E8%B3%87%E6%96%99%E7%B5%90%E6%A7%8B)) response: 查詢回應結構 ([LPMdcs_CommodityResponse](/v-KO6tAmRqmK8ykncHtxSQ#818-HistoryResponse-%E6%AD%B7%E5%8F%B2%E6%9F%A5%E8%A9%A2%E5%9B%9E%E6%87%89%E8%B3%87%E6%96%99)) --- #### 9.2.1.4 quotation_response 事件方法 快照行情查詢回傳事件 **函數原型:** ``` Mdct_Void MdcCallback mdcal_quotation_response(const Mdca_Handle handle, const Mdct_RequestId rid, Mdct_CPChar exchange_abbr, Mdct_CPChar commodity_code, const LPMdcs_QuotationPtr cpQuotation, const Mdca_Quotation_State state); ``` **參數:** handle: 此事件的 connection handle rid: 呼叫 quotation_request 時所帶的識別 Id exchange_abbr: 交易所縮寫 commodity_code: 商品代碼 cpQuotation: 行情資料結構 state: 資料狀態 (一定是 Mdca_QS_Snapshot, 若查詢多筆時,要利用Mdca_QS_LastRecord 來識別是否為最後一筆) --- #### 9.2.1.5 commodity_response 事件方法 商品資訊查詢回傳事件 **函數原型:** ``` typedef Mdct_Void MdcCallback mdcal_commodity_response(const Mdca_Handle handle, const Mdct_RequestId rid, const LPMdcs_CommodityResponse response); ``` **參數:** handle: 此事件的 connection handle rid: 呼叫 commodity_request 時所帶的識別 Id response: 查詢回應結構 ([LPMdcs_CommodityResponse](/v-KO6tAmRqmK8ykncHtxSQ#87-CommodityResponse-%E5%95%86%E5%93%81%E8%B3%87%E8%A8%8A%E6%9F%A5%E8%A9%A2%E5%9B%9E%E6%87%89%E8%B3%87%E6%96%99)) --- #### 9.2.1.6 commodity_change 事件方法 商品資訊變動回傳事件 **函數原型:** ``` typedef Mdct_Void MdcCallback mdcal_commodity_change(const Mdca_Handle handle, const LPMdcs_Commodity commodity, const Mdca_Commodity_Method method); ``` **參數:** handle: 此事件的 connection handle commodity: 商品資訊結構 (可參 [Commodity](/v-KO6tAmRqmK8ykncHtxSQ#86-Commodity-%E5%95%86%E5%93%81%E8%B3%87%E6%96%99) ) method: 商品變動的方式 (可參 [CommodityMethod](/dU9xSl1YTW2oYjzsjHtSZQ#725-CommodityMethod-%E5%95%86%E5%93%81%E8%AE%8A%E5%8B%95%E6%96%B9%E5%BC%8F) ) --- #### 9.2.1.7 continuous_change 事件方法 連續月資訊變動事件 **函數原型:** ``` typedef Mdct_Void MdcCallback mdcal_continuous_change(const Mdca_Handle handle, const LPMdcs_ContinuousCode continuous); ``` **參數:** handle: 此事件的 connection handle continuous: 連續月變動項目 ([LPMdcs_ContinuousCode](/dU9xSl1YTW2oYjzsjHtSZQ#725-CommodityMethod-%E5%95%86%E5%93%81%E8%AE%8A%E5%8B%95%E6%96%B9%E5%BC%8F)) --- ###### tags: `行情API技術文件`