manual de uso del dll cliente

¿Cómo utilizar el DLL Cliente de Medusa?

ClienteMedusa.DLL

manual de uso del dll cliente.odt 2. dic. 2009 Versión 1.2.1.0 Página 1/17


Página intencionalmente

dejada en blanco



Contenido1 Conceptos Básicos..................................................................................................................................5

1.1 ¿Qué es Medusa?.............................................................................................................................51.2 ¿Qué es el DLL Cliente de Medusa?...............................................................................................51.3 ¿Porqué debo utilizar el DLL en lugar de desarrollar yo mismo la parte de comunicaciones?.......5

2 Detalles Técnicos....................................................................................................................................72.1 Funciones expuestas de la librería...................................................................................................72.2 Aclaración sobre los tipos de datos...............................................................................................10

3 Emulador de Medusa.............................................................................................................................113.1 ¿Qué es el Emulador Medusa?......................................................................................................113.2 ¿Cómo utilizar el Emulador Medusa?...........................................................................................113.3 Interpretando el log........................................................................................................................12

4 Aplicación de ejemplo...........................................................................................................................144.1 Descripción....................................................................................................................................144.2 Operación de la aplicación............................................................................................................14

ANEXOS..................................................................................................................................................16Actualización: Versión 1.1.1.0 del 19 de Mayo de 2009....................................................................16Actualización: Versión 1.2.0.0 del 14 de Julio de 2009......................................................................17



Página intencionalmente

dejada en blanco



1 Conceptos Básicos

1.1 ¿Qué es Medusa?

Medusa es el nombre de un servidor de comunicaciones capaz de atender peticiones de diferentes servicios como son: venta de tiempo aire electrónico, pagos bancarios, monedero electrónico, etc.

1.2 ¿Qué es el DLL Cliente de Medusa?

Es una librería creada para facilitar el desarrollo de aplicaciones cliente que requieran comunicarse con un servidor Medusa con el fin de solicitar algún servicio. El dll está desarrollado para ser compatible con cualquier lenguaje de programación que tenga la capacidad de utilizar este tipo de librerías (Ej. VisualBasic, Delphi, C++, etc.).

Esta librería contiene internamente todo el esquema de comunicación y protocolo necesario para enviar las peticiones al servidor Medusa con simples llamadas a funciones, evitando así que el desarrollador del cliente tenga que preocuparse por la parte técnica del intercambio de información y pueda concentrarse en el desarrollo y funcionamiento de la aplicación.

1.3 ¿Porqué debo utilizar el DLL en lugar de desarrollar yo mismo la parte de comunicaciones?

Existen varias razones por las que es necesario utilizar el DLL y no se permite desarrollar la parte de comunicaciones de forma independiente:

● La principal razón es la facilidad. El desarrollador de la aplicación cliente no requiere preocuparse por los detalles técnicos y puede entonces concentrarse de la parte operativa.

● El DLL es una librería probada y desarrollada por la misma empresa desarrolladora del Medusa, lo cuál garantiza una completa compatibilidad entre el cliente y el servidor.

● La comunicación entre el cliente y el servidor se realiza mediante mensajes seguros, encriptados para garantizar que no puedan ser interceptados, modificados o incluso creados por un origen no



autorizado. Recordemos que la comunicación se puede establecer mediante medios no seguros como es el Internet, por lo que garantizar la seguridad y confidencialidad de la información es muy importante.

● Por último, el mantenimiento del software cliente es prácticamente nulo. Cada actualización que se realice al servidor Medusa puede tener asociada una nueva versión del DLL (en caso de que se habiliten nuevos servicios o se requiera modificar el cliente) la cuál se distribuirá a todos los clientes. Para realizar la actualización del software cliente simplemente se requiere reemplazar el DLL anterior por el nuevo y la aplicación seguirá funcionando.



2 Detalles Técnicos

2.1 Funciones expuestas de la librería

La librería contiene algunas funciones expuestas que pueden ser utilizadas por la aplicación cliente. Las siguientes tablas muestran el nombre y la descripción de los parámetros que se utilizan para poder utilizarlas.

Procedure SolicitarRegistroHW: Se utiliza para solicitar al servidor Medusa la autorización para realizar operaciones desde un nuevo Equipo (no registrado).

E/S Tipo de Dato Tamaño Parámetro Descripción

E String (Char *) Indef. servidor Dirección IP o URL para conectarse al servidor

E Entero Corto (16 bits) na puerto Puerto que el servidor tiene habilitado para la comunicación

E Entero (32 bits) na id_org Parámetro asignado por el distribuidor. Indica el número de organización con que desea operar.

E Entero Corto (16 bits) na num_suc Número de sucursal en donde se encuentra el equipo que se desea registrar.

E String (Char *) 20 caja Nombre de la terminal o estación de trabajo que se desea registrar.

E String (Char *) 10 usuario Clave o identificador del usuario que opera el equipo.

E Entero (32 bits) na num_sub Número de subdistribuidor asociado a la empresa que está registrando el equipo. Este dato es proporcionado por el proveedor del servicio (Distribuidor) al momento de registrarlo como cliente.

S Entero Corto (16 bits) na cod_res Código de respuesta del servidor (0 = OK, >0 = Error)

S String (Char *) 512 desc_res OK ó la descripción del error (según el código de respuesta)

S Entero Corto (16 bits) na len_desc_res Longitud de la cadena que contiene la descripción de la respuesta



Procedure RecargaTAE: Se utiliza para solicitar la recarga de tiempo aire electrónico a un celular de la compañía Telcel. No regresa valores. Antes: Procedure SolicitarVentaTAE (obsoleto, ver sección “actualizaciones”).




E Entero (32 bits) na id_servicio Parámetro que indica el servicio que se está requiriendo al servidor. Generalmente para solicitar la recarga será necesario enviar 1 (uno).

E Entero (32 bits) na id_org Parámetro asignado por el distribuidor. Indica el número de organización con que operan.

E Entero Corto (16 bits) na num_suc Número de sucursal en donde se realiza la venta

E String (Char *) 20 caja Nombre de la terminal o estación de trabajo en donde se realiza la venta

E String (Char *) 10 usuario Clave o identificador del usuario que realiza la venta

E String (Char *) 8 fec_vta Fecha en que se registra la venta (Formato: AAAAMMDD)

E String (Char *) 6 hora_vta Hora en que se registra la venta (Formato: HHMMSS)

E String (Char *) 2 tip_doc Tipo de documento de venta

E Entero (32 bits) na fol_doc Folio del documento de venta

E String (Char *) 10 num_tel Número de teléfono al que se desea realizar el abono (Formato: 9999999999)

E Currency (Double) na imp_abo Importe que se debe abonar al teléfono (Formato 099.99)




S String (Char *) 15 fol_prov Folio del proveedor (Telcel) asignado a la operación en caso de éxito (puede ser nulo)

S Entero Corto (16 bits) na len_fol_prov Longitud de la cadena que contiene el folio del proveedor.

S Entero (32 bits) na fol_ope Folio del servidor (Medusa) asignado a la operación en caso de éxito (puede ser nulo)



Procedure ReversaTAE : Se utiliza para solicitar la reversa a un movimiento previamente registrado de recarga de tiempo aire electrónico a un celular de la compañía Telcel. No regresa valores.Antes: Procedure ReversaVentaTAE (obsoleto, ver sección “actualizaciones”).




E Entero (32 bits) na id_servicio Parámetro que indica el servicio que se está requiriendo al servidor. Generalmente para solicitar la reversa será necesario enviar 1 (uno).

E Entero (32 bits) na id_org Parámetro asignado por el distribuidor. Indica el número de organización con que operan.

E Entero Corto (16 bits) na num_suc Número de sucursal en donde se realiza la reversa

E String (Char *) 20 caja Nombre de la terminal o estación de trabajo en donde se realiza la reversa

E String (Char *) 10 usuario Clave o identificador del usuario que realiza la reversa

E String (Char *) 8 fec_rev Fecha en que se solicita la reversa (Formato: AAAAMMDD)

E String (Char *) 6 hora_rev Hora en que se solicita la reversa (Formato: HHMMSS)

E String (Char *) 2 doc_vta Tipo de documento de venta

E Entero (32 bits) na fol_vta Folio del documento de venta

E String (Char *) 10 num_tel Número de teléfono al que se realizó el abono en la venta (Formato: 9999999999)

E Currency (Double) na imp_abo Importe que se abonó al teléfono en la venta (Formato 099.99)

E String (Char *) 15 fprov_vta Folio del proveedor (Telcel) con que se registró la venta

E Entero (32 bits) na fope_vta Folio del servidor (Medusa) con que se registró la venta




S String (Char *) 15 fol_prov Folio del proveedor (Telcel) asignado a la operación en caso de éxito (puede ser nulo)



S Entero Corto (16 bits) na len_fol_prov Longitud de la cadena que contiene el folio del proveedor.

S Entero (32 bits) na fol_ope Folio del servidor (Medusa) asignado a la operación en caso de éxito (puede ser nulo)

2.2 Aclaración sobre los tipos de datos

Los tipos de datos pueden variar de un lenguaje de programación a otro, sin embargo en la librería se utilizan tipos de datos estándar que deben existir en cualquier lenguaje. El nombre puede variar pero por la longitud del campo se puede determinar el tipo de dato correspondiente.

Para los tipos de datos enteros, se utilizan enteros con signo. El rango común para los enteros cortos es de –32768..32767 mientras que para los enteros es de –2147483648..2147483647. Para el tipo de datos Currency se puede manejar cualquier tipo de dato flotante (con decimal) ya que la precisión no es significativa (sólo se consideran 2 decimales).

Para los tipos de datos cadena, se utilizan apuntadores a cadenas de caracteres que es el tipo base para la mayoría de los lenguajes aun cuando muchos lenguajes nuevos utilizan tipos string que optimizan y manejan internamente el espacio en memoria.

Nota importante:

Lenguajes como VisualBasic proporcionan un manejo muy eficiente para las cadenas de caracteres mediante el tipo de datos string, sólo hay que considerar que para pasarlos como parámetros de salida (se espera que el DLL llene la variable) siempre se deben pasar por valor (al pasar un string por valor siempre se pasa la dirección de memoria del primer carácter de la cadena, lo cuál no ocurre al pasarlos por referencia), además de asignarle un espacio suficiente en memoria antes de llamar a la función, esto debido a que el manejo de memoria entre la aplicación y el DLL no se comparte.



3 Emulador de Medusa

3.1 ¿Qué es el Emulador Medusa?

El Emulador de Medusa es una pequeña aplicación desarrollada con el fin de realizar las pruebas necesarias en el software cliente. El emulador medusa no realiza ninguna conexión con un servidor externo sino que por si mismo es un servidor de comunicaciones TCP.

Las validaciones y respuestas que proporciona el emulador son muy limitadas ya que el propósito del software NO es realizar las funciones del medusa, simplemente permite la realización de pruebas de conexión y comunicaciones.

El emulador no registra los eventos ocurridos, simplemente presenta en pantalla un log con el intercambio de información que se está realizando entre el cliente y el servidor, de tal forma que el desarrollador del cliente pueda certificar que la información que envía se está recibiendo correctamente en el servidor y pueda validar que la respuesta del servidor sea correctamente recibida y procesada por el cliente.

Un punto importante que aclarar es que el emulador no es una simple aplicación que reciba información “adaptada para las pruebas”. La información que se intercambia entre el cliente y el emulador tiene los mismos esquemas de seguridad y formato que se tendrían si se tratara de un servidor Medusa real.

3.2 ¿Cómo utilizar el Emulador Medusa?

El emulador es una aplicación muy simple en términos de uso. El emulador está preconfigurado para trabajar con el puerto 9099, sin embargo se puede modificar el puerto por el que escucha para utilizar algún otro. Es importante que en la computadora que se utilice para ejecutar el emulador se verifique que dicho puerto no esté en uso por otra aplicación y que esté abierto para escuchar conexiones entrantes (esto es en caso de que el cliente y el emulador se encuentren en dos estaciones distintas).

El emulador es una aplicación para Windows que corre sin necesidad de ninguna librería extra.

Ejecute el programa, en él se puede observar una ventana grande en donde se registra el log de actividades, al fondo se encuentran cuatro botones y dos check box. Los dos botones de la izquierda permiten iniciar y detener el servidor respectivamente, el servidor debe estar iniciado para poder escuchar las peticiones del DLL. El botón “Limpiar log” borra el texto registrado en el log para las pruebas realizadas previamente. El botón que tiene el icono de un “cronómetro” se utiliza en caso de que se configure el emulador para no responder de forma inmediata (esto permite emular TimeOuts).



El check box con la leyenda “Abono realizado correctamente” permite configurar la respuesta que realizará el emulador ante las peticiones recibidas. Si está marcado indica que todas las peticiones recibidas se responderán con OK y un folio de proveedor y de operación (son generados en base a un consecutivo por lo que cada vez que se reinicie la aplicación generará los mismos folios). En caso de que NO esté marcado, el servidor responderá con un código de error y la descripción del mismo. Los códigos de error son generados aleatoriamente y pueden no coincidir con los códigos reales del servidor Medusa, se utilizan simplemente como ejemplo de lo que puede ocurrir al realizar una operación que no se complete adecuadamente.

El check box con la leyenda “Responder inmediatamente” permite emular situaciones en que ocurran TimeOuts o desconexiones y se utiliza junto con el botón de “cronómetro”. Si está marcado el servidor responderá de forma inmediata a todas las peticiones que reciba. Cuando no esté marcado, al obtener una petición no responderá a la misma hasta que se presione el botón de cronómetro que indica que debe continuar con la respuesta.

Nota importante: El emulador no valida que una reversa sea generada a partir de una venta correcta ya que no almacena ninguna información de las operaciones atendidas. La reversa siempre será válida cuando el check box de respuesta esté marcado y será inválida cuando no lo esté sin importar los datos que contenga.

3.3 Interpretando el log

El log que presenta el emulador es muy fácil de interpretar. Registra los siguientes eventos:

● Inicio del servidor. Marca la fecha y hora en que el servidor se inicia y comienza a recibir peticiones de los clientes.

● Fin del servidor: Marca la fecha y hora en que el servidor se detiene y cierra la conexión con los clientes activos.

● Conexión del cliente: Marca la fecha, hora y dirección IP desde la que se está realizando una conexión con el servidor.

● Mensaje del cliente: Marca la fecha y hora en que se recibió el mensaje así como la IP de donde se recibió. Después el servidor analizará el mensaje para generar una respuesta. Los mensajes pueden ser de dos tipos:

Recarga de Tiempo Aire: Inicia con la leyenda “Abono TAE”, el servidor indica los datos contenidos en el mensaje: Sucursal, Caja, Usuario, Folio de la venta, Teléfono y Monto a abonar. Estos datos deben corresponder a los enviados por el cliente.



Reversa a una Recarga de Tiempo Aire: Inicia con la leyenda “Reversa TAE”, el servidor indica los datos contenidos en el mensaje: Sucursal, Caja, Usuario, Folio de la venta, Teléfono, Monto a abonar, Folio del proveedor de la venta y Folio de operación de la venta. Estos datos deben corresponder a los enviados por el cliente.

Respuesta del servidor al mensaje: Comienza con la leyenda “Respuesta”, el servidor presenta la información de la respuesta que será enviada al cliente: Código de respuesta, Descripción de la respuesta, Folio del proveedor (sólo en caso de éxito) y Folio de operación (sólo en caso de éxito).

● Desconexión: Marca la fecha, hora y dirección IP del cliente que cerró la sesión con el servidor.



4 Aplicación de ejemplo

4.1 Descripción

La aplicación de ejemplo que se incluye contiene el código fuente y ejecutable de un pequeño programa cliente realizado para demostrar el uso de la librería del cliente medusa. Para su correcto funcionamiento el dll debe encontrarse en la misma carpeta en que se encuentre la aplicación.

La aplicación de ejemplo incluye el código fuente de la misma y puede modificarse libremente con el objeto de realizar las pruebas que se consideren necesarias. Existen dos versiones una desarrollada en Delphi que utiliza las funciones actuales de la librería y otra desarrollada en Visual Basic que hace uso de las funciones obsoletas de la librería. El código fuente del programa en ejemplo en Visual Basic podría no estar actualizado pero se presenta con el único fin de ejemplificar la forma en que se puede utilizar la librería en un programa desarrollado en este lenguaje, modificarlo para que funcione de forma correcta con la librería no debería representar mayor problema.

4.2 Operación de la aplicación

Para operar la aplicación simplemente se deben llenar los datos solicitados para la operación y solicitar el servicio deseado. Cabe mencionar que debe estar corriendo el emulador de Medusa para procesar las peticiones y responder adecuadamente de otra forma la aplicación puede generar errores inesperados. Se debe indicar la ip o url donde se encuentra el emulador así como el puerto que por default es el 9099 (para el emulador es el único puerto válido a menos que exista un firewall con un ruteo de puertos).

La aplicación es muy sencilla por lo que espera que todos los datos se introduzcan con el formato correcto (no se realiza ninguna validación de los datos introducidos ni se verifica que estén completos, por lo que introducir datos inválidos puede generar errores inesperados) ya que el objeto de la misma NO es proporcionar una interfaz final para realizar la operación sino simplemente demostrar la forma en que se debe utilizar el dll.

La aplicación tiene las siguientes funciones:

● Limpiar: Borra los datos contenidos en los campos para que sean llenados nuevamente por el usuario.



● Llenar: Llena todos los campos con información generada de forma aleatoria para facilitar al usuario las pruebas.

● Solicitar Recarga: Realiza la petición de recarga de tiempo aire al servidor con los datos introducidos.

● Solicitar Reversa: Realiza la petición de reversa de una recarga de tiempo aire al servidor con los datos introducidos.

● Salir: Finaliza la aplicación.



ANEXOS

Actualización: Versión 1.1.1.0 del 19 de Mayo de 2009

Es necesario realizar un cambio a la interface externa del DLL con el objeto de manejar la respuesta del proveedor (Telcel) cuando se realiza la recarga mediante el sistema de StreetSeller. Esto traerá como consecuencia que se tengan que realizar adecuaciones en los sistemas que actualmente utilizan la DLL.

Justificación:

Anteriormente la respuesta que se podía recibir por parte de Telcel correspondía a un valor entero de máximo 8 dígitos. En la última versión del servidor Medusa se permite realizar recargas mediante el sistema StreetSeller el cuál puede originar una clave de autorización de hasta 15 dígitos. Este tamaño de variable para un entero NO es compatible con la mayoría de los lenguajes de programación y/o bases de datos, por lo que fue necesario modificar el tipo de dato de respuesta para que ahora sea de tipo cadena. También se agregó un nuevo parámetro de respuesta que indica el tamaño de la cadena que se está recibiendo con la autorización (tal como sucede con la descripción de la respuesta).

Sabemos las consecuencias de realizar este tipo de modificaciones que afectan el desarrollo de los clientes actuales y esperamos su comprensión ya que el único fin de realizarlas es crecer y eficientar el sistema que estamos utilizando. Es importante aclarar que este tipo de actualizaciones no son “normales” por lo que deseamos brindarles la seguridad de que sus desarrollos no se verán afectados continuamente.

Compatibilidad con versiones anteriores:

Con el fin de disminuir el impacto que puede tener el migrar los sistemas existentes que utilizan la DLL a la nueva versión, se mantienen las funciones anteriores (SolicitarVentaTAE y ReversaVentaTAE) y se modificaron de tal forma que la clave de autorización, cuando sea mayor a 9 dígitos será truncada, regresando únicamente los 9 últimos dígitos en un tipo de datos entero. Esto aún cuando es funcional no es correcto por lo que se recomienda migrar lo más pronto posible a la nueva versión.

Nuevos desarrollos y actualización de sistemas:

Para los nuevos desarrollos y migrar los desarrollos existentes será necesario utilizar las nuevas



funciones expuestas: RecargaTAE y ReversaTAE ya que las funciones anteriores podrían ser eliminadas o inutilizables en versiones futuras de la librería.

Las diferencias entre las funciones anteriores y las nuevas se encuentran resaltadas en la tabla de parámetros mediante un color amarillo. Se recomienda a todos los desarrolladores y clientes que aún estén usando las funciones obsoletas, migren a la brevedad sus sistemas a las nuevas versiones.

Actualización: Versión 1.2.0.0 del 14 de Julio de 2009

Se agrega el método a la interface externa que permite enviar la solicitud de registro de un equipo al servidor con el fin de agilizar el trámite necesario para autorizar el enlace del mismo. Cómo se mencionó antes la comunicación entre el servidor Medusa y sus clientes es segura por lo que sólo equipos registrados pueden hacer uso de los servicios ofrecidos.


manual de uso del dll cliente

Documents