第 5 章外掛程式的 MySQL 服務

MySQL 伺服器外掛程式可以存取伺服器「外掛程式服務」。外掛程式服務介面會公開外掛程式可以呼叫的伺服器功能。它補充了外掛程式 API，並具有這些特性：

服務讓外掛程式可以使用一般的函式呼叫來存取伺服器內的程式碼。服務也適用於可載入的函式。
服務具有可攜性，並可在多個平台上運作。
介面包含版本控制機制，因此可以在載入時針對外掛程式版本檢查伺服器支援的服務版本。版本控制可保護伺服器提供的服務版本與外掛程式預期或需要的服務版本之間的相容性。
如需測試外掛程式服務的外掛程式相關資訊，請參閱 MySQL 伺服器 Doxygen 文件中的外掛程式服務測試外掛程式章節，該文件位於 https://mysqldev.dev.org.tw/doc/index-other.html。

外掛程式服務介面與外掛程式 API 的不同之處如下：

外掛程式 API 可讓伺服器使用外掛程式。呼叫權限在伺服器端，由伺服器叫用外掛程式。這可讓外掛程式擴展伺服器功能或註冊以接收有關伺服器處理的通知。
外掛程式服務介面可讓外掛程式呼叫伺服器內的程式碼。呼叫權限在外掛程式端，由外掛程式叫用服務函式。這可讓伺服器中已實作的功能供許多外掛程式使用；他們不需要個別自行實作。

若要判斷存在哪些服務以及他們提供哪些函式，請查看 MySQL 原始碼發行版本的 include/mysql 目錄。相關檔案為：

plugin.h 包含 services.h，這是包含所有可用的服務特定標頭檔案的「總括」標頭。
服務特定的標頭名稱格式為 service_xxx.h。

每個服務特定的標頭都應包含註解，這些註解提供特定服務的完整使用文件，包括哪些服務函式可用、它們的呼叫序列和傳回值。

對於希望修改伺服器以新增新服務的開發人員，請參閱 MySQL 內部：外掛程式的 MySQL 服務。

可用的服務包括以下項目：

get_sysvar_source：一種服務，可讓外掛程式擷取系統變數設定的來源。
locking_service：一種服務，可實作具有三個屬性的鎖定：鎖定命名空間、鎖定名稱和鎖定模式。此鎖定介面可在兩個層級存取：1) 在 SQL 層級，作為一組可載入的函式，每個函式都會對應到對服務常式的呼叫；2) 作為 C 語言介面，可從伺服器外掛程式或可載入的函式作為外掛程式服務呼叫。如需詳細資訊，請參閱鎖定服務。
my_plugin_log_service：一種服務，可讓外掛程式報告錯誤並指定錯誤訊息。伺服器會將訊息寫入其錯誤記錄檔。
status_variable_registration。用於註冊狀態變數的服務。
my_thd_scheduler：供外掛程式選取線程排程器的服務。
mysql_keyring：用於金鑰環儲存的服務，可在兩個層級存取：1) 在 SQL 層級，作為一組可載入的函式，每個函式都會對應到對服務常式的呼叫；2) 作為 C 語言介面，可從伺服器外掛程式或可載入的函式作為外掛程式服務呼叫。如需詳細資訊，請參閱金鑰環服務。
mysql_password_policy：用於密碼驗證和強度檢查的服務。
plugin_registry_service：MySQL 伺服器包含一個基於組件的基礎結構，用於改善伺服器的可擴充性；請參閱 MySQL 組件。但是，MySQL 外掛程式使用早於組件介面的介面。plugin_registry_service 可讓外掛程式存取組件登錄及其服務。
security_context：一種服務，可讓外掛程式檢查或操作線程安全性內容。此服務提供設定器和取得器常式，以存取伺服器 Security_context 類別的屬性，包括作業系統使用者和主機、已驗證的使用者和主機，以及用戶端 IP 位址等屬性。
thd_alloc：記憶體配置服務。
thd_wait：供外掛程式報告他們何時要進入休眠或暫停狀態的服務。

本章節的其餘部分說明外掛程式如何使用伺服器功能，該功能以服務的形式提供。另請參閱「守護進程」範例外掛程式的原始碼，該外掛程式使用 my_snprintf 服務。在 MySQL 原始碼發行版本中，該外掛程式位於 plugin/daemon_example 目錄中。

若要從外掛程式內使用一或多個服務，外掛程式原始碼檔案必須包含 plugin.h 標頭檔案，才能存取服務相關資訊：

#include <mysql/plugin.h>

這不代表任何額外的設定成本。外掛程式必須無論如何都包含該檔案，因為它包含每個外掛程式都需要的定義和結構。

若要存取服務，外掛程式會像其他函式一樣呼叫服務函式。

若要報告伺服器將寫入錯誤記錄檔的錯誤，請先選擇錯誤層級。mysql/service_my_plugin_log.h 定義了這些層級：

enum plugin_log_level
{
  MY_ERROR_LEVEL,
  MY_WARNING_LEVEL,
  MY_INFORMATION_LEVEL
};

然後叫用 my_plugin_log_message()：

int my_plugin_log_message(MYSQL_PLUGIN *plugin, enum plugin_log_level level,
                          const char *format, ...);

例如：

my_plugin_log_message(plugin_ptr, MY_ERROR_LEVEL, "Cannot initialize plugin");

某些適用於外掛程式的服務可能由外掛程式提供，因此僅在載入提供服務的外掛程式時才可用。任何使用此類服務的 MySQL 組件都應檢查該服務是否可用。

在您建置外掛程式時，請在連結時使用 -lmysqlservices 旗標來連結 libmysqlservices 程式庫。例如，對於 CMake，請將此放入頂層的 CMakeLists.txt 檔案：

FIND_LIBRARY(MYSQLSERVICES_LIB mysqlservices
 PATHS "${MYSQL_SRCDIR}/libservices" NO_DEFAULT_PATH)

將此放入包含外掛程式原始碼的目錄中的 CMakeLists.txt 檔案：

# the plugin needs the mysql services library for error logging
TARGET_LINK_LIBRARIES (your_plugin_library_name ${MYSQLSERVICES_LIB})

第 5 章 外掛程式的 MySQL 服務

第 5 章外掛程式的 MySQL 服務