文件首頁
MySQL 8.4 C API 開發者指南
下載本手冊
PDF (美式信紙) - 1.4Mb
PDF (A4) - 1.4Mb

5.4.58 mysql_real_connect()

MYSQL *
mysql_real_connect(MYSQL *mysql,
                   const char *host,
                   const char *user,
                   const char *passwd,
                   const char *db,
                   unsigned int port,
                   const char *unix_socket,
                   unsigned long client_flag)

說明

注意

mysql_real_connect() 是一個同步函數。其非同步對應函數為 mysql_real_connect_nonblocking()，供需要與伺服器進行非同步通訊的應用程式使用。請參閱 第 7 章，C API 非同步介面。

若要使用 DNS SRV 記錄進行連線，請使用 mysql_real_connect_dns_srv()。請參閱 第 5.4.59 節，「mysql_real_connect_dns_srv()」。

mysql_real_connect() 嘗試建立與在 host 上執行的 MySQL 伺服器的連線。用戶端程式必須先成功連線到伺服器，才能執行任何其他需要有效 MYSQL 連線處理程式結構的 API 函數。

請依下列方式指定引數

  • 對於第一個引數，請指定現有 MYSQL 結構的位址。在呼叫 mysql_real_connect() 之前，請呼叫 mysql_init() 以初始化 MYSQL 結構。您可以使用 mysql_options() 呼叫變更許多連線選項。請參閱 第 5.4.54 節，「mysql_options()」。

  • host 的值可以是主機名稱或 IP 位址。用戶端嘗試依下列方式連線

    • 如果 host 為 NULL 或字串 "localhost"，則假設為連線至本機主機

      • 在 Windows 上，如果伺服器已啟用共用記憶體連線，則用戶端會使用共用記憶體連線。

      • 在 Unix 上，用戶端會使用 Unix Socket 檔案進行連線。unix_socket 引數或 MYSQL_UNIX_PORT 環境變數可用於指定 Socket 名稱。

    • 在 Windows 上，如果 host 為 "."，或者未啟用 TCP/IP 且未指定 unix_socket 或主機為空，則如果伺服器已啟用具名管道連線，則用戶端會使用具名管道進行連線。如果未啟用具名管道連線，則會發生錯誤。

    • 否則，會使用 TCP/IP。

    您也可以使用 mysql_options() 的 MYSQL_OPT_PROTOCOL 或 MYSQL_OPT_NAMED_PIPE 選項來影響要使用的連線類型。伺服器必須支援連線類型。

  • user 引數包含使用者的 MySQL 登入 ID。如果 user 為 NULL 或空字串 ""，則會假設為目前使用者。在 Unix 中，這是目前的登入名稱。在 Windows ODBC 中，必須明確指定目前使用者名稱。請參閱 連接器和 API 的 Connector/ODBC 區段。

  • passwd 引數包含 user 的密碼。如果 passwd 為 NULL，則僅會檢查 user 表格中具有空白 (空) 密碼欄位的使用者是否有符合項。這讓資料庫管理員能夠設定 MySQL 權限系統，讓使用者根據是否已指定密碼而獲得不同的權限。

    注意

    請勿嘗試在呼叫 mysql_real_connect() 之前加密密碼；密碼加密由用戶端 API 自動處理。

  • user 和 passwd 引數會使用為 MYSQL 物件設定的任何字元集。預設情況下，這是 utf8mb4，但可以在連線之前呼叫 mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") 來變更。

  • db 是資料庫名稱。如果 db 不是 NULL，則連線會將預設資料庫設定為此值。

  • 如果 port 不為 0，則該值會用作 TCP/IP 連線的埠號。請注意，host 引數會決定連線的類型。

  • 如果 unix_socket 不是 NULL，則該字串會指定要使用的 Socket 或具名管道。請注意，host 引數會決定連線的類型。

  • client_flag 的值通常為 0，但可以設定為下列旗標的組合，以啟用特定功能

    • CAN_HANDLE_EXPIRED_PASSWORDS：用戶端可以處理過期的密碼。如需詳細資訊，請參閱伺服器處理過期密碼。

    • CLIENT_COMPRESS：在用戶端/伺服器通訊協定中使用壓縮。

    • CLIENT_FOUND_ROWS：傳回找到 (符合) 的列數，而不是變更的列數。

    • CLIENT_IGNORE_SIGPIPE：防止用戶端程式庫安裝 SIGPIPE 信號處理常式。這可用於避免與應用程式已安裝的處理常式發生衝突。

    • CLIENT_IGNORE_SPACE：允許在函數名稱後方加上空格。使所有函數名稱成為保留字。

    • CLIENT_INTERACTIVE：允許 interactive_timeout 秒的閒置時間（而不是 wait_timeout 秒），然後再關閉連線。用戶端的會話 wait_timeout 變數會設定為會話 interactive_timeout 變數的值。

    • CLIENT_LOCAL_FILES：啟用 LOAD DATA LOCAL 處理。

    • CLIENT_MULTI_RESULTS：告知伺服器用戶端可以處理來自多語句執行或預存程序的多次結果集。如果啟用 CLIENT_MULTI_STATEMENTS，則會自動啟用此旗標。請參閱此表格後面的附註，以取得有關此旗標的詳細資訊。

    • CLIENT_MULTI_STATEMENTS：告知伺服器，客戶端可能會在單一字串中傳送多個語句（以 ; 字元分隔）。如果未設定此旗標，則會停用多語句執行。有關此旗標的更多資訊，請參閱此表格後面的注意事項。

    • CLIENT_NO_SCHEMA：不允許使用 db_name.tbl_name.col_name 語法。這適用於 ODBC。如果您使用該語法，它會導致解析器產生錯誤，這對於捕獲某些 ODBC 程式中的錯誤非常有用。

      從 MySQL 8.0.32 開始，CLIENT_NO_SCHEMA 旗標已棄用。客戶端程式可以省略此旗標和 db 參數，以便連接將資料庫值設定為目前（或預設）資料庫。

    • CLIENT_ODBC：未使用。

    • CLIENT_OPTIONAL_RESULTSET_METADATA：此旗標使結果集元數據成為可選的。抑制元數據傳輸可以提高效能，特別是對於執行許多查詢且每個查詢僅返回少量資料列的會話。有關管理結果集元數據傳輸的詳細資訊，請參閱第 3.6.7 節，「可選結果集元數據」。

    • CLIENT_SSL：使用 SSL（加密協定）。請勿在應用程式中設定此選項；它會在客戶端程式庫內部設定。而是應在呼叫 mysql_real_connect() 之前，使用 mysql_options()。

    • CLIENT_REMEMBER_OPTIONS：記住呼叫 mysql_options() 所指定的選項。如果沒有此選項，若 mysql_real_connect() 失敗，您必須重複呼叫 mysql_options()，才能再次嘗試連線。使用此選項，則不必重複呼叫 mysql_options()。

如果您的程式使用 CALL 語句來執行預存程序，則必須啟用 CLIENT_MULTI_RESULTS 旗標。這是因為除了程序內執行的語句可能傳回的任何結果集之外，每個 CALL 都會傳回一個結果來指示呼叫狀態。由於 CALL 可以傳回多個結果，請使用迴圈呼叫 mysql_next_result() 來處理它們，以確定是否有更多結果。

當您呼叫 mysql_real_connect() 時，可以啟用 CLIENT_MULTI_RESULTS，方法是明確傳遞 CLIENT_MULTI_RESULTS 旗標本身，或隱含地傳遞 CLIENT_MULTI_STATEMENTS（也會啟用 CLIENT_MULTI_RESULTS）。預設會啟用 CLIENT_MULTI_RESULTS。

如果您啟用 CLIENT_MULTI_STATEMENTS 或 CLIENT_MULTI_RESULTS，請使用呼叫 mysql_next_result() 的迴圈，處理每次呼叫 mysql_real_query() 或 mysql_query() 的結果，以確定是否有更多結果。如需範例，請參閱第 3.6.3 節，「多語句執行支援」。

對於某些參數，可以從選項檔取得值，而不是從 mysql_real_connect() 呼叫中的明確值取得。若要執行此操作，請在呼叫 mysql_real_connect() 之前，使用 MYSQL_READ_DEFAULT_FILE 或 MYSQL_READ_DEFAULT_GROUP 選項呼叫 mysql_options()。然後，在 mysql_real_connect() 呼叫中，為每個要從選項檔讀取的參數指定 「無值」值。

  • 對於 host，請指定值 NULL 或空字串 ("")。

  • 對於 user，請指定值 NULL 或空字串。

  • 對於 passwd，請指定值 NULL。（對於密碼，無法在選項檔中覆寫 mysql_real_connect() 呼叫中的空字串值，因為空字串明確表示 MySQL 帳戶必須具有空密碼。）

  • 對於 db，請指定值 NULL 或空字串。

  • 對於 port，請指定值 0。

  • 對於 unix_socket，請指定值 NULL。

如果選項檔中找不到參數的值，則會使用本節稍早說明中指示的預設值。

傳回值

如果連線成功，則為 MYSQL* 連線處理常式；如果連線不成功，則為 NULL。對於成功的連線，傳回值與第一個參數的值相同。

錯誤

範例

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}

透過使用 mysql_options()，MySQL 客戶端程式庫會讀取 my.cnf 檔案中的 [client] 和 [your_prog_name] 區段。這使您能夠將選項新增到 [your_prog_name] 區段，以確保您的程式可以運作，即使有人以非標準方式設定了 MySQL。


上一個   首頁   上一層   下一個
下載本手冊
PDF (美式信紙) - 1.4Mb
PDF (A4) - 1.4Mb