FTP 執行命令 (ftp.cmd)

聲明

result, err = ftp.cmd(URL, cmd [, connectTimeoutSec ])

參數

• URL
  文字型，FTP 遠端地址，帳號及密碼包含在這一參數中；執行目錄操作時應使用以 / 結尾的目錄 URL
• cmd
  文字型，一條 FTP 協定命令，例如 MKD test，不支援傳入命令表
• connectTimeoutSec
  實數型，可選參數，連接超時時間，單位秒，預設 10；不限制整個請求的總耗時

回傳值

• result
  文字型 或 nil，請求成功時回傳收到的資料，可能為空字串；使用目錄 URL 時通常為目錄列表，不是 FTP 命令的狀態碼或控制連線回覆；失敗時回傳 nil
• err
  文字型 或 nil，失敗時回傳錯誤原因文字描述；成功時不回傳第二個值，接收變數為 nil

說明

向 FTP 伺服器傳送命令，可用於建立目錄等操作，操作對象是伺服器上的檔案或目錄。

命令在切換到 URL 指定的目錄之前執行。相對路徑以登入後的預設目錄為基準；例如 MKD uploads/test 在該目錄下的 uploads 中建立 test。不要依靠 URL 中的路徑改變命令的執行目錄；命令中的路徑直接傳送，不進行 URL 百分號解碼。

MKD 通常只建立一級目錄，父目錄需要已經存在。目錄已存在、帳號沒有權限或伺服器不支援相應命令時，都可能失敗。建立多級目錄需要按父目錄到子目錄的順序分別呼叫。

目前實作只要命令文字包含大寫的 LIST 或 NLST，就會跳過傳送該命令，僅執行 URL 的預設請求；即使這些片段出現在目錄名稱中也一樣。因此 NLST 不會切換成僅檔案名稱列表，LIST -a 的參數也不會生效。

執行命令後仍會請求 URL 對應的資料，使用目錄 URL 時還會取得目錄列表。如果後續列目錄或資料連線失敗，目錄可能已經建立，但函式仍回傳 nil 和錯誤資訊。
該函式可能會讓出，在其回傳之前，其他 執行緒 可能會得到執行機會

簡單範例

帳號密碼寫在 URL 中，具體 URL 格式如下（中括號內是可選部分）：

ftp://[user:password@]host[:port]/path

帳號或密碼中包含 @、:、/ 這三個字元可分別用 %40、%3A、%2F 轉義（其他在 URL 中非法的字元可使用 URL 百分號編碼）。 例如帳號 havonz、密碼 11@@22，在登入後的預設目錄下建立 test：

local result, err = ftp.cmd("ftp://havonz:11%40%[email protected]/", "MKD test", 10)
if result == nil then
    sys.alert("建立失敗：" .. tostring(err))
else
    sys.alert("建立成功")
end

複雜範例

依次建立 demo 和 demo/logs，兩者均應尚不存在。某一步失敗就停止，不自動刪除此前已建立的目錄。

local url = "ftp://havonz:11%40%[email protected]/"

for _, path in ipairs({ "demo", "demo/logs" }) do
    local result, err = ftp.cmd(url, "MKD " .. path, 10)
    if result == nil then
        sys.alert("建立失敗 " .. path .. ": " .. tostring(err))
        return
    end
end

sys.alert("目錄建立完成")

註：上述程式碼中使用了非本章函式 sys.alert。