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
BYTE
WORD
DWORD

Longitud
8 bits sin signo
16 bits sin signo
32 bits sin signo

Declaracin en C/C++
typedef unsigned char BYTE;

// 8-bit unsigned

typedef unsigned short int WORD; // 16-bit unsigned

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)

SUCCESS

0 (0x0000)

Descripcin
Operacin efectuada exitosamente.

Operaciones de control y configuracin del puerto serial.

PORT_ALREADY_OPEN
PORT_IN_USE
PORT_NOT_OPEN

1 (0x0001)

Puerto serial abierto.

2 (0x0002)

Puerto Serial en uso por otra aplicacin.

3 (0x0003)

INVALID_COM

4 (0x0004)

INVALID_BAUD_RATE

5 (0x0005)

Puerto Serial Cerrado

Puerto Serial utilizado en la apertura invlido o
inexistente.
Velocidad del Puerto Serial invlido o no
soportada.

Envo de datos.
TIMEOUT_ERROR
SEND_ERROR
PRINTER_OFF_OR_DISCONNECTED

6 (0x0006)
7 (0x0007)

Time-out de comunicacin.
Error en envo de datos.

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)

ANSWER_INVALID
ANSWER_FIELD_INEXISTENT
FIELD_INVALID_TYPE

11 (0x000B)

Formato del campo de entrada al buffer de

comandos invlido.
Campo de respuesta solicitado invlido.

12 (0x000C)

Campo de respuesta inexistente.

13 (0x000D)

Tipo de campo de respuesta invlido.

14 (0x000E)

Error interno del DLL.

Error interno
INTERNAL_ERROR

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
TYPE_ASCII

1 (0x0001)

Formato binario

2 (0x0002)

Formato ASCII

Constantes para la recuperacin de datos

TYPE_UCHAR
TYPE_CHAR
TYPE_USHORT
TYPE_SHORT
TYPE_UINT

4 (0x0004)
5 (0x0005)

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

Campo numrico de 8 bits con signo ( -128 a +127 )

6 (0x0006)

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

7 (0x0007)

Campo numrico de 16 bits con signo ( -32.768 a 32.767 )

8 (0x0008)

TYPE_INT

9 (0x0009)

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

Campo numrico de 32 bits con signo ( -2.147.483.648 a
2.148.483.647 )
Campo numrico de 32 bits sin signo ( 0 a 4.294.967.295 )
Campo numrico de 32 bits con signo ( -2.147.483.648 a
2.148.483.647 )
Vector de caracteres.

TYPE_ULONG

10 (0x000A)

TYPE_LONG

11 (0x000B)

TYPE_STRING

12 (0x000C)

2.5.Constantes para el manejo del estado del puerto serial

Constante
CLOSED
IDLE
BUSY

Valor (HEX)

Descripcin

1 (0x0001)

Puerto serial serrado.

2 (0x0002)
3 (0x0003)

Librera en estado idle.

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
ResendSerialMessage

Enva un mensaje por el puerto serial.

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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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
AddMessageFieldEx
PurgeMessage

Agrega datos binarios en el buffer de salida.

Agrega datos, en el formato especificado, al buffer de salida.
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 )
[Parmetros de Entrada]
szField

Campo que ser agregado al buffer de salida.

dwFieldLength

Tamao del campo szField.

[Parmetros de Salida]
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 )

[Parmetros de Entrada]
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.

[Parmetros de Salida]
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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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.

Retorna un campo del buffer de respuesta en el formato
solicitado.
Retorna el nmero de campos continuos en el buffer de
respuesta.

GetMessageFieldEx
GetFieldCounter

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 )

[Parmetros de Entrada]
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 )

[Parmetros de Entrada]
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.

[Parmetros de Salida]
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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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.

Retorna el error ocurrido en la ltima operacin de
comunicacin.

GetLastCommError

3.4.1. GetCommunicationState

Retorna el estado actual de la comunicacin serial.

[Prototipo]
DWORD GetCommunicationState ( void )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
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
GetSentFrame
GetReceivedFrame

Retorna la versin actual de la librera.

Retorna la ltima trama enviada a la impresora.
Retorna la ltima trama recibida de la impresora.

3.5.1. GetApiVersion

Retorna la versin de la librera.

[Prototipo]
void GetApiVersion (BYTE* szVersion)
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
szVersion
[Retorno]
Ninguno

Versin en formato XX.YY.

3.5.2. GetSentFrame

Retorna la ltima trama enviada al controlador fiscal.

[Prototipo]
DWORD GetSentFrame( BYTE* szSentBuffer, DWORD* dwBufferLength )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]

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 )
[Parmetros de Entrada]
Ninguno
[Parmetros de Salida]
szRecBuffer
.

dwBufferLength

ltima trama recibida.

Tamao en bytes del buffer szRecBuffer.

[Retorno]
SUCCESS

Trama obtenido con xito

INTERNAL_ERROR

Error interno de la librera.