PDF (美式信紙) - 420.2Kb
PDF (A4) - 419.0Kb
每個客戶端外掛都必須有一個描述符，以向客戶端外掛 API 提供資訊。描述符結構以一組適用於所有客戶端外掛的固定成員開頭，後接任何特定於外掛類型的成員。
client_plugin.h 檔案中的 st_mysql_client_plugin 結構定義了一個包含通用成員的 「通用」描述符。
struct st_mysql_client_plugin
{
int type;
unsigned int interface_version;
const char *name;
const char *author;
const char *desc;
unsigned int version[3];
const char *license;
void *mysql_api;
int (*init)(char *, size_t, int, va_list);
int (*deinit)();
int (*options)(const char *option, const void *);
};通用 st_mysql_client_plugin 描述符結構成員的使用方式如下。char * 成員應指定為空字元結尾的字串。
type：外掛類型。這必須是client_plugin.h中的外掛類型值之一，例如MYSQL_CLIENT_AUTHENTICATION_PLUGIN。interface_version：外掛介面版本。例如，驗證外掛的此值為MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION。name：一個提供外掛名稱的字串。這是您在呼叫帶有MYSQL_DEFAULT_AUTH選項的mysql_options()，或向 MySQL 客戶端程式指定--default-auth選項時，用於引用外掛的名稱。author：一個命名外掛作者的字串。這可以是您喜歡的任何值。desc：一個提供外掛一般描述的字串。這可以是您喜歡的任何值。version：外掛版本，為一個包含三個整數的陣列，指示主版本、次版本和微小版本。例如，{1,2,3}表示版本 1.2.3。license：一個指定授權類型的字串。mysql_api：供內部使用。在外掛描述符中將其指定為NULL。-
init：一個一次性初始化函式，如果沒有這樣的函式則為NULL。客戶端程式庫會在載入外掛時執行此函式。此函式在成功時返回零，失敗時返回非零值。init函式使用其前兩個引數，在發生錯誤時返回錯誤訊息。第一個引數是指向char緩衝區的指標，第二個引數表示緩衝區長度。init函式返回的任何訊息都必須以空字元結尾，因此最大訊息長度為緩衝區長度減一。接下來的引數會傳遞到mysql_load_plugin()。第一個引數表示還有多少個引數（如果沒有則為 0），後接任何剩餘的引數。 deinit：一個一次性取消初始化函式，如果沒有這樣的函式則為NULL。客戶端程式庫會在解除載入外掛時執行此函式。此函式不接受引數。此函式在成功時返回零，失敗時返回非零值。options：一個處理傳遞到外掛的選項的函式，如果沒有這樣的函式則為NULL。此函式接受兩個引數，分別表示選項名稱和指向其值的指標。此函式在成功時返回零，失敗時返回非零值。
對於給定的客戶端外掛類型，通用描述符成員之後可能會跟隨實現該類型外掛所需的額外成員。例如，用於驗證外掛的 st_mysql_client_plugin_AUTHENTICATION 結構在末尾有一個函式，客戶端程式庫會呼叫該函式來執行驗證。
若要宣告外掛，請使用 mysql_declare_client_plugin() 和 mysql_end_client_plugin 巨集。
mysql_declare_client_plugin(plugin_type)
... members common to all client plugins ...
... type-specific extra members ...
mysql_end_client_plugin;請勿明確指定 type 或 interface_version 成員。mysql_declare_client_plugin() 巨集會使用 plugin_type 引數自動產生其值。例如，像這樣宣告驗證客戶端外掛。
mysql_declare_client_plugin(AUTHENTICATION)
"my_auth_plugin",
"Author Name",
"My Client Authentication Plugin",
{1,0,0},
"GPL",
NULL,
my_auth_init,
my_auth_deinit,
my_auth_options,
my_auth_main
mysql_end_client_plugin;此宣告使用 AUTHENTICATION 引數將 type 和 interface_version 成員設定為 MYSQL_CLIENT_AUTHENTICATION_PLUGIN 和 MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION。
根據外掛類型，描述符在通用成員之後可能會有其他成員。例如，對於驗證外掛，有一個函式（剛剛顯示的描述符中的 my_auth_main()），該函式會處理與伺服器的通訊。請參閱第 4.4.9 節「撰寫驗證外掛」。
一般而言，支援使用驗證外掛的客戶端程式會透過呼叫 mysql_options() 以設定 MYSQL_DEFAULT_AUTH 和 MYSQL_PLUGIN_DIR 選項來載入外掛。
char *plugin_dir = "path_to_plugin_dir";
char *default_auth = "plugin_name";
/* ... process command-line options ... */
mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir);
mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);通常，該程式也會接受 --plugin-dir 和 --default-auth 選項，讓使用者可以覆寫預設值。
如果客戶端程式需要較低層級的外掛管理，客戶端程式庫會包含接受 st_mysql_client_plugin 引數的函式。請參閱 C API 客戶端外掛介面。