---
# System prepended metadata

title: 九、C 函數庫
tags: [行情API技術文件]

---

# 九、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技術文件`