manual libreria dll interfaz vmax rev. 02 - curazao

Manual Librera (DLL) de Interfaz VMAX

2013

Tabla de contenido

Captulo 1. Introduccin ...................................................................................................................... 4

Captulo 2. Definiciones ...................................................................................................................... 5

2.1. Tipos de datos ..................................................................................................................... 5

2.2. Funciones ............................................................................................................................ 5

2.3. Cdigos de respuesta .......................................................................................................... 5

2.4. Constantes para la insercin y recuperacin de datos ....................................................... 6

2.5. Constantes para el manejo del estado del puerto serial .................................................... 6

Captulo 3. Prototipos de las funciones .............................................................................................. 7

3.1. Configuracin y operacin del puerto serial ....................................................................... 7

3.1.1. OpenSerialPort .................................................................................................................. 8

3.1.2. CloseSerialPort .................................................................................................................. 9

3.1.3. SendSerialMessage.......................................................................................................... 10

3.1.4. ResendSerialMessage ...................................................................................................... 11

3.2. Manejo del buffer de salida .............................................................................................. 12

3.2.1. AddMessageField ............................................................................................................ 13

3.2.2. AddMessageFieldEx ......................................................................................................... 14

3.2.3. PurgeMessage ................................................................................................................. 15

3.3. Manejo del buffer de entrada ........................................................................................... 16

3.3.1. GetMessageField ............................................................................................................. 17

3.3.2. GetMessageFieldEx ......................................................................................................... 18

3.3.3. GetFieldCounter .............................................................................................................. 19

3.4. Estado de la comunicacin ................................................................................................ 20

3.4.1. GetCommunicationState ................................................................................................. 21

3.4.2. GetLastCommError .......................................................................................................... 22

3.5. Informacin de la librera .................................................................................................. 23

3.5.1. GetApiVersion ................................................................................................................. 24

3.5.2. GetSentFrame ................................................................................................................. 25

3.5.3. GetReceivedFrame .......................................................................................................... 26

Captulo 1. Introduccin

Este documento tiene como finalidad describir las funciones encapsuladas en la librera o

DLL de interfaz para la comunicacin con el controlador fiscal VMAX. La librera implementa la

capa de bajo nivel que consiste en el manejo del puerto serial y del protocolo de comunicacin del

controlador fiscal. Esta implementacin consiste en una serie de funciones con parmetros de

entrada y salida bajo un esquema de procesamiento multi-hilos.

De esta manera se garantiza rapidez y facilidad en la integracin con las aplicaciones de

punto de venta. La librera requiere de un sistema operativo Windows de 32 bits.

Captulo 2. Definiciones

2.1. Tipos de datos

Los tipos de datos utilizados en la librera son los siguientes:

Tipo de dato Longitud Declaracin en C/C++

BYTE 8 bits sin signo typedef unsigned char BYTE; // 8-bit unsigned

WORD 16 bits sin signo typedef unsigned short int WORD; // 16-bit unsigned

DWORD 32 bits sin signo typedef unsigned long DWORD; // 32-bit unsigned

2.2. Funciones

Las funciones de la librera estn definidas de alguna de las siguientes maneras:

extern "C" DWORD WINAPI FAR PASCAL NombreFuncion( Parmetros )

extern "C" void WINAPI FAR PASCAL NombreFuncion( Parmetros )

2.3. Cdigos de respuesta

A continuacin se describen los cdigos de respuesta que retornan las funciones,

agrupados por tipo de funcin.

Retorno Valor (HEX) Descripcin

SUCCESS 0 (0x0000) Operacin efectuada exitosamente.

Operaciones de control y configuracin del puerto serial.

PORT_ALREADY_OPEN 1 (0x0001) Puerto serial abierto.

PORT_IN_USE 2 (0x0002) Puerto Serial en uso por otra aplicacin.

PORT_NOT_OPEN 3 (0x0003) Puerto Serial Cerrado

INVALID_COM 4 (0x0004) Puerto Serial utilizado en la apertura invlido o

inexistente.

INVALID_BAUD_RATE 5 (0x0005) Velocidad del Puerto Serial invlido o no

soportada.

Envo de datos.

TIMEOUT_ERROR 6 (0x0006) Time-out de comunicacin.

SEND_ERROR 7 (0x0007) Error en envo de datos.

PRINTER_OFF_OR_DISCONNECTED 8 (0x0008) Impresora desconectada o fuera de lnea.

Insercin de datos en el buffer de envo.

BUFFER_OVERFLOW 9 (0x0009) Lmite del buffer de envo de datos alcanzado.

Recuperacin/insercin de datos en el buffer de envo/respuesta.

FIELD_INVALID 10 (0x000A) Formato del campo de entrada al buffer de

comandos invlido.

ANSWER_INVALID 11 (0x000B) Campo de respuesta solicitado invlido.

ANSWER_FIELD_INEXISTENT 12 (0x000C) Campo de respuesta inexistente.

FIELD_INVALID_TYPE 13 (0x000D) Tipo de campo de respuesta invlido.

Error interno

INTERNAL_ERROR 14 (0x000E) Error interno del DLL.

2.4. Constantes para la insercin y recuperacin de datos

A continuacin se describen los valores de las constantes para la insercin y

recuperacin de datos en el buffer de envo o respuesta.

Retorno Valor (HEX) Descripcin

Constantes para la insercin de datos.

TYPE_BINARY 1 (0x0001) Formato binario

TYPE_ASCII 2 (0x0002) Formato ASCII

Constantes para la recuperacin de datos

TYPE_UCHAR 4 (0x0004) Campo numrico de 8 bits sin signo ( 0 a 255 )

TYPE_CHAR 5 (0x0005) Campo numrico de 8 bits con signo ( -128 a +127 )

TYPE_USHORT 6 (0x0006) Campo numrico de 16 bits sin signo ( 0 a 65.535 )

TYPE_SHORT 7 (0x0007) Campo numrico de 16 bits con signo ( -32.768 a 32.767 )

TYPE_UINT 8 (0x0008) Campo numrico de 32 bits sin signo ( 0 a 4.294.967.295 )

TYPE_INT 9 (0x0009) Campo numrico de 32 bits con signo ( -2.147.483.648 a

2.148.483.647 )

TYPE_ULONG 10 (0x000A) Campo numrico de 32 bits sin signo ( 0 a 4.294.967.295 )

TYPE_LONG 11 (0x000B) Campo numrico de 32 bits con signo ( -2.147.483.648 a

2.148.483.647 )

TYPE_STRING 12 (0x000C) Vector de caracteres.

2.5. Constantes para el manejo del estado del puerto serial

Constante Valor (HEX) Descripcin

CLOSED 1 (0x0001) Puerto serial serrado.

IDLE 2 (0x0002) Librera en estado idle.

BUSY 3 (0x0003) Librera efectuando tareas en background.

Captulo 3. Prototipos de las funciones

3.1. Configuracin y operacin del puerto serial

Las funciones de esta seccin son las utilizadas para la configuracin, apertura y

cierre del puerto serial y tambin para el envo de datos a travs del mismo. Las

funciones son:

Funcin Descripcin

OpenSerialPort Efecta la apertura del puerto serial, reservando los recursos

de software y hardware necesarios para su utilizacin.

CloseSerialPort Efecta el cierre del puerto serial, liberando los recursos de

software y hardware alocados por la funcin OpenSerialPort.

SendSerialMessage Enva un mensaje por el puerto serial.

ResendSerialMessage Re-enva el ltimo mensaje por el puerto serial.

3.1.1. OpenSerialPort

Efecta la apertura del puerto serial, iniciando de este modo la comunicacin entre el

PC y el controlador fiscal. Una llamada realizada con xito a esta funcin es obligatoria

para el correcto funcionamiento de la librera.

[Prototipo]

DWORD OpenSerialPort(WORD wCommNumber, DWORD dwBaudRate)

[Parmetros de Entrada]

wCommNumber Nmero del puerto serial que ser utilizado para la

comunicacin con el controlador fiscal. Soporta valores de 1 a 99.

dwBaudRate Velocidad del puerto serial.

[Parmetros de Salida]

Ninguno

[Retorno]

SUCCESS Puerto abierto con xito.

. PORT_ALREADY_OPEN Apertura del puerto serial ya efectuada.

PORT_IN_USE Puerto serial en uso por otra aplicacin.

INVALID_COM Puerto serie utilizado para la apertura no existe.

INVALID_BAUD_RATE Velocidad utilizada para la apertura invlida.

INTERNAL_ERROR Error Interno de la Librera.

3.1.2. CloseSerialPort

Efecta el cierre del puerto serial, cerrando de este modo la comunicacin entre el PC

y el controlador fiscal.

[Prototipo]

DWORD CloseSerialPort( void )


Ninguno


Ninguno

[Retorno]

SUCCESS Puerto cerrado con xito.

. PORT_NOT_OPEN Puerto Serie no abierto por la funcin

OpenSerialPort.

3.1.3. SendSerialMessage

Enva un mensaje almacenado en el buffer de envo para la impresora fiscal. Esta

funcin ser de funcionamiento asncrono, y retornar el control a la aplicacin mientras el

controlador fiscal ejecuta el comando enviado.

[Prototipo]

DWORD SendSerialMessage ( void )


Ninguno


Ninguno

[Retorno]

SUCCESS Mensaje enviado con xito.

. INTERNAL_ERROR Error Interno de la Librera.

PORT_NOT_OPEN Puerto Serie no abierto por la funcin

OpenSerialPort.

3.1.4. ResendSerialMessage

Reenva un mensaje almacenado en el buffer de envo para la impresora fiscal. Esta

funcin ser de funcionamiento asncrono, y retornar el control a la aplicacin mientras el

controlador fiscal ejecuta el comando enviado.

[Prototipo]

DWORD ResendSerialMessage ( void )


Ninguno


Ninguno

[Retorno]

SUCCESS Mensaje enviado con xito.

. INTERNAL_ERROR Error Interno de la Librera.

PORT_NOT_OPEN Puerto Serie no abierto por la funcin

OpenSerialPort.

3.2. Manejo del buffer de salida

Las funciones descritas en esta seccin son utilizadas para agregar datos al buffer de

salida que sern enviados por el puerto serial a travs de las funciones de envo de la

seccin anterior. Las funciones son:

Funcin Descripcin

AddMessageField Agrega datos binarios en el buffer de salida.

AddMessageFieldEx Agrega datos, en el formato especificado, al buffer de salida.

PurgeMessage Limpia el buffer de salida.

3.2.1. AddMessageField

Agrega datos al buffer de salida, en formato binario. El separador de campos tambin

es agregado cuando es necesario.

[Prototipo]

DWORD AddMessageField( BYTE * szField, DWORD dwFieldLength )


szField Campo que ser agregado al buffer de salida.

dwFieldLength Tamao del campo szField.


Ninguno

[Retorno]

SUCCESS Campo agregado con xito.

. BUFFER_OVERFLOW Lmite del buffer de salida alcanzado.

INVALID_PARAM Parmetro szField nulo.

3.2.2. AddMessageFieldEx

Agrega datos al buffer de salida, en el formato especificado.

[Prototipo]

DWORD AddMessageFieldEx( BYTE * szField, DWORD dwLength, DWORD dwType, bool bSeparator )


szField Campo que ser agregado al buffer de salida.

dwLength Tamao del campo szField.

dwType Tipo de campo a ser agregado. Puede ser

TYPE_BINARY o TYPE_ASCII.

bSeparator Indica si un separador ser o no agregado al final

el campo.


Ninguno

[Retorno]

SUCCESS Campo agregado con xito.

. BUFFER_OVERFLOW Lmite del buffer de salida alcanzado.

INVALID_PARAM Parmetro szField nulo.

FIELD_INVALID Formato invlido de los datos en szField.

FIELD_INVALID_TYPE Campo en dwType invlido.

3.2.3. PurgeMessage

Borra todos los datos del buffer de salida para que un nuevo mensaje sea

agregado al mismo.

[Prototipo]

void PurgeMessage( void )


Ninguno


Ninguno

[Retorno]

Ninguno

3.3. Manejo del buffer de entrada

Las funciones descritas en esta seccin son utilizadas para capturar datos del

buffer de entrada, que sern recibidos por el puerto serial. Las funciones son:

Funcin Descripcin

GetMessageField Retorna un campo del buffer de respuesta en formato binario.

GetMessageFieldEx Retorna un campo del buffer de respuesta en el formato solicitado.

GetFieldCounter Retorna el nmero de campos continuos en el buffer de

respuesta.

3.3.1. GetMessageField

Captura un campo especfico del buffer de respuesta del controlador fiscal. Todos

los datos retornados por esta funcin estn en formato binario.

[Prototipo]

DWORD GetMessageField ( BYTE * szField, DWORD * dwFieldLength, DWORD dwAnswerField )


dwAnswerField Posicin del campo a ser recuperado del buffer de

respuesta del controlador fiscal. [Parmetros de Salida]

szField Campo buscado en el buffer de entrada.

dwFieldLength Tamao del campo szField.

[Retorno]

SUCCESS Campo obtenido con xito

. ASWR_INVALID Campo de respuesta solicitado invlido.

ASWR_FIELD_INEXISTENT Campo de respuesta solicitado no existe.

FIELD_INVALID_TYPE Tipo de campo de respuesta invlido.

INVALID_PARAM Parmetro szField y/o dwFieldLength nulo

INTERNAL_ERROR Error interno de la librera.

3.3.2. GetMessageFieldEx

Captura un campo especfico del buffer de respuesta de la impresora fiscal. El

formato del campo de respuesta puede ser seleccionado a travs del parmetro

dwFieldType, de acuerdo con a tabla de formatos disponibles.

[Prototipo]

DWORD GetMessageFieldEx ( void * vField, DWORD * dwLength, DWORD dwField, DWORD dwType )


dwField Posicin del campo a ser recuperado del buffer de

respuesta del controlador fiscal. dwType Tipo de formato a ser aplicado a la variable

apuntada por vField.


vField Campo solicitado. Se devuelve vacio en caso de

error.

dwLength Tamao del campo vField.

[Retorno]

SUCCESS Campo obtenido con xito

. ASWR_INVALID Campo de respuesta solicitado invlido.

ASWR_FIELD_INEXISTENT Campo de respuesta solicitado no existe.

FIELD_INVALID_TYPE Tipo de campo de respuesta invlido.

INVALID_PARAM Parmetro vField y/o dwField nulo

INTERNAL_ERROR Error interno de la librera.

3.3.3. GetFieldCounter

Esta funcin retorna un nmero total de campos recibidos del controlador fiscal.

[Prototipo]

DWORD GetFieldCounter( void )


Ninguno


Ninguno

[Retorno]

Nmero de campos en el buffer de entrada.

3.4. Estado de la comunicacin

Utilizadas para capturar el status actual de la comunicacin al igual que para

conocer el ltimo error ocurrido. No se debe enviar o recibir datos antes de efectuar

una llamada a estas funciones para verificar. Las funciones son:

Funcin Descripcin

GetCommunicationState Retorna el estado actual de las funciones de comunicacin.

GetLastCommError Retorna el error ocurrido en la ltima operacin de comunicacin.

3.4.1. GetCommunicationState

Retorna el estado actual de la comunicacin serial.

[Prototipo]

DWORD GetCommunicationState ( void )


Ninguno


Ninguno

[Retorno]

CLOSED Puerto serie de comunicacin cerrado.

IDLE Librera en estado Idle.

BUSY Librera efectuando tareas en background.

3.4.2. GetLastCommError

Retorna el ltimo error ocurrido en la comunicacin con el controlador fiscal.

[Prototipo]

DWORD GetLastCommError ( void )


Ninguno


Ninguno

[Retorno]

SUCCESS Operacin completada con xito.

TIMEOUT_ERROR Time-out de comunicacin.

SEND_ERROR Error de envo de datos.

PRINTER_OFF_OR_DISCONNECTED Impresora fuera de lnea o desconectada.

3.5. Informacin de la librera

Utilizadas para obtener informacin de la librera. Las funciones son:

Funcin Descripcin

GetApiVersion Retorna la versin actual de la librera.

GetSentFrame Retorna la ltima trama enviada a la impresora.

GetReceivedFrame Retorna la ltima trama recibida de la impresora.

3.5.1. GetApiVersion

Retorna la versin de la librera.

[Prototipo]

void GetApiVersion (BYTE* szVersion)


Ninguno


szVersion Versin en formato XX.YY.

[Retorno]

Ninguno

3.5.2. GetSentFrame

Retorna la ltima trama enviada al controlador fiscal.

[Prototipo]

DWORD GetSentFrame( BYTE* szSentBuffer, DWORD* dwBufferLength )


Ninguno


szSentBuffer ltima trama enviada.

. dwBufferLength Tamao en bytes del buffer szSentBuffer.

[Retorno]

SUCCESS Trama obtenido con xito

. INTERNAL_ERROR Error interno de la librera.

3.5.3. GetReceivedFrame

Retorna la ltima trama recibida del controlador fiscal.

[Prototipo]

DWORD GetReceivedFrame( BYTE* szRecBuffer, DWORD* dwBufferLength )


Ninguno


szRecBuffer ltima trama recibida.

. dwBufferLength Tamao en bytes del buffer szRecBuffer.

[Retorno]

SUCCESS Trama obtenido con xito

. INTERNAL_ERROR Error interno de la librera.

manual libreria dll interfaz vmax rev. 02 - curazao

Documents

puerto serial

tabla de contenido captulo

recuperacin de datos

buffer de salida

buffer de entrada

tipos de datos

cdigos de respuesta