Componente INETCom

Versão 29/08/2002a

Introdução

O INETCom é uma DLL para o ambiente Windows que implementa automation server (componente COM) para permitir a comunicação TCP/IP. Pode ser utilizada por aplicações compiladas desenvolvidas em C++, Delphi, Visual Basic ou por linguagens script como VBScript, Javascript, Perl, Python, Ruby e outras. A seguir estão listados os componentes contidos na bilblioteca e para cada um são apresentadas suas funções.

Componente Client - Permite comunicação com servidor TCP/IP

Ativação - Cria instância do objeto
Funções disponíveis

SetBlocking - Estabelece modo de operação
SetTimeout - Estabelece timeout
GetHostAddress - Obtem endereços IP associados a nome de servidor.
Open - Abre conexão com servidor
Close - Fecha conexão com servidor
GetLocalIP - Obtém número IP local
GetLocalPort - Obtém número da Porta TCP/IP local
GetConnected - Verifica se conexão foi efetuada
GetError - Obtém último erro retornado pelo sistema operacional
Write - Insere dados no buffer de transmissão para servidor
Read - Retira dados do buffer de transmissão para servidor
Peek - Obtém dados do buffer de recepção do servidor sem retirá-los
TxCount - Retorna número de bytes no buffer de transmissão
TxFlush - Limpa buffer de transmissão
RxCount - Retorna número de bytes no buffer de recepção
RxFlush - Limpa buffer de recepção
Process - Processa comunicação

Tabela de códigos de erro retornado pelas funções

Componente Client

Este componente permite comunicação com um servidor TCP/IP. Estão descritas a seguir todas a funções contida, sendo que para cada uma delas é exibido um exemplo nas linguagens Javascript e Perl.

Client / Ativação

Para o componente poder ser utilizado é necessário criar uma instância do mesmo. Este processo vária para cada linguagem utilizada mas consiste basicamente em passar o nome 'INETCom.Client" para uma função que irá retornar uma referência para o objeto. Caso ocorra erro normalmente é retornada uma referência nula ou indefinida:

Javascript:

Net = WScript.CreateObject("INETCom.Client");

             if (Net == undefined)

                WScript.Echo("Erro na ativacao do componente");

Perl:

$Net = Win32::OLE->new('INETCom.Client');

                                               if (!defined($Com)) {

                                                   printf("Erro
   na  ativacao     do  componente\n");

                                               }

Client / SetBlocking - Estabelece modo de operação

Entradas	Tipo	Descrição
Blocking	Inteiro	Modo de operação: 0 (falso) -não bloqueia, 1 (verdadeiro) -bloqueia
Saída	Tipo	Descrição

Descrição

Esta função deve ser chamada antes de iniciar a conexão e estabelece o modo de operação das funções. No modo 0 (não bloqueia) as funções Open() , Write() e Read() retornam imediatamente. No modo 1 (bloqueia) estas funções só retornam após sua execução completa, ocorrência de erro ou expiração do timeout estabelecido por SetTimeout() . O valor padrão deste parâmetro é 0 (não bloqueia).

Exemplos:

Javascript:
Net.SetBlocking(1);

Perl:
$Net->SetBlocking(0);

Client / SetTimeout - Estabelece timeout

Entrada	Tipo	Descrição
Timeout	Inteiro	Timeout em milisegundos
Saída	Tipo	Descrição
nResul

Descrição

Esta função permite estabelecer o timeout de espera das função Open() , Write() e Read() no modo com bloqueio. O valor padrão deste parâmetro é 30000 (30s). No modo sem bloqueamento, este timeout é ignorado.

Exemplo:

Javascript:

Net.SetTimeout(10000);    // 10s de timeout

Perl:
$Net->SetTimeout(5000); # 5s de timeout

Client / GetHostAddress - Obtém endereços IP associados a nome de servidor

Entradas	Tipo	Descrição
Host	String	String com nome do servidor cujos endereços IP serão resolvidos e retornados
Saída	Tipo	Descrição
Address	String	Resultado da função: String com número IPs ou string vazio caso tenha ocorrido problema.

Descrição

Esta função permite obter os endereços IPs de um servidor para posterior conexão com o mesmo. Deve ser fornecido o nome completo do servidor (nome do host seguido de seu nome de domínio) e a função tentará resolver este nome e obter endereços IP associados. Este processo pode demorar alguns segundos. O valor retornado é um string vazio caso tenha ocorrido algum problema ou uma lista com um ou mais endereços IP associados. Os números IP são retornados no formato XXX.XXX.XXX.XXX. Caso haja mais de um IP, os mesmos serão separados por vírgulas.

Exemplo:

Javascript:

var Res = Net.GetHostAddress("www.cnn.com");

if (Res.length = 0) {

                WScript.Echo("Erro na obtenção de 
endereços IP");

 }

 var IPs = Res.split(",");

 var IP = IPs[0];

Perl:

my $Res = $Net->GetHostAddress("www.trixtec.com.br");

                                                if (length($Res) == 0) {

                                                    printf("Erro 
na obtenção de endereços IP");

                                                }

 my @IPs = split(/,/, $Res);

 my $IP = $IPs[0];

Client / Open - Abre conexão com servidor

Entradas	Tipo	Descrição
IP	String	String com número IP do servidor no formato XXX.XXX.XXX.XXX
Port	Inteiro	Número da porta do TCP/IP associada ao servidor
Saída	Tipo	Descrição
Result	Inteiro	Resultado da função: 0 - se OK, -1 - se ocorreu erro do sistema operacional, -2 - se endereço IP fornecido for inválido -4 - se conexão está em processo (modo sem bloqueio apenas)

Descrição

Esta função permite abrir conexão com servidor. Devem ser fornecidos o número IP do servidor, que pode ser obtido através da função GetHostAddress() e o número da porta TCP/IP associada ao servidor. Se tiver sido estabelecido modo de bloqueio através de SetBlocking() a função só retorna após a conexão ter sido efetuada com sucesso, ter ocorrido um erro ou expirado timeout. Este processo, dependendo o servidor, poderá demorar alguns segundos. Se tiver sido estabelecido o modo sem bloqueio, a função retorna imediatamente, e neste caso é possível que a conexão ainda não tenha sido efetuada e a função retorna valor -4.

Exemplo:

Javascript:

var Res = Net.Open("192.168.1.254",
80);

Perl:

my $Res = $Net->Open("192.168.1.254", 
80);

Client / Close - Fecha conexão com servidor

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
nResult	Inteiro	Resultado da função: 0 - se OK ou código de erro caso contrário

Descrição

Esta função permite fechar conexão previamente aberta com servidor. Retorna resultado indicando se a conexão foi fechado com sucesso ou ocorreu erro.

Exemplo:

Javascript:

var Res = Net.Close();

                                   if (Res) {

                WScript.Echo("Erro ao fechar conexao");

Perl:

my $Res  = $Net->Close();

                                                if ($Res) {

                                                    printf("Erro 
ao fechar conexao");

                                                }

Client / GetLocalIP - Obtém número IP local

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
IP	String	Resultado da função: String com número IP local ou string vazio caso tenha ocorrido erro.

Descrição

Esta função só deve ser chamada após a conexão com servidor ter sido aberta e permite obter o número IP local sendo utiizado. O número IP é retornado em um string no formato: XXX.XXX.XXX.XXX. Caso tenha ocorrido erro é retornado string vazio.

Exemplo:

Javascript:

var Res = Net.GetLocalIP();

 if (Res.length) {

                                                   WScript.Echo("Numero 
IP local:" + Res);

                               }

Perl:
my $Res = $Net->GetLocalIP()



 if (length($Res)) {

                                                   printf("Numero 
IP local: $Res");

                                                }

Client / GetLocalPort - Obtém número da Porta TCP/IP local

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Port	Inteiro	Resultado da função: Valor positivo com número da porta TCP/IP local ou valor negativo caso tenha ocorrido erro.

Descrição

Esta função só deve ser chamada após a conexão com servidor ter sido aberta e permite obter o número da porta TCP/IP local sendo utilizada.

Exemplos:

Javascript:

var Res = Net.GetLocalPort();

  if (Res > 0) {

                                                   WScript.Echo("Numero 
da Porta local:" + Res);

                               }

Perl:
my $Res = $Net->GetLocalIP()



  if ($Res > 0) {

                                                   printf("Numero 
da Porta local: $Res");

                                                }

Client / GetConnected - Verifica se conexão foi efetuada

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Status	Inteiro	Resultado da função: 1 (verdadeiro) - se conexão efetuada ou 0 (falso) se conexão ainda não foi efetuada.

Descrição

Esta função permite verificar se a conexão foi efetuada, após a chamada da função Open() no modo sem bloqueio. Neste modo a função Open() retorna imediatamente e a conexão pode ainda não ter sido efetuada. Neste caso a função Open() retorna -4 e deverá então ser chamada a função GetConnected() periodicamente para verificar se a conexão foi estabelecida ou ocorreu erro.

Exemplos:

Javascript:

var Res = Net.Open("192.168.1.254",
80);

 if (Res == -4) {

     while (true) {

         if (Net.GetConnected())

             break;

     }

 }

Perl:

my $Res = $Net->Open("192.168.1.254", 
80);

if ($Res == -4) {

     while (true) {

         if ($Net->GetConnected())

             last;

     }    

 }

Client / GetError - Obtém último erro retornado pelo sistema operacional

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Error	Inteiro	Código do último erro retornado pelo sistema operacional

Descrição

Quando uma função retornar erro -1 indica que houve erro em chamada de função do sistema operacional. Neste caso pode ser utilizada a função GetError() para obter o código de erro retornado pelo sistema operacional.

Exemplos:

Javascript:

var Res = Net.Open("192.168.1.254", 80);

  if (Res == -1)

     var Error = Net.GetError();

     WScript.Echo("Ocorreu erro: " + Error);

 }

Perl:

my $Res = $Net->Open("192.168.1.254", 80);

if ($Res == -1) {

     my $Error = $Net->GetError();

     printf("Ocorreu erro: $Error");

 }

Client / Write - Insere dados no buffer de transmissão para servidor

Entrada	Tipo	Descrição
Data	String	String com dados a serem enviados para servidor
Saída	Tipo	Descrição
Result	Inteiro	Resultado da função: 0- se OK ou código de erro caso contrário

Descrição

Esta função deve ser chamada apenas após a conexão com servidor tiver sido estabelecida e permite enviar dados para o mesmo. No modo com bloqueio a função só retorna quando os dados forem transferidos para o sistema operacional para envio para o servidor, se ocorrer erro ou se expirar timeout estabelecido por SetTimeout() . No modo sem bloqueio a função insere os dados em buffer interno e retorna imediatamente.

Exemplos:

Javascript:

var Res = Net.Write("Mensagem para servidor");

                                                if (Res == 0) {

                                                    WScript.Echo("mensagem 
        enviada para servidor");

Perl:

my $Res = $Net->Write("Mensagem para 
servidor");

 if ($Res == 0) {

     printf("mensagem enviada para servidor");

 }

Client / Read - Retira dados do buffer de recepção do servidor

Entrada	Tipo	Descrição
Bytes	Inteiro	Número de bytes a serem retirados do buffer
Saída	Tipo	Descrição
Data	String	String com bytes retirados do servidor

Descrição

Esta função deve ser chamada apenas após a conexão com servidor tiver sido estabelecida e permite obter dados recebidos do servidor. No modo com bloqueio a função só retorna quando pelo menos o número de bytes especificado for recebido, se ocorrer erro ou se expirar timeout estabelecido por SetTimeout() . No modo sem bloqueio a função retorna imediatamente com os bytes retirados do buffer de recepção interno. Se o buffer estiver vazio a função retorna string vazio.

Exemplos:

Javascript:

var Res = Net.Read(50);

 if (Res.length)

                                                    WScript.Echo("Recebidos 
dados: " + Res);

Perl:
my $Res = $Net->Read(50);



                                                if (length($Res)) {

                                                   printf("Recebidos 
dados: $Res");

                                                }

Client / Peek - Obtém dados do buffer de recepção do servidor sem retirá-los

Entrada	Tipo	Descrição
Bytes	Inteiro	Número de bytes a serem lidos do buffer
Saída	Tipo	Descrição
Data	String	String com dados lidos do buffer de recepção do servidor

Descrição

Esta função deve ser chamada apenas no modo sem bloqueamento e permite obter os bytes no buffer de recepção do servidor sem retirá-los. No modo com bloqueio a função sempre retorna um string vazio.

Exemplos:

Javascript:

var Res = Net.Peek(9);

 if (Res == "Resposta:")

     WScript.Echo("Iniciando recepcao de resposta");

Perl:
my $Res = $Net->Peek(9);



                                                if (!Res eq  "Responsta:") 
{

                                                   printf("Iniciando 
recepcao de resposta");

                                                }

Client / TxCount - Retorna número de bytes no buffer de transmissão

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Result	Inteiro	Número de bytes no buffer de transmissão para servidor

Descrição

Esta função deve ser chamada apenas no modo sem bloqueamento e permite obter o número de bytes no buffer de transmissão que ainda não foram transferidos. No modo com bloqueamento a função retorna sempre o valor 0.

Exemplos:

Javascript:

var Res = Net.TxCount();

 if (Res) {

                                                    WScript.Echo("Faltam 
transmitir: " + Res + " bytes");

Perl:
my $Res = $Net->TxCount();



 if ($Res) {

                                                   printf("Faltam 
transmitir: $Res bytes");

                                                }

Client / TxFlush - Limpa buffer de transmissão

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Nenhuma

Descrição

Esta função deve ser chamada apenas no modo sem bloqueamento e permite limpar o buffer de transmissão interno. No modo com bloqueamento a função não faz nada.

Exemplos:

Javascript:
Net.TxFlush();

Perl:

$Net->TxFlush();

Client / RxCount - Retorna número de bytes no buffer de recepção

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Result	Inteiro	Número de bytes no buffer de recepção

Descrição

Esta função deve ser chamada apenas no modo sem bloqueamento e permite obter o número de bytes no buffer de recepção interno. No modo com bloqueamento a função retorna sempre o valor 0.

Exemplos:

Javascript:

var Res = Net.RxCount();

 if (Res) {

     var Data = Net.Read(Res);

Perl:
my $Res = $Net->RxCount();



  if ($Res) {

                                                   my $Data 
= $Net->Read($Res);

                                                }

Client / RxFlush - Limpa buffer de recepção

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Nenhuma

Descrição

Esta função deve ser chamada apenas no modo sem bloqueamento e permite limpar o buffer de recepção interno. No modo com bloqueamento a função não faz nada.

Exemplos:

Javascript:
Net.RxFlush();

Perl:
$Net->RxFlush();

Client / Process - Processa comunicação

Entrada	Tipo	Descrição
Nenhuma
Saída	Tipo	Descrição
Result	Inteiro	Resultado da função: 0 - se OK, código de erro caso contrário

Descrição

Esta função deve ser utilizada apenas no modo sem bloqueamento e neste caso precisa ser chamada periodicamente para processar a comunicação com servidor.

Exemplos:

Javascript:

var Res;

 var Bytes;

while (true) {

     Res = Net.Process();

     if (Res)

         break;

     Bytes = Net.RxCount();

     if (Bytes)

         WScript.Echo("Recebidos dados");    
        

 }

Perl:

my $Res;

 my $Bytes;

 while (1) {

     $Res = $Net->Process();

     if ($Res)

         last;

     $Bytes = $Net->RxCount();

     if ($Bytes) {

         printf("Recebidos dados");

     }

 }

Client / Códigos de erros retornados

Os códigos de erro retornados por este componente estão na faixa de -1 a -99:

Código do erro	Descrição
-1	Erro em chamada do sistema operacional
-2	Número IP inválido em Open()
-3	Conexão foi fechada pelo servidor
-4	Timeout em Open() , Write() ou Read() no modo com bloqueamento