PDF (US Ltr) - 420.5Kb
PDF (A4) - 419.3Kb
每個客戶端外掛程式都必須有一個描述符，向客戶端外掛程式 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 * 成員應指定為以 null 結尾的字串。
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函式傳回的任何訊息都必須以 null 結尾，因此最大訊息長度為緩衝區長度減一。接下來的引數會傳遞給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 客戶端外掛程式介面。