Executar um comando FTP (ftp.cmd)

Declaração

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

Parâmetros

• URL
  Texto. URL FTP remota que inclui a conta e a senha. Para operações com diretórios, use uma URL de diretório que termine em /.
• cmd
  Texto. Um único comando do protocolo FTP, como MKD test. Não é possível passar uma tabela de comandos.
• connectTimeoutSec
  Número real, opcional. Tempo limite de conexão em segundos; o padrão é 10. Não limita a duração total da solicitação.

Valores de retorno

• result
  Texto ou nil. Se a solicitação for bem-sucedida, retorna os dados recebidos, que podem ser uma string vazia. Com uma URL de diretório, geralmente é uma listagem do diretório, não o código de status do comando FTP nem a resposta da conexão de controle. Retorna nil em caso de falha.
• err
  Texto ou nil. Em caso de falha, retorna uma descrição textual da causa do erro. Em caso de sucesso, não retorna um segundo valor, portanto a variável que o recebe é nil.

Descrição

Envia um comando ao servidor FTP para realizar operações como criar diretórios. As operações atuam sobre arquivos ou diretórios do servidor.

O comando é executado antes de mudar para o diretório especificado na URL. Caminhos relativos têm como base o diretório padrão após o login; por exemplo, MKD uploads/test cria test dentro de uploads sob esse diretório. Não dependa do caminho da URL para mudar o diretório de trabalho do comando. Os caminhos no comando são enviados diretamente, sem decodificação percentual de URL.

MKD normalmente cria apenas um nível de diretório, portanto o diretório pai já deve existir. A operação pode falhar se o diretório já existir, a conta não tiver permissão ou o servidor não oferecer suporte ao comando. Para criar vários níveis, chame a função separadamente para cada diretório, do pai para o filho.

Na implementação atual, se o texto do comando contiver LIST ou NLST em maiúsculas, o comando não será enviado; somente a solicitação padrão da URL será realizada. Isso também se aplica quando essas sequências aparecem no nome de um diretório. Portanto, NLST não muda para uma listagem apenas de nomes de arquivos, e os argumentos de LIST -a não têm efeito.

Após executar o comando, a função ainda solicita os dados da URL; com uma URL de diretório, também obtém a listagem do diretório. Se a listagem ou a conexão de dados falhar em seguida, o diretório pode já ter sido criado, mas a função ainda retornará nil e uma mensagem de erro.
Esta função pode ceder a execução; outras threads podem executar antes que ela retorne.

Exemplo simples

Coloque a conta e a senha na URL. O formato é o seguinte (os colchetes indicam partes opcionais):

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

Se a conta ou a senha contiver @, : ou /, use %40, %3A ou %2F, respectivamente, para escapá-los. Outros caracteres inválidos em uma URL podem usar codificação percentual. Por exemplo, com a conta havonz e a senha 11@@22, crie test no diretório padrão após o login:

local result, err = ftp.cmd("ftp://havonz:11%40%[email protected]/", "MKD test", 10)
if result == nil then
    sys.alert("Falha ao criar: " .. tostring(err))
else
    sys.alert("Criado com sucesso")
end

Exemplo complexo

Crie demo e depois demo/logs; nenhum dos dois deve existir ainda. Pare se alguma etapa falhar. Os diretórios criados anteriormente não são excluídos automaticamente.

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("Falha ao criar " .. path .. ": " .. tostring(err))
        return
    end
end

sys.alert("Diretórios criados")

Nota: O código acima usa sys.alert, uma função de outro capítulo.