Objeto HTTPRequest¶

O Objeto HTTPRequest é utilizado para a troca de dados com um servidor usando protocolo HTTP ou HTTPS.

É excelente para integrar o plug-in com alguma api REST, baixar ou enviar informações para um servidor da World Wide Web.

Para instanciar um Objeto HTTPRequest, utilize a função internet.newHTTPRequest

Restrições:¶

As requisições HTTP são permitidas apenas se o usuário do rrpg for um membro GOLD.

Características¶

Propriedades e atributos¶

Propriedade	Tipo	Descrição
url	String	Define a URL para onde a requisição HTTP será direcionada. Exemplo: "http://www.google.com/xx/document.txt" "https://www.rrpg.com.br/apiexemplo" A URL deve iniciar com "http://" ou "https://"
method	String	Define o método/verbo HTTP que será utilizado na requisição. Os possíveis valores são: "GET" (padrão) "POST" "PUT" "PATCH" "TRACE" "HEAD" "OPTIONS" "DELETE"
status	Integer	Um número contendo o status da resposta http. (Exemplos: 200 para ok, 404 para não encontrado, etc..) Consulte http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html para saber quais são os possíveis status.
statusText	String	Uma cadeia de caracteres contendo o texto-status-resposta da requisição HTTP. Diferente da propriedade "status", este valor contém o texto completo da resposta (Exemplos: "200 OK", "404 NOT FOUND").
responseText	String	Contém o corpo da resposta interpretada como texto. O "charset" do cabeçalho de resposta "Content-Type" é levado em consideração antes de retornar o texto.
responseStream	Objeto Stream	Contém o corpo da resposta em um objeto stream. Muito útil quando a resposta dada pelo servidor for binária.

Métodos¶

Método	Descrição
request:send([content])	Inicia o envio da requisição HTTP. Antes de chamar esta função, a URL e todos os cabeçalhos devem ser informados pela função setRequestHeader. Parâmetros: (OPCIONAL) content - Uma cadeia de caracteres ou um objeto stream contendo os dados que serão enviado ao servidor. Se não informado, a requisição é feita com corpo vazio. Observações: A requisição é assíncrona. Isto é, a função send retorna imediatamente e o código LUA continua sua execução normal enquanto a comunicação com o servidor é feita em segundo plano. Para obter a resposta, manipule os eventos onResponse e onError antes de chamar este método. Se o parâmetro content for uma cadeia de caracteres, o "charset" do cabeçalho de requisição "Content-Type" é levado em consideração para a codificação do texto.
request:setRequestHeader(header, value)	Altera o valor de um cabeçalho de requisição HTTP. Você deve enviar setRequestHeader antes de invocar o método send. Parâmetros: header - Cadeia de caracteres representando o nome do cabeçalho. Exemplos: "Content-Type" , "Content-Encoding", etc.. value - Cadeia de caracteres com o valor que deve ser associado ao cabeçalho. Observações: Para saber mais sobre os cabeçalhos HTTP, veja http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html. Se este método for chamado várias vezes alterando o mesmo cabeçalho, o valor da última chamada prevalecerá.
request:getRequestHeader(header)	Obtém o valor de um cabeçalho de requisição HTTP. Parâmetros: header - cadeia de caracteres representando o nome do cabeçalho. Retorno: Uma cadeia de caracteres, contendo o valor do cabeçalho.
request:getResponseHeader(header)	Obtém o valor de um cabeçalho de resposta da requisição HTTP. Parâmetros: header - cadeia de caracteres representando o nome do cabeçalho de resposta. Retorno: Uma cadeia de caracteres, contendo o valor do cabeçalho, ou "" (cadeia de caracteres vazia) se o cabeçalho não existir na resposta. Para saber mais sobre os cabeçalhos HTTP, veja http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.
request:getAllResponseHeaders()	Retorna uma cadeia de caracteres contendo todos os cabeçalhos da resposta HTTP de uma só vez.
request:abort();	Aborta a requisição HTTP que está sendo feita.
request:open(method, url);	Inicializa a requisição HTTP Parâmetros: method - Uma cadeia de caracteres identificando o método/verbo HTTP utilizado nesta requisição. Os valores aceitos são: "GET" "POST" "PUT" "PATCH" "TRACE" "HEAD" "OPTIONS" "DELETE" url - A URL da requisição HTTP Observação: O uso deste método não é obrigatório. É apenas um "doce" para aqueles que estão acostumados com a requisição HTTP do JavaScript.

Eventos¶

Nome do evento	Descrição
onResponse	Este evento é invocado quando a requisição HTTP concluir sem erros. Após este evento, as propriedades de resposta estarão disponíveis no objeto (como, por exemplo, status, statusText, responseText, etc..). Observação: Se o servidor retornar status 4xx (algum erro de requisição) ou 5xx (algum erro do servidor), o evento "onError" será disparado ao invés de "onResponse"
onError	Este evento é disparado quando ocorrer um erro na requisição HTTP. Parâmetros: errorMsg - Uma cadeia de caracteres contendo informações sobre o erro. Observação: Se o servidor retornar status 4xx (algum erro de requisição) ou 5xx (algum erro do servidor), o evento "onError" será disparado ao invés de "onResponse"
onReceiveProgress	Evento que é disparado frequentemente a fim de informar o progresso de download da requisição HTTP. Parâmetros: currentBytes - Um número indicando quantos bytes já foram baixados maxBytes - Um número indicando quantos bytes serão baixados no final das contas.
onSendProgress	Evento que é disparado frequentemente a fim de informar o progresso de upload da requisição HTTP. Parâmetros: currentBytes - Um número indicando quantos bytes já foram enviados. maxBytes - Um número indicando quantos bytes serão enviados no final das contas.

Exemplos¶

Exemplo 1 - Baixar o "index.html" de um site.¶

require("internet.lua"); local requisicao = internet.newHTTPRequest("GET", "http://www.rrpg.com.br/"); requisicao.onResponse = function() showMessage("Conteúdo: " .. requisicao.responseText); end; requisicao.onError = function(errorMsg) showMessage("Ops! Ocorreu algum erro: " .. errorMsg); end; requisicao:send();

Exemplo 2 - Fazer um upload de um arquivo, receber outro arquivo, rastreando o progresso.¶

require("internet.lua"); require("vhd.lua"); local requisicao = internet.newHTTPRequest("POST", "http://www.rrpg.com.br/REST_API/URL"); requisicao.onResponse = function() local streamResposta = requisicao.responseStream; local tipoRetornado = requisicao:getResponseHeader("Content-Type"); local arquivoDestino; if tipoRetornado == "image/png" then arquivoDestino = vhd.openFile("/baixado.png", "w+"); else arquivoDestino = vhd.openFile("/baixado.outraExtensao", "w+"); end; arquivoDestino:copyFrom(streamResposta, streamResposta.size); arquivoDestino:close(); end; requisicao.onError = function(errorMsg) showMessage("Ops! Ocorreu algum erro: " .. errorMsg); end; requisicao.onSendProgress = function(currentBytes, maxBytes) local porcentagem; if maxBytes ~= 0 then porcentagem = (currentBytes / maxBytes) * 100; else porcentagem = 0; end; --- porcentagem contém quantos % do arquivo já foram enviados end; requisicao.onReceiveProgress = function(currentBytes, maxBytes) local porcentagem; if maxBytes ~= 0 then porcentagem = (currentBytes / maxBytes) * 100; else porcentagem = 0; end; --- porcentagem contém quantos % do arquivo já foi recebido. end; local arquivoAEnviar = vhd.openFile("/arquivoExistente.png", "r"); requisicao:setRequestHeader("Content-Type", "image/png"); requisicao:send(arquivoAEnviar);

Created with the Personal Edition of HelpNDoc: Revolutionize Your Documentation Output with HelpNDoc's Stunning User Interface