> For the complete documentation index, see [llms.txt](https://jihsunfutures.gitbook.io/mdcapi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jihsunfutures.gitbook.io/mdcapi/jiuc-han-shu-ku.md). # 九、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](/mdcapi/jiuc-han-shu-ku.md#9-2-1-mdcalistener-shi-jian-wei-zhi-miao-shu-jie-gou)) \ 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 狀態或期間。 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) #### 9.1.3.3 mdca\_connection\_close 方法 要求回收連線物件 **函數原型:** ``` Mdca_Result mdca_connection_close(Mdca_Handle handle); ``` **參數:** \ handle: 連線物件的 Handle **返回值:** \ 成功，Mdca\_R\_Success 表示連線已回收。 \ 失敗，Mdca\_R\_SessionNotExist 表示不存在這 Handle 連線。 **備註:** \ 此方法會導致存在的連線也一併中斷。 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) #### 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 狀態或期間。 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) #### 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 連線。 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **特別說明:** \ out\_info 字串內容格式如下 \ Key: Value \n (換行) **Key: Value** | Key | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ID | 登入帳號 | | Name | 使用者名稱 | | Expire | 使用到期日 | | Exchange |

Exch,Bound,Days,Minutes,Ticks,Depths
Exch: 支援交易所代碼
Bound: 可以訂閱的上限 (-1 = 無限制)
Days: 可回補 日線 的極限日期
Minutes: 可回補 分線 的極限日期
Ticks: 可回補 Tick 的極限日期
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, 連線尚未準備好,無法使用 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) #### 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，連線尚未準備好,無法使用 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) ### 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](/mdcapi/qic-c++-cchang-shu-zi-liao.md#713-quotationtype-hang-qing-chu-li-qi-hao)) **返回值:** \ Mdca\_R\_Success , 成功!\ Mdca\_R\_MissImplement , mdca\_listener::mdcal\_quotation\_change 事件未設定, 呼叫無意義 Mdca\_R\_SessionNotComplete , 連線尚未準備好,無法使用 \ Mdca\_R\_InvalidArgument , 參數不合法 \ Mdca\_R\_SubscribeDenied , 沒有訂閱權限或已達上限 \ Mdca\_R\_SubscribeExist , 訂閱已經存在 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **特別說明:** 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](/mdcapi/qic-c++-cchang-shu-zi-liao.md#713-quotationtype-hang-qing-chu-li-qi-hao)) **返回值:** \ Mdca\_R\_Success , 成功! Mdca\_R\_SessionNotComplete , 連線尚未準備好,無法使用 Mdca\_R\_InvalidArgument , 參數不合法 \ Mdca\_R\_UnsubscribeNotExist , 解訂閱對象不存在 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **特別說明:** \ 支援全交易所解訂閱，代碼同訂閱。 #### 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 , 沒有查詢權限或已達上限 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **特別說明:** 支援全交易所查詢，代碼同訂閱。 ### 9.1.7 即時與歷史查詢 #### 9.1.7.1 mdca\_history\_request 方法 歷史資料查詢訂閱 **說明:** 此呼叫向伺服端要求資料，取得伺服回應時，會從 [mdca\_listener::history\_response](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#818-historyresponse-li-shi-cha-xun-hui-ying-zi-liao)中得到一次性完整的資料結構內容。 **函數原型:** ``` Mdca_Result mdca_history_request(Mdca_Handle handle, LPMdcs_RequestArgument request_argument); ``` **參數:** \ handle: 連線物件的 Handle \ request\_argument: 查詢參數 (參 [Mdcs\_RequestArgument](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#810-quotationdeal-hang-qing-cheng-jiao-zi-liao-jie-gou)) **返回值:** \ 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 得到說明 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **說明:** \ 返回成功時，表示參數的邏輯性正確，並向伺服端要求資料，當伺服器成功回應時[mdca\_listener::history\_response](/mdcapi/jiuc-han-shu-ku.md#9-2-13-historyresponse-shi-jian-fang-fa) 將會觸發供資料的取得，若伺服器無法完成，或是您的查詢超出權限時，您將會收到 [mdca\_listener::history\_response](/mdcapi/jiuc-han-shu-ku.md#9-2-13-historyresponse-shi-jian-fang-fa) 事件，並取得錯誤碼 (error\_code) 與 錯誤說明 (error\_message)。 **特別說明 request\_argument** \ argument.Realtime = ture，會訂閱並維護資料型態的資料內容，並多次進入 [mdca\_listener::history\_response](/mdcapi/jiuc-han-shu-ku.md#9-2-13-historyresponse-shi-jian-fang-fa) 供使用。 **注意:** \ 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 不存在。 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) ### 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: 跳動資訊不足 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **舉列:** \ 若為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: 跳動資訊不足 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) #### 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: 跳動資訊不足 ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) #### 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 , 跳動資訊不足 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) \ 注意: \ out\_point 指標資源為 MDC 建立，你必須使用 [mdca\_free](/mdcapi/jiuc-han-shu-ku.md#9-1-91-mdcafree-fang-fa) 釋放資源。 #### 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: 跳動資訊不足 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **備註:** \ out\_strings 為字串串列，串列即字串接續於 (null-terminal) 為下一個字串，連續 二個 (null-terminal) 即為結束。\ Ex: \[Text] \0 \[Text] \0 ….. \0 \[Text] \0 \0 \ \ 注意: \ out\_strings 指標資源為 MDC 建立，你必須使用 [mdca\_free](/mdcapi/jiuc-han-shu-ku.md#9-1-91-mdcafree-fang-fa) 釋放資源。 #### 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: 跳動資訊不足 \ ※詳細返回值說明，可參考 [錯誤代碼說明](/mdcapi/shi-4e8c-cuo-wu-dai-ma-shuo-ming.md) **舉例:** 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](/mdcapi/jiuc-han-shu-ku.md#9-1-93-mdcalogflag-fang-fa)) **返回值:** \ 成功，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](/mdcapi/qic-c++-cchang-shu-zi-liao.md#72-connectionstate-lian-xian-zhuang-tai)) \ 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](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#812-quotationptr-shi-jian-shi-yong-hang-qing-jie-gou-zhi-wei-qi)) \ state: 異動資料狀態 (參 [Mdca\_QS\_XXXXXX](/mdcapi/qic-c++-cchang-shu-zi-liao.md#72-connectionstate-lian-xian-zhuang-tai)) **說明:** \ cpQuotation 分類成員中，有二個重要的旗號說明 \ cpQuotation->###->\_flag.Exist 欄位值存在判斷用旗號 (你可用 & 邏輯來判斷) \ cpQuotation->###->\_flag.Update 欄位值有變動時旗號 (你可用 & 邏輯來判斷) | Exist | Update | 說明 | | ----- | ------ | -------------- | | 1 | 0 | 本次事件下，並無異動 | | 1 | 1 | 本次事件下，有欄位變動 | | 0 | 0 | 無值 (不使用,或是沒資料) | | 0 | 1 | 被清為空值 (多半為清盤時) | ※有值->無值，一樣會有 Update flag \ ※清除數值欄位的值會被設為 0 以下我們以 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](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#814-requestargument-cha-xun-can-shu)) \ response: 查詢回應結構 ([LPMdcs\_CommodityResponse](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#87-commodityresponse-shang-pin-zi-xun-cha-xun-hui-ying-zi-liao)) #### 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](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#813-quotationresponse-hang-qing-kuai-zhao-hui-ying)) #### 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](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#86-commodity-shang-pin-zi-liao) ) \ method: 商品變動的方式 (可參 [CommodityMethod](/mdcapi/qic-c++-cchang-shu-zi-liao.md#725-commoditymethod-shang-pin-bian-dong-fang-shi) ) #### 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](/mdcapi/bac-c++-c-gong-yong-zi-liao-jie-gou.md#819-continuouscode-lian-xu-yue-shang-pin-zi-xun))