qSocket

Control de conexiones TCP/IP.

Hija de
No tiene clase padre.

Variables
socket Manejador del socket (solo lectura)
nPort Puerto utilizado (solo lectura)
date Fecha de conexión (solo lectura)
time Hora de conexión (solo lectura)
nUsers Número de conexiones activas en el objeto (solo lectura)
nTotUsrs Número total de usuarios que se han conectado al objeto, aunque la idea es llevar el conteo total o volver a iniciar en determinando momento, se permite modificar con cualquier cantidad a discreción del programador
nUsrCount Devuelve el total de usuarios conectados a todos los objetos qSocket activos en el programa
nTotalCount Número total de usuarios que se han conectado a todos los objetos qSocket del programa, aunque la idea es llevar el conteo total o volver a iniciar en determinando momento, se permite modificar con cualquier cantidad a discreción del programador

Métodos
init() Inicializa el uso de sockets, se debe de utilizar siempre antes de comenzar a utilizar la clase qSocket
cleanup() Apaga el uso de sockets
newServer() Crea un objeto qSocket para conexión como servidor
newClient() Crea un objeto qSocket cliente y lo conecta al servidor
address() Obtiene la IP remota
error() Devuelve el último codigo de error
errorDes() Devuelve la descripción del último error
port() Devuelve el puerto remoto
recvLine() Recibe una línea de datos indicada por un fin de línea (CRLF)
recv() Recibe una cantidad indicada de datos
recvAll() Recibe la información pendiente de recibir
recvBlock() Recibe una línea de datos indicada por una cadena de caracteres definida por el usuario
setTimeOut() Indica el tiempo de espera antes de cerrar el socket
getTimeOut() Devuelve el tiempo de espera definido para esperar antes de cerrar el socket
sendAll() Envía los datos indicados
sendLenAll() Envía el tamaño del paquete de datos seguido de los datos
sendLine() Envía los datos seguidos de un fin de línea (CRLF)
sendBlock() Envía los datos seguidos de la cadena caracteres definida por el usuario como fin de bloque
accept() Activa el socket de un objeto qSocket servidor para esperar conexiones
sendFile() Envía un archivo
close() Cierra y destruye el socket

Descripción
Clase para manejar las conexiones TCP/IP, es necesario habilitar el uso de internet llamando antes de cualquier uso de sockets el método init:

   qSocket():init()

con esto se habilita el uso de las funciones de TCP/IP.

Esta clase trabaja en multihebra (MT o multithread).

Métodos

init()
Inicializa el uso de sockets y control interno de la clase qSocket para poder trabajar. Este método debe ser llamado antes de comenzar a utilizar la clase qSocket directamente ( qSocket():init() ), ya que los métodos que construyen los objetos hacen llamados a las funciones de sockets y control interno de conexiones de la clase.
Devuelve: NIL.

cleanup( olMostrar )
Apaga el uso de sockets de (x)Harbour y variables de control interno de qSocket. Este método debe ser llamado cuando ya no se piensa utilizar la clase qSocket. Al igual que el método init() su uso es unico para todos los objetos, así que puede ser llamado desde cualquiero objeto o directamente desde la clase qSocket():cleanup()
Devuelve: NIL.

newServer( nPort )
Crea un objeto qSocket para conexión como servidor.
Devuelve: Una referencia al objeto qSocket.
nPort Puerto que se utilizará para la conexión

newClient( cAddress, nPort )
Crea un objeto qSocket cliente y lo conecta al servidor.
Devuelve: Una referencia al objeto qSocket.
nModulo Número del módulo que se quiere accesar
nPermiso Número del permiso que se pide para tener acceso

address()
Obtiene la dirección IP de la conexión remota.
Devuelve: Cadena de caracteres con la dirección IP remota.

error()
Devuelve el codigo de error de la última operación realizada.
Devuelve: Valor numérico del último código de error.

errorDes()
Descripción del código de error de la última operación realizada.
Devuelve: Descripción del último código de error.

port()
Devuelve el número del puerto de la conexión remota.
Devuelve: Numero del puerto remoto.

recvLine( nResult, nTam )
Lee una línea de datos indicada por un fin de línea (CRLF) o el tamaño indicado, lo que ocurra primero. Esta método espera hasta que sea leido el fin de línea o se reciba el total de caracteres indicado en nTam.
Devuelve: Linea de datos, si se recibe el fin de línea (CRLF) no será incluido al final de la cadena.
nResult Variable enviada por referencia, en ella será devuelto el número de caracteres leido, si se recibe fin de línea (CRLF), nResult devolverá el total incluida la cadena, aunque no se incluya el fin de línea en ella, si no se envía no se devuelve el total de bytes recibidos
nTam Tamaño máximo de caracteres a leer, si o se envía, se espera hasta el fin de línea

recv( cDatos, nTam )
Lee caracteres hasta un máximo, ya sea el tamaño de cDatos, la cantidad indicada en nTam, o no se terminan los caracteres pendietes por leer en el puerto. Este método no bloquea el proceso, ya que en cuanto se termina de leer los caracteres pendientes devuelve lo leido y continúa, si se quiere detener el proceso hasta completar el leido necesario, deberá usarse el método recvAll()
Devuelve: Total de caracteres leidos.
cDatos Variable enviada por referencia, en ella será devuelo los caracteres leidos, los cuales se iran escribiendo sobre la información contenida en cDatos desde el primer caracter hasta el último, tal como sean leidos del puerto
nTam Tamaño máximo de caracteres a recibir, si o se envía, el límite es el tamaño de cDatos

recvAll( cDatos, nTam )
Lee caracteres hasta un máximo, ya sea el tamaño de cDatos o la cantidad indicada en nTam. Este método bloquea el proceso hasta que se llena cDatos, se lee la cantidad de caracteres indicada en nTam o el socket es cerrado, si no se quiere bloquer hasta esperar que se reciben todos los caracteres necesarios deberá usarse el método recv().
Devuelve: Total de caracteres leidos.
cDatos Variable enviada por referencia, en ella será devuelo los caracteres leidos, los cuales se iran escribiendo sobre la información contenida en cDatos desde el primer caracter hasta el último, tal como sean leidos del puerto
nTam Tamaño máximo de caracteres a recibir, si o se envía, el límite es el tamaño de cDatos

recvBlock( cFinBlock, nResult, nTam)
Lee un bloque de datos finalizado por una cadena de caracteres indicada o el tamaño indicado, lo que ocurra primero. Esta método espera hasta que sea leido el fin de línea o se reciba el total de caracteres indicado en nTam.
Devuelve: Bloque de datos, si se recibe el fin de bloque no será incluido al final de la cadena.
cFinBlock Cadena de caracteres que indica el final del bloque
nResult Variable enviada por referencia, en ella será devuelto el número de caracteres leido, si se recibe el fin de bloque, nResult devolverá el total incluido el bloque, aunque no se incluya el fin de bloque en ella, si no se envía no se devuelve el total de bytes recibidos
nTam Tamaño máximo de caracteres a leer, si o se envía, se espera hasta el encontrar el fin de bloque

setTimeOut( nMiliSec )
Asigna el tiempo en milisegundos que el socket esperara recibir alguna información, si se completa el tiempo sin recibir datos, el socket se cerrará automáticamente. Si se quiere mantener abierto indefinidamente, deberá indicarse -1.
Devuelve: NIL.
nMiliSec Milisegundos que esperara el socket antes de cerrarse. -1 asigna tiempo indefinido

getTimeOut()
Devuelve el tiempo en milisegundos que el socket tiene asignado para esperar información antes de cerrarse automáticamente.
Devuelve: Milisegundos que espera el socket información antes de cerrarse automáticamente.

sendAll( cData, nTam )
Envía todos los datos indicados.
Devuelve: Número de caracteres enviados.
cData Cadena de caracteres que desea enviarse
nTam Indica si solamente se envía una parte de la cadena, si es menor que el tamaño de cData, solo se envía lo indicado en nTam

sendLenAll( cData, nTam )
Envía el tamaño del bloque de datos que se va a enviar seguido de fin de línea (CRLF) y enseguida envía los datos indicados.
Devuelve: Número de caracteres enviados del blocue cData, no incluye la primera línea con el tamaño.
cData Cadena de caracteres que desea enviarse
nTam Indica si solamente se envía una parte de la cadena, si es menor que el tamaño de cData, solo se envía lo indicado en nTam

sendLine( cData )
Envía los datos seguidos de un fin de línea (CRLF).
Devuelve: Número de caracteres enviados.
cData Cadena de caracteres que desea enviarse

sendBlock( cData, cBlock )
Envía los datos seguidos de la cadena caracteres definida por el usuario como fin de bloque.
Devuelve: Número de caracteres enviados.
cData Cadena de caracteres que desea enviarse
cBlock Cadena que indica el fin de bloque

accept( xFunction )
accept( oClase, xMetodo )
Activa el socket de un objeto qSocket servidor para esperar conexiones, debe enviarse un códeblock, función o método que se disparara al momento de detectar un conexión nueva, esta función recibirá como parámetro un objeto qSocket con la nueva conexión.
Devuelve: NIL.
xFuncion Codeblock o nombre o apuntador de una función que se disparará al momento de detectar una nueva conexión
oClase Clase que contiene el método que se va a disparar al detectar una nueva conexión
xMetodo Nombre o apuntador al método que se disparará al momento de detectar una nueva conexión

sendFile( cHead, cFile, bMonitoreo )
Envía un un archvo precedido de un encabezado.
Devuelve: Si pudo abrir el archivo a enviar (.t.) o no (.f.).
cHead Encabezado que será enviado antes del archivo, si no se envía, no se envíará nada antes del archivo
cFile Nombre del archivo que será enviado, si el archivo no se encuentra en el directorio por defecto, deberá incluirse el camino
bMonitoreo Codeblock que se evalúa durante el proceso de envío del archivo, el cual puede ser utilizado para monitorear el avance, recibirá como parámetro los bytes del archivo leídos hasta el momento, el codeblock deberá devolvera un valor lógico, si es .f. se detendrá el proceso de envío. Es un parámetro opcional.

close()
Cierra ydestruye el socket, y actualiza contadors y depura variables internas del objeto.
Devuelve: NIL.

Ejemplo

function main
qSocket():init()
oSrv:newServer( 65523 )
oSrv:accept( @aceptar() )
? "Oprime cualquier tecla para terminar"
inkey( 0 )
killAllThreads()
waitforthreads()
return nil

static function aceptar( oSocket)
local cLinea
oSocket:sendLine( "Bien venido, eres el usuario " + lTrim( str( oSocket:nTotalCount ) ) )
do while .t.
   cLinea := oSocket:recvLine( @nResult )
   if nResult < 0
      exit
   endIf
   do case
      case cLinea == "saludo"
         oSocket:sendLine( "Hola" )
      case cLinea == "aviso"
         oSocket:sendLine( "¡Cuidado!" )
      case cLinea == "fin"
         exit
   endCase
endDo
oSocket:close()
return nil