HTTPSQuote

Permite emular um Client HTTP (Hypertext Transfer Protocol) através de uma função AdvPL, utilizando protocolo HTTPS, no qual o método HTTP é informado para a função, postando um bloco de informações para um determinado documento publicado em um servidor Web, permitindo a passagem de parâmetros adicionais via URL e aguardando por um tempo determinado (time-out) pela resposta do servidor solicitado.

Sintaxe

HTTPSQuote( < cURL >, < cCertificate >, < cPrivKey >, < cPassword >, < cMethod >, [ cGETParms ], [ cPOSTParms ], [ nTimeOut ], [ aHeadStr ], [ @cHeaderRet ], [ lClient ] )

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Referência
cURL	caractere	Indica o endereço HTTP com a pasta e o documento solicitado.	X
cCertificate	caractere	Indica o path do arquivo, em formato PEM (modelo Apache), do arquivo que contém o certificado digital.	X
cPrivKey	caractere	Indica o path da chave privada, em formato PEM (modelo Apache), do arquivo que contém a chave privada, referente ao certificado digital.	X
cPassword	caractere	Indica a senha que será utilizada para a abertura da chave privada. Para uma chave privada que não possua senha deve ser informada uma string vazia.	X
cMethod	caractere	Define o HTTP Method que será utilizado, permitindo outros além de POST/GET.	X
cGETParms	caractere	Indica uma string de parâmetros, do tipo GET, que serão enviados ao servidor HTTP através da URI. Caso não seja especificado, este parâmetro é considerado vazio ("").
cPOSTParms	caractere	Indica uma string de parâmetros, do tipo POST, que serão enviados ao servidor HTTP através do pacote HTTP. Caso não seja especificado, este parâmetro é considerado vazio ("").
nTimeOut	numérico	Indica o tempo, em segundos, máximo de inatividade permitido durante a recepção do documento. Caso não seja especificado, o valor assumido será de 120 segundos.
aHeadStr	vetor	Indica o array que contêm as strings que serão acrescentadas no header da requisição HTTP que será realizada.
cHeaderRet	caractere	Indica a string que conterá o header de resposta HTTP enviado pelo servidor requisitado. Observação: A variável deve ser declarada antes da chamada da função.		X
lClient	lógico	Indica se a operação será feita pelo SmartClient (.T.) ou pelo AppServer (.F.). Valor padrão: .F..

Retorno

Nome	Tipo	Descrição
cRet	caractere	Retorna a string que corresponde à requisição solicitada.

Observações

O parâmetro <cGetParms> representa uma lista de itens, separados por '&'. Pois, a mesma segue o formato URI - Uniform Resource Identiers: Query Component.

Exemplo: "param1=value1&m2=value2"

Neste caso, ao realizar o POST para o endereço, este seria completado com os parâmetros Get.

Exemplo: http://www.totvs.com?param1=value1&m2=value2

Atenção

Para fazer a passagem de valores dos parâmetros de GET, utilize no valor do parâmetro a função Escape.

Caso não seja retornado o documento antes do término do time-out especificado na chamada da função ou caso não seja possível localizar o servidor, seja por falha de resolução de DNS ou por erro de sintaxe ao especificar a URL, a função retornará nulo (Nil).

Caso não seja possível acessar o documento como, por exemplo, o documento não existe, o retorno será uma string HTML com a mensagem de erro HTML enviada pelo servidor correspondente.

Ao utilizar a função HTTPSQuote pode-se especificar um Content-Type diferenciado para o conteúdo postado. Caso não seja especificado um Content-Type, alguns servidores tratam a informação postada como sendo um dado do tipo 'application/x-www-form-url', seria o equivalente a um formulário HTML postado via Browser. Desta forma, outros servidores poderão não reconhecer tal informação postada dessa forma.

Para especificar que o conteúdo postado deve ser tratado como um POST de formulário HTTP, deve-se passar no parâmetro aHeadStr um elemento 'Content-Type: application/x-www-form-url'.

Caso a operação seja feita no AppServer e não for passado um caminho no environment para o parâmetro cCertificate, a aplicação será encerrada com uma exceção cuja mensagem será: "Only server path are allowed to Certificate on HTTPSQuote".
Caso a operação seja feita no AppServer e não for passado um caminho no environment para o parâmetro cPrivKey, a aplicação será encerrada com uma exceção cuja mensagem será: "Only server path are allowed to PrivKey on HTTPSQuote".
Campos 'Content-Length' não deverão ser acrescentados manualmente no cabeçalho HTTP via parâmetro <aHeadStr>; caso sejam acrescentados e indiquem tamanho do corpo da mensagem igual ao esperado, serão descartados silenciosamente; caso sejam acrescentados e indiquem tamanho do corpo da mensagem diferente do esperado, serão descartados e um aviso será gerado no log da aplicação.
Caso seja passado o parâmetro lClient com valor .T. e a função for chamada via Job, a aplicação será encerrada com uma exceção cuja mensagem será: "Function HTTPSQuote with Client parameter isn't available in JOB.".
Caso seja passado o parâmetro lClient com valor .T. e a versão do SmartClient utilizado seja inferior a 20.3.1.3, a aplicação será encerrada com uma exceção cuja mensagem será: "Function HTTPSQuote isn't available in this version of SmartClient.".
Para saber quais são os métodos possíveis de serem utilizados, verifique a RFC 9110. É preciso certificar-se de que o servidor que vai receber a requisição tem suporte ao método especificado em cMethod.

Exemplos

#include "totvs.ch"
#include "xmlcsvcs.ch"

user function tstquop()
  Local cURL := "https://homologacao.nfe.fazenda.sp.gov.br:443/nfeWEB/services/NfeStatusServico.asmx"
  Local nTimeOut := 120
  Local aHeadOut := {}
  Local cHeadRet := ""
  Local cPostRet := ""
  
  // Acrescenta o UserAgent na requisição ...
  // http://tools.ietf.org/html/rfc3261#page-179
  
  AAdd( aHeadOut, 'User-Agent: Mozilla/4.0 (compatible; Protheus ' + GetBuild() + ')' )
  cPostRet := HTTPSQuote( cURL, "\certs\cert.pem", "\certs\privkey.pem", "pwdprivkey", "POST", "", "", nTimeOut, aHeadOut, @cHeadRet )
  
  if Empty( cPostRet )
    conout( "Fail HTTPSQuote" )
  else
    conout( "OK HTTPSQuote" )
    varinfo( "WebPage", cPostRet )
  endif
  
  varinfo( "Header", cHeadRet )
return

Abrangência

AppServer versão 20.3.1.3 e SmartClient versão 20.3.1.3.

Árvore de páginas