Biblioteca Internet

Biblioteca que contém funções relacionadas à internet/intranet, como: downloads, requisições HTTP, etc..

Todas as funções estão contidas na unidade "internet.lua".

Exemplo de uso:

-- Primeiro, é necessário usar a unidade "internet.lua"
require("internet.lua");

-- Agora é possível acessar as funções da biblioteca
Internet.FUNCAO_DA_BIBLIOTECA(Parametro1, Parametro2, ...);

Funções da biblioteca Internet

function Internet.asyncDownload(url[, cacheMode[, progressCallback]])

Asynchronously downloads a file from the internet.

Arguments:

url - String containing the URL address of the file, like "http://www.website.com/directory/file.png".
(Optional) cacheMode - One of the following strings:

"alwaysUseCache" - If the file already exists in the cache, Firecast will return the content without even communicating with the internet. This is the default mode.
"checkForModification" - If the file already exists in the cache, Firecast will check the remote server for changes to the content before deciding to use the local cache or download the content.
"alwaysDownload" - Firecast will not use the local cache and will always download content from the remote server.

(Optional) progressCallback - A function that will be called multiple times to report the download progress. This function takes 2 parameters:

downloadedBytes - How many bytes have already been downloaded.
totalBytes - How many bytes the file has in total.

Return:

A Promise for two pieces of information in the following order:

A Stream object with the downloaded file content.
A String containing the content type / mime type of the downloaded file, like 'image/png', 'text/html', and so on

Remarks:

Internet URL addresses must start with "http://" or "https://".
File addresses that are located inside the VHD (plugin's virtual HD) are also accepted.
If you explicitly return false in a progressCallback call, the download will be aborted.
The download process is queued in the Firecast download manager and therefore the download may experience a wait before actually starting.

Example:

local promise = Internet.asyncDownload("https://www.address.com/file.txt");

local stream, contentType = await(promise);

showMessage(contentType .. ": " .. tostring(stream.size));

function Internet.download(url [, finishCallback [, errorCallback [, progressCallback [, cacheMode]]]])

Realiza o download de um arquivo da internet.

Parâmetros:

url - Cadeia de caracteres contendo a URL do arquivo (Exemplo: http://www.site.com.br/pasta/arquivo.png).

URL de arquivos que estão na internet devem começar com "http://" ou "https://"
Endereços de arquivos que estão localizados no HD virtual do plug-in também são aceitos.

(OPCIONAL) finishCallback - Uma função que será invocada quando o download estiver terminado. Esta função recebe os seguintes 2 parâmetros:

stream - Um objeto Stream possuindo o conteúdo do arquivo baixado.
contentType - Uma cadeia de caracteres identificando o MimeType/tipo do conteúdo.. Exemplos: "application/octet-stream", "image/png", "text/html", etc..

(OPCIONAL) errorCallback - Uma função que será invocada se ocorrer algum erro no download. A Mensagem de erro é passada no primeiro parâmetro desta função.
(OPCIONAL) progressCallback - Uma função que será invocada várias vezes para informar o progresso do download. Esta função recebe 2 parâmetros:

downloadedBytes - Quantos bytes já foram baixados.
totalBytes - Quantos bytes o arquivo possui no total.

(OPCIONAL) cacheMode - Pode ser passado um dos seguintes valores e significados:

"alwaysUseCache" - Se o arquivo já existir no cache, o Firecast irá retornar o conteúdo sem mesmo se comunicar com a internet. Este é o modo padrão.
"checkForModification" - Se o arquivo já existir no cache, o Firecast irá verificar no servidor remoto se houve alterações no conteúdo antes de decidir usar o cache local ou baixar o conteúdo.
"alwaysDownload" - O Firecast não usará o cache local e sempre baixará o conteúdo do servidor remoto.

Retorno:

A função retorna um identificador de download. Este valor pode ser utilizado para invocar o método Internet.stopDownload caso queira abortar o download.

Observações:

A função não espera o download terminar e continua a execução do código enquanto o download é feito em paralelo.
Para ter acesso ao conteúdo baixado, utilize o parâmetro finishCallback.
Invocar esta função faz com que a URL seja enfileirada no gerenciador de downloads do Firecast, e, portanto, o download pode passar por uma espera antes de realmente começar.
Retornar explicitamente "false" na função progressCallback faz com que o download seja abortado.
Este método utiliza um sistema de cache de arquivos para evitar usar a internet com arquivos que já foram recentemente baixados.
Se o arquivo estiver pronto no sistema de cache de arquivos, a função "finishCallback" poderá ser invocada imediatamente, antes mesmo da função "Internet.download" retornar.
Este método, quando possível, faz "resume", isto é, ele consegue fazer download à partir de um ponto que havia parado recentemente.

Exemplo 1:

Internet.download("http://www.rrpg.com.br/arquivo.png",
  function(stream, contentType)
  -- esta função será chamada quando o download terminar
  -- o conteúdo do arquivo baixado está em stream.
  end,

  function (errorMsg)
  -- esta função será chamada quando ocorrer algum erro no download.
  -- errorMsg possui a msg de erro
  end,

  function (downloaded, total)
  -- esta função será chamada constantemente.
  -- dividir "downloaded" por "total" lhe dará uma porcentagem do download.
  end);

Exemplo 2 - checkForModification

  function (errorMsg)
  -- esta função será chamada quando ocorrer algum erro no download.
  -- errorMsg possui a msg de erro
  end,

  function (downloaded, total)
  -- esta função será chamada constantemente.
  -- dividir "downloaded" por "total" lhe dará uma porcentagem do download.
  end, "checkForModification");

function Internet.stopDownload(downloadId)

Aborta um download que foi iniciado pela função Internet.download

Parâmetros:

downloadId - a identificação do download a ser abortado. Este valor é retornado pela função Internet.download

function Internet.newHTTPRequest([method [, url]])

Cria e retorna um objeto HTTPRequest, usado para troca de dados com um servidor através de protocolo HTTP ou HTTPS.

Parâmetros:

(OPCIONAL) method - Uma cadeia de caracteres identificando o método/verbo HTTP utilizado nesta requisição. Os valores aceitos são:

"GET" (valor padrão, se o parâmetro for omitido)
"POST"
"PUT"
"PATCH"
"TRACE"
"HEAD"
"OPTIONS"
"DELETE"

(OPCIONAL) url - A URL da requisição HTTP. Este valor pode ser alterado posteriormente no objeto HTTPRequest.

Retorno:

Um objeto HTTPRequest representando a requisição.

Observações:

As requisições HTTP são permitidas se ao menos uma das seguintes afirmativas for verdadeira:

O usuário atual é assinante Gold/Platinum/Ruby; ou
O usuário atual está em uma mesa cujo criador é assinante Platinum.

Esta função apenas cria o objeto HTTPRequest e não a envia. Você deve utilizar o método "send" do objeto para, de fato, enviar a requisição.

function Internet.httpEncode(str)

Codifica um texto para que possa ser usado como URL em requisições HTTP.

Parâmetros:

str - A cadeia de caracteres que deseja codificar.

Retorno:

Uma cadeia de caracteres contendo o texto codificado.

function Internet.httpDecode(str)

Decodifica os caracteres/códigos de URL contidas no texto passado.

Parâmetros:

str - A cadeia de caracteres que deseja decodificar.

Retorno:

Uma cadeia de caracteres contendo o texto decodificado.

Created with the Personal Edition of HelpNDoc: Effortlessly Convert Your Word Doc to an eBook: A Step-by-Step Guide