#ifndef _posnetH_
#define _posnetH_

/*

	Nagłówek w wersji: 1.0

*/


/*!
	\mainpage Biblioteka interfejsu kasy POSNET COMBO oraz POSNET NEO
	
	Spis Treści

	- \ref sec_intro 
	- \ref sec_flow 
	- \ref sec_async
	  - \ref sec_async_events
	  - \ref sec_async_sale_buffer
	  - \ref sec_modem
	  .
	- \ref sec_example
	- \ref sec_extern
	- \ref linux_port
	.

	<b> Zgodnie z INSTRUKCJĄ PROGRAMISTY COMBO 1.01, v. 1.6.61.1
	oraz SPECYFIKACJĄ PROTOKOŁU KASY POSNET NEO 1.01 v. 006
	oraz SPECYFIKACJĄ PROTOKOŁU KAS POSNET NEO 1.02 ORAZ POSNET COMBO 1.02 v.004 </b>

	<hr>

	\section sec_intro	Wprowadzenie

	Podstawowe założenia, które zostały przyjęte przy projektowaniu biblioteki dla
	kasy POSNET COMBO są następujące:
	  - komunikacja za pośrednictwem RS-232, USB (VCP lub DXX), Ethernet
	  - wielowątkowość i wielo-urządzeniowość biblioteki (brak zmiennych globalnych)
	  - obsługa zdarzeń asynchronicznych (karta rabatowa)
	  - kolejkowanie rozkazów w celu przyspieszenia wymiany danych
	  - wykorzystanie z różnych języków programowania (konwencja wywołań __stdcall zgodna 
		z WINAPI)
	  - minimalna zależność od systemu operacyjnego w zakresie interfejsu biblioteki -
	    praktycznie tylko 2 funkcja są typowo dedykowane dla Windows - \ref POS_GetEvent
		i \ref POS_SetMessageParams.
	  - interfejs śledzenia (\ref debugging)
	  - natywny port dla systemu Linux
	  .
    
	Ze względu na to, że ilość rozkazów wykorzystywanych w komunikacji z kasą jest ogromna
	przy projektowaniu biblioteki zrezygnowano z literalnej realizacji każdego rozkazu
	jako osobnej funkcji. Grupowanie rozkazów w/g rodzaju parametrów także nie jest dobrym
	rozwiązaniem. W tej sytuacji został zastosowany model "obiektu rozkazowego (Request)",
	wraz z zestawem funkcji umożliwiających ustawianie parametrów (\ref req_param). 

	Zastosowanie takiego rozwiązania ma dodatkową zaletę. Drobne korekty w rozkazach obsługi
	kasy w tym dodanie nowych czy zmiana ilości i rodzaju parametrów nie wymagają wtedy
	zmian w bibliotece komunikacyjnej, a jedynie dostosowania aplikacji do tych zmian.

	Po wykonaniu takiego obiektu rozkazowego przez kasę (por. \ref sec_flow) wyniki 
	dostępne są w analogiczny sposób - przez zestaw funkcji pobierających je kolejno
	z obiektu rozkazowego.

	Cztery niezależne kolejki rozkazowe (rozkazy oczekujące, rozkazy wykonane, zdarzenia
	asynchroniczne i pozycje paragonowe) umożliwiają jednocześnie dużą swobodę przy 
	tworzeniu aplikacji klienckiej zostawiając znaczną swobodę wybory sposobu obsługi kasy
	jej twórcy.

	\section sec_flow	Przepływ informacji

	W aplikacji istnieją 4 kolejki rozkazowe, pomiędzy którymi następuje przepływ danych 
	jak w grafie poniżej.
	\dot
	digraph flow {
		node [shape=record, fontname=Helvetica, fontsize=8];
		K0 [label="Kolejka rozkazowa"  shape="ellipse" ]
		K1 [label="Kolejka wynikow"  shape="ellipse" ]
		K2 [label="Kolejka asynchroniczna"  shape="ellipse" ]
		K3 [label="Bufor paragonowy" shape="ellipse" ]
		NOWY -> OCZEKUJACY [label="POS_PostRequest" fontname=Helvetica fontsize=8];
		OCZEKUJACY -> K0;
		K0 -> WYSLANY [label="transmisja do kasy" fontname=Helvetica fontsize=8];
		WYSLANY -> POTWIERDZONY [label="sekwencja zlozona" fontname=Helvetica fontsize=8];
		WYSLANY -> ZAKONCZONY [label="sekwencja prosta\n lub blad" fontname=Helvetica fontsize=8];
		POTWIERDZONY -> ZAKONCZONY [label="sekwencja zlozona" fontname=Helvetica fontsize=8];
		ZAKONCZONY -> K1 [label="Rozkaz" fontname=Helvetica fontsize=8]
		ZAKONCZONY -> K2 [label="Asychroniczny" fontname=Helvetica fontsize=8]
		ZAKONCZONY -> K3 [label="Paragonowy" fontname=Helvetica fontsize=8]
	}
	\enddot

	Całość transmisji obsługiwana jest przez dwa niezależne wątki, jeden transmisyjny,
	drugi odbiorczy operujące na odpowiednich kolejkach rozkazów.

	\section sec_async	Zdarzenia asynchroniczne i bufor paragonowy

	\subsection sec_async_events Zdarzenia asynchroniczne

	Kasa POSNET COMBO posiada możliwość generacji pewnych
	zdarzeń w sposób asynchroniczny w stosunku do wykonywanych poleceń
	wydawanych przez nadzorującą ją aplikację sterująco-magazynową.
	
	Do obsługi zdarzeń w tym trybie został przygotowany zestaw funkcji
	opisany w module \ref event_handling. Przychodzące zdarzenia asynchroniczne 
	gromadzone są w osobnej kolejce zdarzeń, w której oczekują na obsługę.
	Aplikacja główna może zostac powiadomiona o przyjściu nowego zdarzenia
	za pomocą:
	  - zdarzenia IPC typu "Event" systemu Windows,
	  - komunikatu Windows wysłanego do wskazanego okna aplikacji
	
	Aplikacja może też cyklicznie sprawdzać, czy w kolejce znajdują się nowe
	zdarzenia asynchroniczne (polling).

	\subsection sec_async_sale_buffer	Bufor pozycji paragonowych

	Aby uprościć obsługę pozycji paragonowych tak, aby nie kolidowała z główną kolejką
	zdarzeń i w efekcie mogła być obsługiwana za pośrednictwem osobnego watku aplikacji
	została stworzona osobna kolejka zdarzeń zbierająca wyniki poleceń czytających
	pozycje paragonowe patrz \ref sale_buffer.

	W ten sposób wątek odbioru danych paragonowych może wysyłać zapytania o pozycje
	paragonowe w standadowy sposób (do głównej kolejki rozkazów). Główna kolejka
	rozkazów do wysłania może równolegle otrzymywać rozkazy przygotowywane przez różne 
	wątki (jest w pełni wielowątkowa), serializować je i wysyłac w kolejności otrzymania
	do kasy.

	Odpowiedzi są natomiast rozdzielane od siebie i trafiają do dwóch osobnych
	kolejek odbiorczych. W kolejce pozycji paragonowych umieszczane są wyłącznie
	wyniki wysyłanych rozkazów dotyczących pozycji paragonowych.

	Mogą to być własciwe pozycje paragonowe lub informacje o błędach wykonania
	tych rozkazów.

	\section sec_modem Obsługa modemu
	Obsługa modemu w bibliotece COMBO/NEO jest realizowana poprzez trzy 
	dodatkowe funkcje biblioteczne oraz trzy dodatkowe parametry 
	dla urządzenia typu RS232. Umożliwia realizację zarówno połączeń 
	wychodzących (wybieranie numeru telefonu) jak i przyjmowanie 
	połączeń przychodzących (odbieranie telefonu). Stanowi ona integralną 
	część urządzenia typu RS232.

	Aby włączyć tryb modemowy należy ustawić parametr urządzenia 
	RS232  POSNET_DEV_PARAM_MODEMMODE na wartość 1. Po wykonaniu tej 
	czynności urządzenie nie będzie wykonywało zleconych poleceń do 
	momentu nawiązania połączenia modemowego. Urządzenie jest także 
	gotowe do przyjmowania połączeń przychodzących. W przypadku 
	pojawienia się sygnału RING na modemie zostanie automatycznie odebrana rozmowa.

	UWAGA: W trybie odbioru rozmowy nie ma możliwości ustawienia modemu ciągiem 
	inicjującym bezpośrednio (tryb zaczyna się pasywnie) – można to jednak 
	zrobić za pośrednictwem polecenia dzwonienia bez ustawiania numeru 
	telefonu (polecenie to zakończy się błędem POSNET_STATUS_MODEM_BADDIAL) ale 
	wyśle do modemu ciąg inicjujący.

	Dla urządzenia modemowego można ustawić dwa ciągi:
	  - ciąg inicjujący modem wraz z początkowym ciągiem „AT” np. AT&S0=0 – parametr POSNET_DEV_PARAM_MODEMINIT
	  - ciąg dzwonienia wraz z początkowym ATD np. ATDT022123456789 – parametr POSNET_DEV_PARAM_MODEMDIAL

	Urządzenie modemowe NIGDY samo nie wybiera numeru i nie ponawia 
	przerwanych połączeń – ta operacja pozostawiona jest w gestii aplikacji 
	zarządzającej kasami.

	Do obsługi trybu modemowego służą następujące funkcje
	  - Do wykonania połączenia służy funkcja: \ref POS_ModemDial , która wymaga dwóch parametrów – uchwytu globalnego urządzenia (nie uchwytu widoku lokalnego) oraz flagi „wait” oczekiwania na wykonanie połączenia (0 – nie czekaj, 1 – czekaj na zakończenie operacji). W przypadku wyboru trybu bez oczekiwania postęp procesu można monitorować z wykorzystaniem funkcji POS_ModemStatus – poprawne połączenie jest sygnalizowane statusem POSNET_STATUS_MODEM_CONNECTED.
	  - Do rozłączenia trwającego połączenia służy funkcja: \ref POS_ModemDisconnect , która przyjmuje takie same parametry jak polecenie dzwonienia i wykonuje procedurę rozłączania połączenia,
	  - Do sprawdzania bieżącego statusu modemu służy funkcja: \ref POS_ModemStatus , która zwraca zestaw flag zależnych od aktualnego stanu połączenia modemowego:

	Przykład użycia – patrz demo demo_modem.exe.


	\section sec_example	Przykładowa sekwencja poleceń

	Obsługa kasy wymaga wykonania pewnego zestawu standardowych
	operacji. Poniższy opis przedstawia jedną z możliwości na
	przykładzie polecenia DSPPARAMGET. Przykład jest w języku C++,
	pominięto obsługę sytuacji wyjątkowych.

	\code
	// Deklaracje zmiennych
	POSNET_HANDLE hDevice;
	POSNET_HANDLE hGlobalDevice;
	POSNET_HANDLE hRequest;

	// Wyniki
	unsigned char kontrast;
	unsigned char podswietlenie;
	unsigned char tryb;

	// Utworzenie obiektu urządzenia
	hGlobalDevice = POS_CreateDeviceHandle(POSNET_INTERFACE_RS232);

	// Ustawienie parametrów urządzenia
	POS_SetDeviceParam(hGlobalDevice, POSNET_DEV_PARAM_COMSETTINGS,"COM1,19200,8,N,1,H");

	// Otwarcie urządzenia
	hDevice = POS_OpenDevice(hGlobalDevice);

	// Przygotowanie polecenia
	// Numer polecenia DSPPARAMGET = 101
	hRequest = POS_CreateRequest(hDevice,POSNET_CMDID_DSPPARAMGET);

	// Przygotowanie parametrów polecenia
	// Pobierz dane dla wyświetlacza operatora
	// Wymagany 1 paramter typu 'B' o wartości 0
	POS_PushRequestParamByte(hRequest,0);

	// Wyślij rozkaz do kasy w trybie interaktywnym
	POS_PostRequest(hRequest,POSNET_REQMODE_IMMEDIATE);

	// Oczekuj na wykonanie
	POS_WaitForRequestCompleted(hRequest,INFINITE);

	// Sprawdź czy zakończyło się sukcesem
	if (POS_GetRequestStatus(hRequest) == POSNET_STATUS_OK)
	{
		// Pobranie wyników, polecenie zwraca 3 wartości typu byte
		unsigned char kontrast,podswietlenie,tryb;
		POS_PopResponseValueByte(hRequest,&kontrast);
		POS_PopResponseValueByte(hRequest,&podswietlenie);
		POS_PopResponseValueByte(hRequest,&tryb);
	}

	// Usuń stworzone zapytanie
	POS_DestroyRequest(hRequest);

	// Zamknij urządzenie
	POS_CloseDevice(hDevice);

	\endcode

	\section sec_extern	Wykorzystanie w językach programowania

	W wersji prototypowej biblioteka została przetestowana w:
	  - VisualC++ .NET 2003
	  - Borland C++ Builder 4
	  - Delphi 7
	  - Visual Basic for Applications (MS Excel)
	  - Ch  (<a href='http://www.softintegration.com'>http://www.softintegration.com</a>)
	
	Poniżej przedstawiono przykładowy kod dla VBA.
	\verbatim
	Private Declare Function POS_PopSalesQueue Lib "posnet.dll" (ByVal H As Long, ByVal P As Long) As Long
	\endverbatim

	Podobny kod dla Delphi 7

	\verbatim
	function POS_PopSalesQueue (hDevice : THandle; k: longint) : THandle; stdcall; external 'posnet.dll'
	\endverbatim

	\section linux_port Wersja dla systemu Linux

	Natywny port dla systemu Linux składa się z bibliotek:

	libposnet.so.1.0

	libhlapi.so.1.0

	oraz 

	libptypes.so.2.0.2 (http://www.melikyan.com/ptypes/)

	Biblioteki te są zależne także od dostępnych na licencji LGPL bibliotek obsługujących
	podsystem USB:

	libusb - w wersji 0.1.11+ dostępnej standardowo w większości dystrybucji
	(http://libusb.sourceforge.net/)

	oraz 

	libftdi w wersji 0.7+ (http://www.intra2net.com/de/produkte/opensource/ftdi/index.php)
	do obsługi konwertera FTDI zastosowanego w urządzeniu.

	UWAGA!!!  W przypadku korzystania z trybu natywnego USB (POSNET_INTERFACE_USB)
	do poprawnego działania kasy niezbędne jest zablokowanie automatycznego ładowania
	i usunięcie jesli jest załadowany modułu jądra ftdi_sio. W przeciwnym razie połączenie z kasą nie będzie
	możliwe (w pliku logu zgłaszany będzie błąd o kodzie -5), gdyż moduł ten przejmuje kontrolę nad konwerterem
	FTDI tworząc wirtualny port szeregowy (/dev/ttyUSBx).

	W przypadku korzystania w trybie wirtualnego portu szeregowego, sterownik ftdi_sio jest potrzebny.
*/


/*!
	\ingroup global_defs
	\brief	Standardowy sposób obsługi bibliotek DLL
*/
/* Patch dla Borland C++ Builder'a */
#ifdef __WIN32__
#define WIN32 
#endif

#ifdef WIN32
#ifdef POSNET_EXPORTS
#define POSNET_API  __declspec(dllexport)	
#else
#define POSNET_API  __declspec(dllimport)	
#endif
#else
#define POSNET_API
#define __stdcall
#define __cdecl
#endif

extern "C"
{

	/*!
		\defgroup	global_defs Definicje globalne
		@{
		
	*/
	/*!
	\brief Definicja typu uchwytu urządzenia.
	*/
	typedef  void*					POSNET_HANDLE;
	/*!
	\brief Definicja typu wartości zwracanej jako status.
	*/
	typedef	 unsigned long			POSNET_STATUS;
	/*!
	\brief Definicja typu wartości zwracanej jako stan rozkazu.
	*/
	typedef	 unsigned long			POSNET_STATE;
	/*!
	\brief Definicja typu wartości reprezentującej kod polecenia.
	*/
	typedef	 unsigned short			POSNET_CMD;
	/*!
	\brief Definicja typu wartości reprezentującej typ danych w polach DATA.
	*/
	typedef	 unsigned long			POSNET_DATA_TYPE;

	/*!
	\brief	Pobierz wersję biblioteki

	\return	Wersja jako liczba 32 bitowa. Liczba ta składa się z trzech części. Najstarsze 8 bitów to główny
	 numer wersji, następne 8 to podrzędny numer wersji, oststanie 16 bitów to numer kompilacji.
	*/

	POSNET_API unsigned long __stdcall POS_GetLibraryVersion();


	/*!
		@}
	*/


	/*!
		\defgroup	data_types	Typy danych pól DATA
		\ingroup	sync_api
		
		\sa POS_GetResponseValueType
		@{
	*/
	
	#define	POSNET_DATATYPE_STRING		'S' //!< Ciąg znaków
	#define POSNET_DATATYPE_BYTE		'B'	//!< Liczba całkowita 1 bajtowa
	#define POSNET_DATATYPE_WORD		'V'	//!< Liczba całkowita 2 bajtowa
	#define POSNET_DATATYPE_LONG		'L'	//!< Liczba całkowita 4 bajtowa
	#define POSNET_DATATYPE_QUANTITY	'Q'	//!< Typ ilościowy (nie wykorzystywany w obecnej wersji kasy)
	#define POSNET_DATATYPE_CURRENCY	'K'	//!< Typ walutowy (nie wykorzystywany w obecnej wersji kasy)
	#define POSNET_DATATYPE_NUMERIC		'N'	//!< Typ numeryczny
	#define POSNET_DATATYPE_INVALID		'*'	//!< Typ niewłaściwy/błąd


	/*!
		@}
	*/

	/*! \defgroup debug_level	Poziomy informacyjności
		\ingroup debugging
	@{
	*/
	#define	POSNET_DEBUG_NONE				0x00000000  //!< Brak rejestrowania informacji.
	#define POSNET_DEBUG_ALL				0xFFFFFFFF	//!< Rejestracja wszystkich informacji we wszystkich podsystemach
	#define POSNET_SUBSYSTEM_DEVICE			0x00001000	//!< Podsystem urządzenia
	#define POSNET_SUBSYSTEM_DEVICERS232	0x00002000  //!< Podsystem RS232
	#define POSNET_SUBSYSTEM_DEVICEETHER	0x00004000  //!< Podstsystem Ethernet
	#define	POSNET_SUBSYSTEM_DEVICEUSB		0x00008000  //!< Podsystem USB (używa sterownika D2XX, w przypadku korzystania ze
														//!< sterownika VCP należy korzystać z trybu RS232
	#define	POSNET_SUBSYSTEM_FRAME			0x00010000  //!< Podsystem ramki - wyświetla zawartość wysyłanych i odbieranych ramek
														//!< w formacie hexadecymalnym - możliwość konwersji na postać binarną dołączonym konwerterem
	#define POSNET_DEBUG_EXTRA				0x00800000  //!< Rejestracja szczegółowych informacji o stanach rozkazów
	/*!
	@}
	*/

	/*!
		\defgroup	debugging	Ustawienie poziomu śledzenia (informacyjności) biblioteki
		@{
	*/

	/*!
		\brief Ustaw poziom informacyjności biblioteki.

		System debuggingu opiera się na tzw. "podsystemach".\n
		Definicje POSNET_DEBUG_SUBSYSTEM_* definiują te podsystemy.\n
		Są one maskami bitowymi, które zsumowane (OR) daja możliwość 
		jednoczesnego rejestrowania przepływu danych w róznych podsystemach.\n
		4 najmłodsze bity definiują poziom ilości wysyłanych danych (stałe
		POSNET_DEBUG_LEVEL_*).
		
		Ustawienie poziomu debuggingu na wartość różną od 0 powoduje otwarcie
		aktualnie wybranego pliku (domyślnie "POS_DBG.txt", można ustawić przy
		wykorzystaniu \ref POS_SetDebugFileName . W pliku tym zostaną zapisane
		odpowiednie informacje umożliwiające śledzenie wykonania kodu biblioteki.
		Ponowne ustawienie poziomu debuggingu zamyka plik śledzący.
		
		Maksymalna ilość podsystemów określona została na 28.
		\param hGlobalDevice	Uchwyt stworzonego połączenia z urządzeniem
		\param debugLevel	Określenie poziomu śledzenia
	*/
	POSNET_API	void	__stdcall POS_SetDebugLevel(POSNET_HANDLE hGlobalDevice, unsigned long debugLevel);
	/*!
		\brief	Ustawienie nazwy pliku śledzącego.

		Funkcja umożliwia zmianę domyślnego pliku śledzącego.
		\param hGlobalDevice	Uchwyt stworzonego połączenia z urządzeniem
		\param fileName nowa nazwa pliku
	*/
	POSNET_API  void	__stdcall POS_SetDebugFileName(POSNET_HANDLE hGlobalDevice, const char *fileName);

	/*!
		@}
	*/



	/*! 
	*	\addtogroup dev_types Rodzaje interfejsu urządzenia
		\ingroup basic_api

		@{
	*/

	/*!
		\brief	Podłączenie przez RS232
	*/
	#define POSNET_INTERFACE_RS232	0x0001	
	/*!
		\brief	Podłączenie przez USB

		Podłączenie przez  USB może być wykonane na dwa sposoby:
		-  korzystając ze sterownika FTDI VCP (Virtual ComPort), gdzie tworzony jest dodatkowy, virtualny port szeregowy (odpowiednik RS232),
		w tym przypadku należy korzystać z trybu RS232.
		-  przy wykorzystaniu sterownika D2XX, korzysta się z trybu USB. Należy w tym przypadku podać zaprogramowany w interfejsie numer seryjny
		kasy.
		.

	*/
	#define POSNET_INTERFACE_USB	0x0002
	/*!
		\brief	Podłączenie przez Ethernet

		Biblioteka, dla urządzeń sieciowych w systemie Windows nie wywołuje WSA_Startup. Obowiązek inicjalizacji podsystemu
		Winsock spoczywa na aplikacji wykorzystującej bibliotekę. Brak inicjalizacji podsystemu Winsock objawia się błędem w logach
		biblioteki: DEVICE_Ether: Socket Error (1)- 10093. 
	*/
	#define POSNET_INTERFACE_ETH	0x0003
	/*! @}

	*/


	/*!
		\defgroup dev_params	Identyfikatory parametrów urządzenia
		\ingroup basic_api
		@{
	*/
	
	/*!
		\brief	Parametry portu szeregowego

		TYLKO ZAPIS
		
		Parametry portu przekazuje się jako ciąg znaków w formacie
		port,baud rate,bits,parity,stopbits,flowcontrol np. "COM1,9600,8,N,1,H"
		Flowcontrol: (N)one, (S)oftware XON/XOFF, (H)ardware RTS/CTS
	*/
	#define	POSNET_DEV_PARAM_COMSETTINGS	0x00020001

	/*!
		\brief Tryb obsługi ciągów znaków

		TYLKO ZAPIS

		Sposób traktowania ciągów znaków jako wartości zwracanych przez funkcje - 
		dopuszczalne są dwie możliwości:

		  - \ref POSNET_STRINGMODE_PREDEF - aplikacja zna maksymalne długości 
			buforów na podstawie dokumentacji kasy
		  - \ref POSNET_STRINGMODE_INTELLIGENT aplikacja kliencka definiuje swój bufor 
			o długości N i w jego pierwszym znaku przekazuje liczbę określającą 
			długość ciągu. Funkcje zwracające ciągi znaków sprawdzają w tym trybie 
			długość przekazanego ciągu i w przypadku braku miejsca działają następująco: 
			jako status zwracają \ref POSNET_STATUS_BUFFERTOOSHORT i we wszystkich 
			otrzymanych buforach ustawiają wymagane długości. Można też w ten 
			sposób uzyskać informację o wymaganych długościach buforów – wystarczy 
			przekazać bufory z ustawioną długością 0.
		  


	*/
	#define POSNET_DEV_PARAM_STRINGHANDLING		0x00020002

	/*!
		\brief Separator częsci dziesiętnej

		TYLKO ZAPIS

		W obecnej wersji kasy, w związku z nieobsługiwaniem typów danych QUANTITY i CURRENCY
		parametr jest ignorowany.

		Parametr - wskaźnik na 1 znak
	
	*/
	#define POSNET_DEV_PARAM_DECIMALSEPARATOR	0x00020003
	/*!
		\brief Czas w [s] po jakim ma być zaniechane wysyłanie ramki

		TYLKO ZAPIS

		Parametr - wskaźnik na wartośc long
	*/
	#define POSNET_DEV_PARAM_SENDTIMEOUT		0x00020004

	/*!
		\brief Adres IP kasy dla urządzenia typu \ref POSNET_INTERFACE_ETH

		TYLKO ZAPIS

		Parametr - wskaźnik na ciąg znaków języka C (zakończony 0) zawierający adres IP.
	*/
	#define POSNET_DEV_PARAM_IP					0x00020005
	/*!
		\brief Port dla protokołu TCP/IP dla urządzenia typu \ref POSNET_INTERFACE_ETH

		TYLKO ZAPIS

		Parametr - wskaźnik na ciąg znaków języka C (zakończony 0) zawierający numer portu.
	*/
	#define POSNET_DEV_PARAM_IPPORT				0x00020006

	/*!
		\brief Numer seryjny kasy do otwarcia przez typ urządzenia \ref POSNET_INTERFACE_USB
		
		TYLKO ZAPIS

		Parametr - wskaźnik na ciąg znaków języka C (zakończony 0) zawierający numer seryjny.

	*/
	#define POSNET_DEV_PARAM_USBSERIAL			0x00020007

	/*!

		\brief Odczyt wszystkich numerów seryjnych kas podłączonych do komputera poprzez interfejs USB i sterownik
				FTDI - D2XX

		TYLKO ODCZYT

		Parametr - bufor na numery seryjne rozdzielone znakiem końca linii - 
					(każdy numer ma max. 8znaków+2 bajty - koniec linii = 10 bajtów * max. 127 urządzeń na USB = 1270)
					w związku z tym zalecany jest rozmiar bufora większy lub równy 1271 znaków.

	*/

	#define POSNET_DEV_PARAM_LISTUSBSERIALS		0x00020008

	/*!

	\brief Długość kolejki wysyłkowej, po przekroczeniu, której rozkazy traktowane są jak wysyłane w trybie natychmiastowym.

	TYLKO ZAPIS

	Parametr - wskaźnik na liczbę typu unsigned long (32 bit) zawierającą żądaną długość kolejki wysyłkowej.

	*/

	#define POSNET_DEV_PARAM_OUTQUEUELENGTH		0x00020009

	/*

	\brief Sterowanie auto synchronizacją poleceń złożonych. Kontroluje automatyczne oczekiwanie na zakończenie
			poleceń złożonych. Domyślnie biblioteka samodzielnie odczytuje status poleceń złożonych i oczekuje na ich zakończenie.
			Jeśli program samodzielnie chce weryfikować ich przebieg, należy ten mechanizm wyłączyć.

	TYLKO ZAPIS

	Parametr - wskaźnik na wartość typu unsigned char. 0 - synchronizuj, inna wartość nie synchronizuj
	*/

	#define POSNET_DEV_PARAM_NOSYNC				0x0002000A

	/*

	\brief	Włączenie/Wyłączenie trybu modemowego urzadzenia typu RS232. Współpraca z modemem ma następujące
		wymagania: 1. modem musi byc podłączony pełnym kablem RS232 i musi poprawnie obsługiwać sygnały DCD (Data Carrier Detect)
		dla detekcji aktywnego połączenia, oraz DTR (Data Termina Ready)- w celu poprawnego rozłączania połączeń telefonicznych.
		UWAGA 1: Połączenia modemowe NIE są automatycznie nawiązywane i ponawiane w przypadku zerwania - to zadanie należy
		do aplikacji korzystającej z biblioteki (ponowne dzwonienie nie wymaga zamknięcia i otwarcia urządzenia) - to podejście
		ma na celu przekazanie kontroli nad generującymi koszty połączeniami telefonicznymi na wyższy poziom (do aplikacji
		zarządzającej kasami).
		UWAGA 2: Tryb modemowy wymusza sprzętowy handshake bez względu na ustawienia ciągu inicjującego parametry portu RS232

	ZAPIS I ODCZYT

	Parametr: wskaźnik na wartość typu unsigned char. 0 - tryb wyłączony, 1 - tryb włączony
	*/
	#define POSNET_DEV_PARAM_MODEMMODE				0x0002000B

	/*!
		\brief Ciąg inicjujący modem (wraz z początkowym AT)
		
		TYLKO ZAPIS

		Parametr - wskaźnik na ciąg znaków języka C (zakończony 0).

	*/
	#define POSNET_DEV_PARAM_MODEMINIT				0x0002000C

	/*!
		\brief Ciąg dzwonienia z numerem telefonicznym (wraz z początkowym ATD)- numer podany bez przedrostka trybu wybierania P (impulsowe) lub T (tonowe) zostanie wybrany 
		w trybie zależnym od aktualnie zaprogramowanego w modemie, lub ustawionego ciągiem inicjującym. (por. komendy AT modemowe
		polecenie ATD ).
		
		TYLKO ZAPIS

		Parametr - wskaźnik na ciąg znaków języka C (zakończony 0).

	*/
	#define POSNET_DEV_PARAM_MODEMDIAL				0x0002000D


	/*!
		@}
	*/

	/*!
		\defgroup	string_handling Tryby obsługi buforów znakowych w API wysokiego poziomu
		\ingroup dev_params

		\sa POSNET_DEV_PARAM_STRINGHANDLING
		@{
	*/
	#define POSNET_STRINGMODE_PREDEF 0x00
	#define POSNET_STRINGMODE_INTELLIGENT 0x01


	/*!
		@}
	*/


	/*!
		\defgroup	basic_api	Obsługa podstawowa urządzenia
		@{
	*/

	/*!
		\brief	Utworzenie uchwytu do nowego urządzenia kasowego. 
		
		Tworzy odpowiedni obiekt i ustawia
		niebędne jego właściwości, ale fizycznie go nie otwiera. Przed otwarciem urządzenia 
		należy ustawić niebędne parametry, które są rózne w zależności od typu urządzenia.
		\param	deviceType	Typ podłączonego urządzenia \ref dev_types "Typy podłączenia"
		\return Uchwyt globalny utworzonego urządzenia. Wartośc NULL zostanie zwrócona wyłącznie
				w przypadku braku pamięci lub podania błędnego typu urządzenia.
	*/
	POSNET_API POSNET_HANDLE	__stdcall POS_CreateDeviceHandle(unsigned long deviceType);

	/*!
		\brief	Otwórz urządzenie.
		
		\param hGlobalDevice	Uchwyt globalny urzadzenia do otwarcia.
		\return Zwraca uchwyt lokalny do urządzenia w kontekście bieżącego wątku. NULL w przypadku błędu,
				kod błędu można odczytać funkcją POS_GetError
	*/
	POSNET_API POSNET_HANDLE	__stdcall POS_OpenDevice(POSNET_HANDLE hGlobalDevice);		  
	/*!
		\brief	Zamknij urządzenie. 
		
		Zamyka urzadzenie wskazywane przez uchwyt. Usuwa zawartości kolejek
		komunikacyjnych. Wszytskie dane należy odczytać przed zamknięciem urządzenia.

		\param hLocalDevice	Uchwyt urzadzenia do zamknięcia.
	*/
	POSNET_API POSNET_STATUS	__stdcall POS_CloseDevice(POSNET_HANDLE hLocalDevice);
	/*!
		\brief	Usuń istniejący uchwyt urządzenia i zwolnij zajmowaną pamięć.

		Ostatecznie usuwa obiekt komunikacyjny i zwalnia pamięć.

		\param hGlobalDevice	Uchwyt globalny urządzenia do usunięcia. Wszystkie wątki muszą najpierw zamknąć urzadzenie,
								w przeciwnym wypadku funkcja zwróci błąd POSNET_STATUS_BUSY.
	*/
	POSNET_API POSNET_STATUS	__stdcall POS_DestroyDeviceHandle(POSNET_HANDLE hGlobalDevice); 
	/*!
		\brief	Funkcja do ustawiania parametrów urządzenia

		\param hDevice Uchwyt urządzenia - zarówno lokalny jak i globalny
		\param paramCode Kod parametru por. \ref dev_params kody parametrów
		\param paramValue Wskaźnik lub wartość parametru. Opis przy parametrach urządzenia.

	*/
	POSNET_API POSNET_STATUS	__stdcall POS_SetDeviceParam(POSNET_HANDLE hDevice, unsigned long paramCode,void *paramValue);	
	/*!
		\brief	Funkcja do pobierania parametrów urządzenia

		\param hDevice Uchwyt urządzenia - zarówno lokalny jak i globalny
		\param paramCode Kod parametru por. \ref dev_params kody parametrów
		\param paramValue Wskaźnik lub wartość parametru. Opis przy parametrach urządzenia.

	*/
	POSNET_API POSNET_STATUS	__stdcall POS_GetDeviceParam(POSNET_HANDLE hDevice, unsigned long paramCode,void *paramValue);	


	/*!
		\brief	Funkcja słuąy do nawiązania połączenia modemowego. Procedura rozpoczyna proces nawiązywania połączenia
		modemowego.

		\param hGlobalDevice Uchwyt globalny urzadzenia typu RS232
		\param wait	Flaga oczekiwania na wykonanie polecenia - 0 - nie oczekuj, 1 - oczekuj, ponieważ czas wykonania połączenia modemowego
		może osiągać nawet ponad minutę dla aplikacji współpracującej z biblioteką wskazane może być samodzielne sprawdzenie statusu
		dzwonienia funkcją POS_ModemStatus

		\return Status wykonania polecenia
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_ModemDial(POSNET_HANDLE hGlobalDevice,int wait);

	/*!
		\brief	Funkcja słuzy do rozłączenia połączenia modemowego. Procedura rozpoczyna proces zamykania połączenia
		modemowego.

		\param hGlobalDevice Uchwyt globalny urzadzenia typu RS232
		\param wait	Flaga oczekiwania na wykonanie polecenia - 0 - nie oczekuj, 1 - oczekuj, chociaż czas rozłączenia połączenia modemowego
		jest dość krótki to dla spółności ze sposobem obsługi połączenia dostepne są oba tryby pracy

		\return Status wykonania polecenia
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_ModemDisconnect(POSNET_HANDLE hGlobalDevice,int wait);

	/*!
		\brief	Funkcja słuzy do sprawdzenia stanu połączenia modemowego. 

		\param hGlobalDevice Uchwyt globalny urzadzenia typu RS232

		\return Status połączenia modemowego POSNET_STATUS_MODEM_xxx
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_ModemStatus(POSNET_HANDLE hGlobalDevice);

	/*!
		\brief Funkcja umożliwia zapis ciągu znaków bezpośrednio do portu szeregowego (modemu), do wykorzystania
		wyłącznie w trybie włączonego modemu

		\param hGlobalDevice Uchwyt globalny urzadzenia typu RS232
		\param buffer Ciąg znaków do wysłania do modemu

		\return Status wykonania rozkazu
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_ModemWrite(POSNET_HANDLE hGlobalDevice,const char *buffer);

	/*!
		@}
	*/

	/*! \defgroup error_codes	Kody błędów biblioteki
		\ingroup	error_handling

		\brief	Kody błędów biblioteki. Biblioteka może zwracać kody
				błędów zarówno własne jak i kody bezpośrednio uzyskane
				z kasy.
		@{
	*/
	
	#define POSNET_STATUS_OK						0x00000000 //!< Brak błędu
	#define POSNET_STATUS_OUTOFMEMORY				0x00000001 //!< Brak pamięci
	#define POSNET_STATUS_FRAMETOOSHORT				0x00000002 //!< Za krótka ramka
	#define POSNET_STATUS_FRAMINGERROR				0x00000003 //!< Błąd ramki odebranej z kasy
	#define POSNET_STATUS_COULDNOTOPEN				0x00000005 //!< Nie można otworzyc wskazanego urządzenia
	#define POSNET_STATUS_CRCERROR					0x00000006 //!< Błąd CRC w odebranej ramce
	#define POSNET_STATUS_IPCERROR					0x00000007 //!< Błąd utworzenia obiektu IPC (Event)
	#define POSNET_STATUS_COMMERROR					0x00000008 //!< Błąd komunikacji
	#define POSNET_STATUS_USBERROR					0x00000009 //!< Błąd krytyczny USB - urządzenie nie będzie funkcjonować poprawnie
	#define POSNET_STATUS_FTLIBIMPORTFAIL			0x0000000A //!< Nieudany import sterownika FTDI
	#define POSNET_STATUS_COULDNOTSETUPPORT			0x0000000B //!< Błąd ustawienia parametrów otwieranego portu
	#define POSNET_STATUS_COULDNOTOPEN_ACCESSDENIED 0x0000000C //!< Błąd otwarcia urządzenia - dostęp zabroniony
	#define POSNET_STATUS_COULDNOTOPEN_FILENOTFOUND 0x0000000D //!< Błąd otwarcia urządzenia - brak takiego pliku (urządzenia)
	#define POSNET_STATUS_SETUP_INVALIDBAUD			0x0000000E //!< Błędne parametry portu - baudrate
	#define POSNET_STATUS_SETUP_INVALIDDATA			0x0000000F //!< Błędne parametry portu - databits
	#define POSNET_STATUS_SETUP_INVALIDPARITY		0x00000010 //!< Błędne parametry portu - parity
	#define POSNET_STATUS_SETUP_INVALIDSTOP			0x00000011 //!< Błędne parametry portu - stop bits
	#define POSNET_STATUS_SETUP_INVALIDHANDSHAKE	0x00000012 //!< Błędne parametry portu - handshake
	#define POSNET_STATUS_INVALIDSTATE				0x00000013 //!< Wydano polecenie REPEAT dla ramki znajdującej się w niewłaściwym stanie (innym niż SENT lub ACK)
	#define POSNET_STATUS_DEVICE_BUSY				0x00000014 //!< Urządzenie zajęte

	#define	POSNET_STATUS_BUSY					0x00000020 //!< Urządzenie zajęte
	#define	POSNET_STATUS_BUSY_LEVER			0x00000021 //!< Urządzenie zajęte - podniesiona dźwignia
	#define	POSNET_STATUS_BUSY_MECHANISM		0x00000022 //!< Urządzenie zajęte - błąd mechanizmu
	#define	POSNET_STATUS_BUSY_COVER			0x00000023 //!< Urządzenie zajęte - podniesiona pokrywa
	#define	POSNET_STATUS_BUSY_PAPER			0x00000024 //!< Urządzenie zajęte - brak papieru
	#define	POSNET_STATUS_BUSY_TEMP				0x00000025 //!< Urządzenie zajęte - zbyt wysoka temperatura
	#define	POSNET_STATUS_BUSY_POWER			0x00000026 //!< Urządzenie zajęte - chwilowy zanik zasilania
	#define	POSNET_STATUS_BUSY_CUTTER			0x00000027 //!< Urządzenie zajęte - błąd obcinacza

	#define POSNET_STATUS_ALREADY_COMPLETED		0x00010000 //!< Rozkaz już wykonany \sa POS_CancelRequest
	#define POSNET_STATUS_EMPTY					0x00010001 //!< Brak danych w kolejce
	#define	POSNET_STATUS_INVALIDVALUE			0x00010002 //!< Błędna wartość
	#define	POSNET_STATUS_TIMEOUT				0x00010003 //!< Oczekiwanie zakończone upłynięciem czasu (timeout)
	#define	POSNET_STATUS_PENDING				0x00010004 //!< Polecenie w trakcie wykonywania
	#define POSNET_STATUS_INVALIDCOMMAND		0x00010005 //!< Błędny numer polecenia
	#define POSNET_STATUS_INVALIDHANDLE			0x00010006 //!< Błędny uchwyt
	#define POSNET_STATUS_BUFFERTOOSHORT		0x00010007 //!< Przekazany bufor znakowy jest za mały
	#define POSNET_STATUS_OUTOFRANGE			0x00010008 //!< Poza zakresem licznika
	#define POSNET_STATUS_INVALIDSPOOLMODE		0x00010009 //!< Błędny tryb kolejkowania
	#define POSNET_STATUS_CANCELLED				0x0001000A //!< Rozkaz anulowany

	#define POSNET_STATUS_COULDNOTOPEN_WSAEINTR  		0x00000030 //!< Błąd sieciowy - przerwane wywołanie systemowe
	#define POSNET_STATUS_COULDNOTOPEN_WSAEACCES 		0x00000031 //!< Błąd sieciowy - brak dostępu
	#define POSNET_STATUS_COULDNOTOPEN_WSAEINPROGRESS 	0x00000032 //!< Błąd sieciowy - operacja w toku
	#define POSNET_STATUS_COULDNOTOPEN_WSAEDESTADDRREQ  0x00000033 //!< Błąd sieciowy - wymagany adres docelowy
	#define POSNET_STATUS_COULDNOTOPEN_WSAEADDRINUSE 	0x00000034 //!< Błąd sieciowy - adres w użyciu
	#define POSNET_STATUS_COULDNOTOPEN_WSAEADDRNOTAVAIL	0x00000035 //!< Błąd sieciowy - adres nieprawidłowy
	#define POSNET_STATUS_COULDNOTOPEN_WSAENETDOWN 		0x00000036 //!< Błąd sieciowy - sieć jest wyłączona
	#define POSNET_STATUS_COULDNOTOPEN_WSAENETUNREACH 	0x00000037 //!< Błąd sieciowy - sieć jest nieosiągalna
	#define POSNET_STATUS_COULDNOTOPEN_WSAENETRESET 	0x00000038 //!< Błąd sieciowy - sieć rozłączyła połączenie
	#define POSNET_STATUS_COULDNOTOPEN_WSAECONNABORTED  0x00000039 //!< Błąd sieciowy - połączenie zerwane przez aplikację
	#define POSNET_STATUS_COULDNOTOPEN_WSAECONNRESET 	0x0000003A //!< Błąd sieciowy - strona zdalna zerwała połączenie
	#define POSNET_STATUS_COULDNOTOPEN_WSAETIMEDOUT 	0x0000003B //!< Błąd sieciowy - upłynął czas oczekiwania na odpowiedź
	#define POSNET_STATUS_COULDNOTOPEN_WSAECONNREFUSED 	0x0000003c //!< Błąd sieciowy - połączenie odrzucone
	#define POSNET_STATUS_COULDNOTOPEN_WSAEHOSTDOWN  	0x0000003d //!< Błąd sieciowy - serwer zdalny jest wyłączony
	#define POSNET_STATUS_COULDNOTOPEN_WSAEHOSTUNREACH 	0x0000003e //!< Błąd sieciowy - serwer zdalny jest nieosiągalny
	#define POSNET_STATUS_COULDNOTOPEN_WSAHOSTNOTFOUND 	0x0000003f //!< Błąd sieciowy - serwer nieznaleziony
	#define POSNET_STATUS_COULDNOTOPEN_WSATRYAGAIN  	0x00000040 //!< Błąd sieciowy - serwer nieznaleziony, spróbuj ponownie

	#define POSNET_STATUS_MODEM_NOTSUPPORTED		0x00000060	//!< Modem nie obsługiwany - urządzenie nie jest RS232 lub ma nie aktywny tryb modemowy
	#define POSNET_STATUS_MODEM_ONHOOK				0x00000061	//!< Status modemu - na widełkach (rozłączony)
	#define POSNET_STATUS_MODEM_DIALING				0x00000062  //!< Status modemu - w trakcie nawiązywania połączenia
	#define POSNET_STATUS_MODEM_DISCONNECTING		0x00000063  //!< Status modemu - w trakcie rozłączania
	#define POSNET_STATUS_MODEM_CONNECTED			0x00000064  //!< Status modemu - połączony
	#define POSNET_STATUS_MODEM_ANSWERING			0x00000065	//!< Status modemu - trwa odbieranie połączenia
	#define	POSNET_STATUS_MODEM_BUSY				0x00000066  //!< Próba wykonania połączenia przy zajetym modemie
	#define POSNET_STATUS_MODEM_NOTCONNECTED		0x00000067  //!< Próba rozłączenia nie połączonego modemu
	#define	POSNET_STATUS_MODEM_NODIALTONE			0x00000068	//!< Status połączenia - brak tonu centrali
	#define POSNET_STATUS_MODEM_NOCARRIER			0x00000069  //!< Status połączenia - nie powiodło się
	#define POSNET_STATUS_MODEM_OTHERERROR			0x0000006A	//!< Status połączenia - inny błąd
	#define POSNET_STATUS_MODEM_BADINIT				0x0000006B	//!< Status połączenia - modem nie zaakceptował ciagu inicjującego
	#define POSNET_STATUS_MODEM_BADDIAL				0x0000006C	//!< Status połączenia - modem nie zaakceptował komendy połączenia
	#define POSNET_STATUS_MODEM_NOMODEM				0x0000006D  //!< Status połączenia - brak odpowiedzi modemu na polecenia AT
	#define POSNET_STATUS_MODEM_CONNECTIONLOST		0x0000006E	//!< Status połączenia - przerwane
	#define POSNET_STATUS_MODEM_ERRORONDISCONNECT	0x0000006F	//!< Status połączenia - nie udało się rozłączyć połączenia (modem nie odpowiada)
	

	#define POSNET_STATUS_INVALID_PARAM1		0x00010101 //!< Błędny 1 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM2		0x00010102 //!< Błędny 2 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM3		0x00010103 //!< Błędny 3 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM4		0x00010104 //!< Błędny 4 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM5		0x00010105 //!< Błędny 5 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM6		0x00010106 //!< Błędny 6 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM7		0x00010107 //!< Błędny 7 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM8		0x00010108 //!< Błędny 8 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM9		0x00010109 //!< Błędny 9 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM10		0x0001010A //!< Błędny 10 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM11		0x0001010B //!< Błędny 11 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM12		0x0001010C //!< Błędny 12 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM13		0x0001010D //!< Błędny 13 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM14		0x0001010E //!< Błędny 14 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM15		0x0001010F //!< Błędny 15 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM16		0x00010110 //!< Błędny 16 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM17		0x00010111 //!< Błędny 17 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM18		0x00010112 //!< Błędny 18 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM19		0x00010113 //!< Błędny 19 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM20		0x00010114 //!< Błędny 20 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM21		0x00010115 //!< Błędny 21 parametr polecenia
	#define POSNET_STATUS_INVALID_PARAM22		0x00010116 //!< Błędny 22 parametr polecenia

	#define	POSNET_STATUS_CASHREGBASE			0x00430000 //!< Bazowy kod błędu wykonania rozkazu kasy [błędy 0x00430000 - 0x0043FFFF]
	#define	POSNET_STATUS_CASHREGCOMMBASE		0x00440000 //!< Bazowy kod błędu transmisji rozkazu do kasy [błędy 0x00440000 - 0x0044FFFF]
	/*!
		@}
	*/


	/*!
		\defgroup	error_handling	Obsługa błędów
		@{
	*/

	/*!
		\brief	Podaj kod statusu związany z uchwytem urządzenia
		
		Zwraca ostatnio ustawiony kod statusu związany z uchwytem urządzenia. 
		Każda wywoływana funkcja oprócz zwrócenia tej wartości jako wyniku działania
		(o ile nie zwraca innego rodzaju rezultatu)	ustawia wewnętrzny znacznik błędu. 
		\param hLocalDevice Uchwyt lokalny urządzenia lub uchwyt globalny urządzenia.
		\return Kod statusu patrz \ref error_codes Kody błędów.
	*/
	POSNET_API POSNET_STATUS	__stdcall POS_GetError(POSNET_HANDLE hLocalDevice);	
	/*!
		\brief	Zwróć tekstowy opis błędu

		Funkcja zwraca tekstowy opis błędu zrozumiały dla użytkownika / programisty.
		Komunikat może być zwrócony we wskazanym języku (o ile przygotowano
		niezbędny plik językowy). W przeciwnym wypadku komunikat zwracany jest
		w domyślnym języku biblioteki. 

		<em>UWAGA:</em> W systemie Linux pliki z tekstowymi opisami kodów błędów (pliki językowe
		o nazwach w postaci posnet_xx.lng mogą być umieszczone w katalogu, z którego
		uruchomiono program (nie zalecane) lub w miejscu wskazywanym przez zmienną
		środowiskową POSNET_LIB_SHARE_DIR (zalecane).
		W systemie WINDOWS katalog wskazany w POSNET_LIB_SHARE_DIR musi być zakończony 
		znakiem „\” rozdzielającym katalogi np. POSNET_LIB_SHARE_DIR=c:\myapp\bin\

		\param code	Kod błędu do wyjaśnienia
		\param lang	2 znakowy kod języka wg ISO-3166
		\return Ciąg znaków opisujących zdarzenia (C-string) zakoczńony znakiem 0. Ciąg ten zwracany
				jest z wewnętrznego bufora. Nie wolno go zwalniać funkcjami allokacji pamięci.
	*/
	POSNET_API const char *			__stdcall POS_GetErrorString(POSNET_STATUS code, char *lang);
	/*!
		\brief	Zwróć status rozkazu

		\return Funkcja zwraca kod błędu związany z rozkazem. W przypadku odebrania odpowiedzi o błędzie 
				wykonania rozkazu zwracane są kody odebrane od kasy, są one także dostępne w polach rezultatu
				komendy w postaci zgodnej z Instrukcją Programisty.
				Kody o wartościach 0x00000000-0x0042FFFF służą do przekazywania stanu rozkazu w ramach biblioteki.
				Kody o wartościach 0x00430000-0x0043FFFF wykorzystywane są w przypadku negatywnej odpowiedzi kasy na rozkaz, po jego zakończeniu w wyniku błędu kasy – kod błędu kasy zwiększony jest o wartość 0x00430000.
				Kody o wartościach 0x00440000-0x0044FFFF wykorzystywane są w przypadku negatywnej odpowiedzi kasy na rozkaz, po jego zakończeniu w wyniku błędu transmisji – kod błędu transmisji zwiększony jest o wartość 0x00440000.
		\sa sync_api "Obsługa synchroniczna kasy"
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_GetRequestStatus(POSNET_HANDLE hRequest);
	/*!
		@}
	*/



	// --------------------------------------------------------------------------------------------------------
	/*! \defgroup event_types Typy zdarzeń
		\ingroup	event_handling
		@{
	*/
	/*!
		\brief	Wyłączenie obsługi zdarzeń asynchronicznych - w tym trybie
		wszystkie zdarzenia są automatycznie usuwane, a aplikacja nie jest
		o nich informowana.
	*/
	#define POSNET_EVENT_DISABLE	0x0000
#ifdef _WIN32
	/*!
		\brief	Sygnalizacja otrzymania zdarzenia za pomocą komunikacji międzyprocesowej
		typu "Event" (zdarzenie) w systemie Windows.
		Po wybraniu tego typu obsługi za pomocą funkcji \ref POS_GetEvent można
		uzyskać uchwyt zdarzenia zarezerwowanego przez urządzenie. 

		Tylko dla WIN32
	*/
	#define POSNET_EVENT_EVENT		0x0001
	/*!
		\brief	Sygnalizacja otrzymania zdarzenia za pomocą komunikatów systemu Windows.
		Po wybraniu tego trybu należy za pomocą funkcji \ref POS_SetMessageParams
		ustawić kod komunikatu i uchwyt okna do którego ma on być wysłany. Wysyłany
		komunikat ma jako lParam umieszczony uchwyt urządzenia, które go wygenerowało.

		Tylko dla WIN32
	*/
	#define	POSNET_EVENT_MESSAGE	0x0002
#else
	/*!
		\brief Sygnalizacja otzrymania zdarzenia za pomoca semafora pthread

		Tylko dla Linux
	*/	
	#define POSNET_EVENT_SEMAPHORE	0x0005

#endif
	/*!
		\brief	Tryb obsługi poprzez odpytywanie. System gromadzi otrzymywane zdarzenia
		asynchroniczne i oczekuje, że aplikacja będzie w sposób regularny sprawdzać, 
		czy jest zdarzenie oczekujące. 

		\warning Kolejka komunikatów ma ograniczoną długość. Istnieje możliwość ustawienia 
		ilości zapamiętywanych komunikatów za pomocą funkcji \ref POS_SetDeviceParam .
	*/
	#define POSNET_EVENT_POLLING	0x0003

	/*!
		\brief	Tryb obsługi poprzez wywołanie funkcji w momencie otrzymania
		pakietu danych asynchronicznych.
	*/
	#define POSNET_EVENT_CALLBACK	0x0004
	/*! 
		@}
	*/

	/*!
		\defgroup	event_handling	Obsługa zdarzeń asynchronicznych
		@{
	*/


	/*!
		\brief Ustaw metodę obsługi zdarzeń asynchronicznych

		Kasa ma możliwość generacji zdarzeń asynchronicznych, które muszą być przesłane do aplikacji. 
		Przykładowym zdarzeniem jest obsługa karty rabatowej w trakcie sprzedaży. 
		Tego typu zdarzenia można przesłać do aplikacji w następujący sposób:
		- za pomocą IPC typu "Event"
		- za pomocą komunikatów systemu Windows (Windows Messages)
		- za pomocą systemu pollingu, gdzie aplikacja odpytuje bufor zdarzeń asynchronicznych
		
		Funkcja służy to ustawienia trybu sygnalizacji zdarzeń.
		\param hLocalDevice	Uchwyt lokalny urządzenia. Funkcja pomimo pobierania uchwytu lokalnego ma zasięg
				globalny dla urządzenia.
		\param eventMode Typ sygnalizacji zdarzeń definiowany przez \ref event_types "Typy zdarzeń"
		\return Status wykonania funkcji (POSNET_STATUS_OK w przypadku sukcesu)
	*/
	POSNET_API POSNET_STATUS	__stdcall POS_SetEventHandlingMode(POSNET_HANDLE hLocalDevice, unsigned long eventMode);
#ifdef _WIN32
	/*!
		\brief	Funkcja ustawia kod komunikatu i uchwyt okna do którego ma być on wysłany
				przy obsłudze zdarzeń asynchronicznych. Tylko dla Windows.
		\param hLocalDevice	Uchwyt lokalny urządzenia. Funkcja pomimo pobierania uchwytu lokalnego ma zasięg
				globalny dla urządzenia.
		\param	messageCode	Kod komunikatu (WM_xxxx)
		\param	hWnd	Uchwyt okna

		Tylko dla WIN32
	*/
	POSNET_API POSNET_STATUS	__stdcall POS_SetMessageParams(POSNET_HANDLE hLocalDevice, UINT messageCode, HANDLE hWnd);
	/*!
		\brief	Funkcja zwraca uchwyt do zdarzenia. Obiekt zdarzenia jest zarządzany przez
				bibliotekę. Zdarzenie pracuje w trybie Manual Reset 
				patrz \sa http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/createevent.asp MSDN.
		\param hLocalDevice	Uchwyt lokalny urządzenia. Funkcja pomimo pobierania uchwytu lokalnego ma zasięg
				globalny dla urządzenia.
		\return	NULL w przypadku błędu, w przeciwnym przypadku uchwyt zdarzenia (Event).

		Tylko dla WIN32
	*/
	POSNET_API HANDLE			__stdcall POS_GetEvent(POSNET_HANDLE hLocalDevice);
#else
	/*!
		\brief Pobranie semafora synchronizującego wątki pthread (typ sem_t)
		\param hLocalDevice Uchwyt lokalny urządzenia. Funkcja pomimo pobierania uchwytu lokalnego ma zasięg
				globalny dla urządzenia.
		\return NULL w przypadku błędu, w przeciwnym wypadku wskaźnik na semafor.

		Tylko dla Linux
	*/
	POSNET_API void * __stdcall POS_GetSemaphore(POSNET_HANDLE hLocalDevice);

#endif
	/*!
		\brief Typ definiujący funkcję callback dla zdarzeń asynchronicznych. Przyjmuje jeden parametr
		- uchwyt do odebranych danych (hRequest). Funkcja MUSI usunąć orzymany obiekt wyniku.
	*/
	typedef void (POSNET_CALLBACK_T)(POSNET_HANDLE handle);

	/*!
		\brief Funkcja ustawia w bibliotece funkcję callback, która będzie wywoływana po otrzymaniu zdarzenia asynchronicznego.
		\param hLocalDevice Uchwyt lokalny urządzenia. Funkcja pomimo pobierania uchwytu lokalnego ma zasięg
				globalny dla urządzenia.
		\param callback wskaźnik na funkcję typu callback.
	*/
	POSNET_API POSNET_STATUS	__stdcall POS_SetCallback(POSNET_HANDLE hLocalDevice, POSNET_CALLBACK_T *callback);

	/*!
		@}
	*/
	// --------------------------------------------------------------------------------------------------------


	/* MAIN COMMAND API */

	/*!
		\defgroup	req_modes	Tryby wysyłania rozkazów
		\ingroup sync_api
		@{
	*/

	#define	POSNET_REQMODE_SPOOL	0x00 //!< Tryb kolejkowania [domyślny], w tym trybie rozkaz umieszczany jest na 
										 //!< końcu kolejki rozkazów do wysłania, za wyjątkiem następujących komend,
										 //!< które ze swej natury umieszczane są na samym początku kolejki:
										 //!< MANUALDISCNTPCSET, DBDISCNTPCSET, WAITSTATUSGET, SEQSTATUSGET, CMPLXSEQSTOP
	#define POSNET_REQMODE_IMMEDIATE 0x01 //!< Tryb bezpośredni. Podobny do \ref POSNET_REQMODE_SPOOL kolejkowania, lecz
										  //!< w przypadku, gdy w kolejce są już jakieś rozkazy zwraca błąd.
	#define	POSNET_REQMODE_SPOOLSPECIAL	0x02 //!< Tryb kolejkowania specjalnego, w którym
											 //!< w kolejce odbiorczej odpowiedź OK (brak błędu)
											 //!< na rozkaz nie zwracający wyniku zostanie automatycznie
											 //!< usunięta z kolejki odbiorczej. Ten tryb musi być używany 
											 //!< jedynie w trybie odbioru z kolejki odbiorczej (nie wolno
											 //!< stosować \ref POS_WaitForRequestCompleted POS_WaitForRequestCompleted, gdyż
											 //!< nie ma gwarancji poprawności uchwytu urządzenia.
	#define POSNET_REQMODE_AUTOCLEAR 0x03 //!< Ten tryb powoduje automatyczne czyszczenie odpowiedzi,
										  //!< bez względu na kod powrotu. W momencie wysłania rozkazu w tym trybie należy uznać,
										  //!< że uchwyt rozkazu jest błędny.

	/*!
		@}
	*/
	
	/*!
		\defgroup	req_states	Stany rozkazu
		\ingroup sync_api
		@{
	*/

	#define POSNET_RSTATE_NEW			0x00019000	//!< Nowe polecenie, nie umieszczone w kolejce
	#define POSNET_RSTATE_PENDING		0x00019001	//!< Nowe polecenie, umieszczone w kolejce
	#define POSNET_RSTATE_SENT			0x00019002	//!< Polecenie wysłane, nie potwierdzone
	#define POSNET_RSTATE_ACK			0x00019003	//!< Polecenie wysłane, złożone, potwierdzone
	#define	POSNET_RSTATE_COMPLETED		0x00019004	//!< Wykonanie rozkazu zakończone
	#define	POSNET_RSTATE_ERRCOMPLETED	0x00019005	//!< Wykonanie rozkazu zakończone błędem
	/*!
		@}
	*/


	// --------------------------------------------------------------------------------------------------------


	/*!
		\defgroup	request_base	Obsługa obiektów rozkazowych
		\ingroup sync_api

		@{
	*/

	/*!
		\brief	Funkcja tworzy nowy obiekt rozkazowy dla kasy.

		Funkcja tworzy obiekt rozkazowy dla kasy. Obiekt tego typu jest podstawową
		komórką transmisyjną pomiędzy aplikacją a kasą. Jego zadaniem jest realizacja
		pojedynczej transakcji kasa-aplikacja.

		Więcej informacji we wprowadzeniu - \ref sec_flow "Przepływ informacji" 

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param	command	Identyfikator rozkazu dla kasy
		\return	Zwracany jest uchwyt do nowego obiektu rozkazowego lub NULL w przypadku błędu
	*/
	POSNET_API	POSNET_HANDLE	 __stdcall POS_CreateRequest(POSNET_HANDLE hLocalDevice, POSNET_CMD	command);
	/*!
		\brief Funkcja służy do pobrania uchwytu urządzenia związanego z rozkazem

		\param hRequest	Uchwyt rozkazu
		\return uchwyt lokalny urządzenia lub NULL w przypadku błędu lub dla rozkazów odesłanych przez kasę (karta rabatowa),
				gdyż nie można ustalić adresata rozkazu.
	*/
	POSNET_API POSNET_HANDLE	__stdcall POS_RequestDevice(POSNET_HANDLE hRequest);

	/*!
		\brief	Fukcja umieszcza obiekt rozkazowy w kolejce rozkazów do wykonania.

		Istnieją dwa warianty wysyłania rozkazów 
		  - tryb kolejkowania,
		  - tryb bezpośredni.
		
		W trybie kolejkowania nowy rozkaz jest umieszczany w kolejce do wysłania do kasy i
		automatycznie wysyłany w miarę zwalniania się bufora kasy. 
		\warning Długośc kolejki jest ograniczona. Po jej przekroczeniu rozkazy traktowane są 
				 jakby były wysyłane w trybie bezpośrednim.
	   
	    Tryb bezpośredni kontroluje, czy kasa jest wolna i dopiero gdy jest wolna umożliwia
		umieszczenie rozkazu w buforze. W ten sposób w danej chwili do kasy wysłany jest 
		co najwyżej 1 rozkaz.

		\param	hRequest	Uchwyt rozkazu
		\param	mode		Wybór trybu wysyłania rozkazu \ref req_modes "Tryby wysyłania rozkazów"
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PostRequest(POSNET_HANDLE hRequest,unsigned char mode);
	/*!
		\brief	Anulowanie obiektu rozkazowego

		Funkcja anuluje wykonanie rozkazu. W zależności od stanu rozkazu może to oznaczać:
		  - jeśli rozkaz nie został jeszcze wysłany zostaje on usunięty z kolejki rozkazów,
		  - jeśli rozkaz został wysłany do kasy i jest to rozkaz złożony, który został potwierdzony
		    to następuje próba anulowania poprzez komendę CMPLSEQSTOP, po sukcesie anulowania
			zostaje on usunięty z kolejki rozkazów,
		  - jeśli rozkaz był już wykonany to nic nie jest wykonywane i zostaje zwrócony
			kod błędu \ref POSNET_STATUS_ALREADY_COMPLETED .

		W każdym przypadku za zniszczenie obiektu odpowiada aplikacja - należy dla anulowanego rozkazu
		wywołać \ref POS_DestroyRequest .

		\param hRequest	Uchwyt rozkazu
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_CancelRequest(POSNET_HANDLE hRequest);
	/*!
		\brief	Zniszczenie obiektu rozkazowego i zwolnienie zajmowanej przezeń pamięci.

		Funkcja kasuje obiekt rozkazowy oraz wszystkie powiązane z nim dane.
		Musi być użyta dla każdego rozkazu allokowanego poprzez \ref POS_CreateRequest POS_CreateRequest 
		który nie jest automatycznie usuwany w ytybach SPOOLSPECIAL i AUTOCLEAR.

		\param hRequest	Uchwyt rozkazu
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_DestroyRequest(POSNET_HANDLE hRequest);

	/*!
		\brief	Wiek rozkazu - czas jaki upłynął od wywołania \ref POS_PostRequest

		Funkcja ta ma na celu ustalenie wieku rozkazu i może być przydatna w obsłudze
		sytuacji nadzwyczajnych. Czas podawany jest w milisekundach.

		\param hRequest	Uchwyt rozkazu
	*/
	POSNET_API	unsigned long	__stdcall POS_GetRequestAge(POSNET_HANDLE hRequest);
	/*!
		\brief	Pobierz numer polecenia, który został użyty przy tworzeniu obiektu

		\param hRequest	Uchwyt rozkazu
		\return Numer rozkazu lub \ref POSNET_STATUS_INVALIDCOMMAND w przypadku błędu
	*/
	POSNET_API	unsigned long	__stdcall POS_GetRequestCommandID(POSNET_HANDLE hRequest);
	/*!
		\brief	Pobierz numer seryjny rozkazu

		\param hRequest	Uchwyt urządzenia
		\return Numer seryjny rozkazu
	*/
	POSNET_API	unsigned long	__stdcall POS_GetRequestCommandSerial(POSNET_HANDLE hRequest);
	/*!
		\brief	Zwróć stan rozkazu

		Funkcja zwraca stan w jakim aktualnie znajduje się rozkaz.
		Więcej informacji we wprowadzeniu - \ref sec_flow "Przepływ informacji" 

		\param hRequest	Uchwyt rozkazu
	*/
	POSNET_API	POSNET_STATE	__stdcall POS_GetRequestState(POSNET_HANDLE hRequest);
	/*!
		\brief	Czekaj na zakończenie rozkazu

		Funkcja powoduje zatrzymanie (uśpienie) wołającej ją aplikacji do momentu
		zmiany stanu rozkazu na \ref POSNET_RSTATE_COMPLETED lub POSNET_RSTATE_ERRCOMPLETED lub upłynięcia czasu
		wskazanego przez parametr timeout.
 
		\param hRequest	Uchwyt rozkazu
		\param	timeout Czas w ms na jaki ma aplikacja być uśpiona. 0 oznacza natychmiastowy 
				powrót
		\return	zwraca POSNET_STATUS_OK jeśli rozkaz został juz ukończony lub POSNET_STATUS_TIMEOUT 
				jeśli rozkaz nie zdążył się zakończyć we wskazanym czasie.
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_WaitForRequestCompleted(POSNET_HANDLE hRequest,unsigned long timeout);

	/*!
		@}
	*/

	// --------------------------------------------------------------------------------------------------------

	/*!
		\defgroup req_param	Obsługa parametrów rozkazu
		\ingroup sync_api

		\brief  W zależności od typu rozkazu może on posiadać odpowiednią
				ilość parametrów. Parametry te (w instrukcji programisty
				opisywane jako DATAxx) odkładane są na listę parametrów
				za pomocą kolejnych wywołań funkcji POS_PushRequestParamXXXXX.
		@{
	*/

	/*!
		\brief	Wstaw parametr typu "Ciąg znakowy"
		\param	hRequest	Uchwyt rozkazu
		\param	param		Ciąg znaków w konwencji języka C (zakończony znakiem 0)
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamString(POSNET_HANDLE hRequest,char *param);
	/*!
		\brief	Wstaw parametr typu liczba całkowita o zakresie 1 bajtowym (0 - 255) (znak)
		\param	hRequest	Uchwyt rozkazu
		\param	param		Wartość 1 bajtowa
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamByte(POSNET_HANDLE hRequest,unsigned char param);
	/*!
		\brief	Wstaw parametr typu liczba całkowita o zakresie 2 bajtowym (0 - 65535)
		\param	hRequest	Uchwyt rozkazu
		\param	param		Wartość 2 bajtowa
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamWord(POSNET_HANDLE hRequest,unsigned short param);
	/*!
		\brief	Wstaw parametr typu liczba całkowita o zakresie 4 bajtowym (0 - 2^32-1)
		\param	hRequest	Uchwyt rozkazu
		\param	param		Wartość 4 bajtowa
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamLong(POSNET_HANDLE hRequest,unsigned long param);
	/*!
		\brief	Wstaw parametr typu ilościowego - 2 miejsca po przecinku [typ Q w/g instrukcji programisty]
		
		W przeciwieństwie do sposobu reprezentacji liczb w protokole kasy biblioteka wymienia się z aplikacją
		reprezentacją tekstową liczb [tzw. Decimal String]. Biblioteka wewnętrznie tłumaczy otrzymany ciąg
		znaków na właściwy format liczby stosując jednocześnie technikę "ucinania" bez zaokrąglania orzymanej
		wartości. Na aplikacji spoczywa obowiązek dostarczenia licz w wymaganej precyzji (ilości miejsc po
		przecinku).
		
		Biblioteka akceptuje ciagi znaków zawierające kropkę "." lub "," jako separator części dziesiętnej.
		Biblioteka nie akceptuje stosowania separatora tysięcy.

		\warning W obecnej wersji kasa COMBO nie wykorzystuje tego typu.

		\param	hRequest	Uchwyt rozkazu
		\param	param		Ciąg znaków będący reprezentacją tekstową liczby
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamQuantity(POSNET_HANDLE hRequest,char *param);
	/*!
		\brief Wstaw parametr typu walutowego podawany w "groszach" - najmniejszej jednostce waluty

		\warning W obecnej wersji kasa COMBO nie wykorzystuje tego typu.

		\param	hRequest	Uchwyt rozkazu
		\param	param		Ciąg znaków będący reprezentacją tekstową liczby

		\sa POS_PushRequestParamQuantity
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamCurrency(POSNET_HANDLE hRequest,char *param); 
	/*!
		\brief Wstaw parametr typu numerycznego

		\param	hRequest	Uchwyt rozkazu
		\param	param		Ciąg znaków będący reprezentacją tekstową liczby, bez miejsc dziesiętnych. Ilość
							miejsc dziesiętnych wynika bezpośrednio z dokumentacji kasy (Instrukcja Programisty)
							i jest zależna od polecenia.

		\sa POS_PushRequestParamQuantity
		*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParamNumeric(POSNET_HANDLE hRequest,char *param); 

	/*!
		@}
	*/
	// --------------------------------------------------------------------------------------------------------

	/*!
		\defgroup	response_handling	Analiza pól odpowiedzi
		\ingroup sync_api

		@{
	*/
	/*!
		\brief	Pobierz ilość otrzymanych pól wartości

		Funkcja zwraca ilość pól DATA otrzymanych w odpowiedzi na rozkaz. Poprawna tylko
		wtedy, gdy sam rozkaz jest w stanie \ref POSNET_RSTATE_COMPLETED

		\param hRequest	Uchwyt zapytania/odpowiedzi
		\return Ilość otrzymanych pól odpowiedzi lub -1 w przypadku błędu
	*/
	POSNET_API	long			__stdcall POS_GetResponseValueCount(POSNET_HANDLE hRequest);
	/*!
		\brief	Jaki jest typ następnego parametru DATA

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\return	Typ danych aktualnego pola lub POSNET_STATUS_INVALIDVALUE w przypadku błędu (wyłącznie błędny uchwyt hRequest)
				lub gdy następne pole jest niedostępne (poprzednie było ostatnim).
	*/
	POSNET_API	POSNET_DATA_TYPE	__stdcall POS_GetResponseValueType(POSNET_HANDLE hRequest);
	/*!
		\brief	Pobierz watość typu "ciągu znaków" i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal Wskaźnik do bufora znakowego, w którym funkcja umieści odebrany ciąg znaków. Aplikacja musi zapewnić odpowiednią
						pojemność bufora, którą przekazuje w parametrze retValLen. W przypadku zbyt krótkiego
						bufora zostanie zwrócony błąd \ref POSNET_STATUS_BUFFERTOOSHORT
		\param	retValLen	Długość bufora
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PopResponseValueString(POSNET_HANDLE hRequest, char * retVal, unsigned long retValLen);
	/*!
		\brief	Pobierz watość typu liczba 1 bajtowa i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal	Wskaźnik do zmiennej, w której zostanie umieszczona odczytana wartość
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PopResponseValueByte(POSNET_HANDLE hRequest,unsigned char *retVal);
	/*!
		\brief	Pobierz watość typu liczba 2 bajtowa i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal	Wskaźnik do zmiennej, w której zostanie umieszczona odczytana wartość
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PopResponseValueWord(POSNET_HANDLE hRequest,unsigned short *retVal);
	/*!
		\brief	Pobierz watość typu liczba 4 bajtowa i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal	Wskaźnik do zmiennej, w której zostanie umieszczona odczytana wartość
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PopResponseValueLong(POSNET_HANDLE hRequest,unsigned long *retVal);
	/*!
		\brief	Pobierz watość typu "ilościowego" w jej reprezentacji jako ciąg znaków i przesuń na następne pole

		\warning	Separator części dziesiętnej może być ustawiony za pomocą funkcji \ref POS_SetDeviceParam
					Domyślnym separatorem jest separator systemowy (ustawienia regionalne Windows).

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal Wskaźnik do bufora znakowego, w którym funkcja umieści odebrany ciąg znaków. Aplikacja musi zapewnić odpowiednią
						pojemność bufora. W przypadku zbyt krótkiego
						bufora zostanie zwrócony błąd \ref POSNET_STATUS_BUFFERTOOSHORT
		\param	retValLen	Długość bufora

	*/
	POSNET_API	POSNET_STATUS		__stdcall POS_PopResponseValueQuantity(POSNET_HANDLE hRequest,char *retVal, unsigned long retValLen);
	/*!
		\brief	Pobierz watość typu "walutowego" w jej reprezentacji jako ciąg znaków w najmniejszej jednostce waluty i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal Wskaźnik do bufora znakowego, w którym funkcja umieści odebrany ciąg znaków. Aplikacja musi zapewnić odpowiednią
				pojemność bufora.  W przypadku zbyt krótkiego
						bufora zostanie zwrócony błąd \ref POSNET_STATUS_BUFFERTOOSHORT
		\param	retValLen	Długość bufora
	*/
	POSNET_API	POSNET_STATUS		__stdcall POS_PopResponseValueCurrency(POSNET_HANDLE hRequest, char *retVal, unsigned long retValLen);
	/*!
		\brief	Pobierz watość typu "numerycznego" w jej reprezentacji jako ciąg znaków i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param  retVal Wskaźnik do bufora znakowego, w którym funkcja umieści odebrany ciąg znaków. Aplikacja musi zapewnić odpowiednią
						pojemność bufora.  W przypadku zbyt krótkiego
						bufora zostanie zwrócony błąd \ref POSNET_STATUS_BUFFERTOOSHORT
		\param	retValLen	Długość bufora
	*/
	POSNET_API	POSNET_STATUS		__stdcall POS_PopResponseValueNumeric(POSNET_HANDLE hRequest, char *retVal, unsigned long retValLen);
	/*!
		\brief	Przesuń wskaźnik pól na początek listy

		Funkcja umożliwia rozpoczęcie analizy pól od początku.

		\param	hRequest	Uchwyt zapytania/odpowiedzi
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_ResponseRewind(POSNET_HANDLE hRequest);
	
	/*!
		@}
	*/

	/*!
		\defgroup req_queue Obsługa kolejek rozkazów i wyników
		\ingroup sync_api

		Aplikacja może obsługiwać wysyłane rozkazy w dwóch trybach.
		  * W trybie "wyślij-zapomnij" aplikacja tworzy rozkaz, wypełnia parametrami a następnie
			umieszcza w kolejce rozkazów do wykonania. Jednocześnie nie przechowuje samodzielnie 
			uchwytów wysłanych rozkazów. Wyniki rozkazów pobiera z kolejki wyników za pośrednictwem
			\ref POS_GetNextResponse i obsługuje odpowiednio.
		  * W trybie "interaktywnym" aplikacja tworzy rozkaz, wypełnia parametrami i wstawia
			do kolejki rozkazów. Jednakże zapamiętuje uchwyt rozkazu i obserwując stan rozkazu
			za pośrednictwem \ref POS_GetRequestState obsługuje go w momencie zakończenia.
		
		Tryb "wyślij-zapomnij" jest bardziej odpowiedni dla operacji masowych (np. programowanie
		kasy) gdyż umożliwia efektywniejsze (szybsze) wykonywanie rozkazów, których wynik jest
		mniej istotny.

		Tryb "interkatywny" wskazany jest dla rozkazów, których wynik jest w danej chwili niezbędny dla
		dalszej pracy aplikacji. W tym celu wprowadzony jest też rozkaz \ref POS_WaitForRequestCompleted
		który umozliwia synchronizowane oczekiwanie na zakończenie wykonania rozkazu przez kasę.

		\warning	Nie ma możliwości przeglądania kolejki rozkazów oczekujących/wysłanych. Jest to spowo
		dowane ich asynchronicznym w stosunku do apliacki wykonywaniem i zawartość tej kolejki może się
		zmieniać w trakcie wykonywania zaputań przeglądających (rozkazy mogą znikać z kolejki mimo
		iż aplikacja pobrała je jeszcze z kolejki oczekujących).

		@{
	*/

	/*!
		\brief	Pobierz z kolejki odpowiedzi (rozkazów zakończonych) następny dostępny wynik.

		Z kolejki odpowiedzi zostaje pobrany (i usunięty) następny wynik. Pobrany wynik należy 
		zniszczyć za pomocą \ref POS_DestroyRequest. Pobierane są wyłącznie wyniki otrzymane na
		rozkazy wysłane za pośrednictwem bieżącego kontekstu urządzenia (hLocalDevice). Rozkazy 
		wysłane za pomocą innych kontekstów tego samego urządzenia są pomijane.

		Funkcja jest nieblokująca.

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\return	Uchwyt do odpowiedzi lub NULL w przypadku błędu lub braku następnej odpowiedzi
	*/
	POSNET_API	POSNET_HANDLE	__stdcall POS_GetNextResponse(POSNET_HANDLE hLocalDevice);
	/*!
		\brief	Pobierz ilość wyników w kolejce wyników

		\param hLocalDevice	Uchwyt lokalny urządzenia
		\return Ilość wyników dla bieżącego kontekstu urządzenia.
	*/
	POSNET_API	unsigned long	__stdcall POS_GetResponseCount(POSNET_HANDLE hLocalDevice);
	/*!
		\brief	Pobierz ilość rozkazów oczekujących w kolejce rozkazów wysłanych przez bieżący kontekst
				urządzenia lub wszystkich rozkazów oczekujących w kolejce.

		\param hLocalDevice	Uchwyt lokalny urządzenia
		\param globalnie Jeśli parametr ten jest różny od 0 zwracana wartość podaje ilość wszystkich rozkazów 
				oczekujących w kolejce.
	*/
	POSNET_API	unsigned long	__stdcall POS_GetRequestCount(POSNET_HANDLE hLocalDevice,unsigned char globalnie=0);

	/*!
		\brief	Pobierz statystyki kolejek. Statystyki są zwracane w kontekście całego urządzenia.

		\param hLocalDevice	Uchwyt lokalny urządzenia
		\param sent		Do tej zmiennej wpisywana jest ilość wszystkich wysłanych do kasy
						rozkazów
		\param completed	Do tej zmiennej wpisywana jest ilość wszystkich ukończonych rozkazów
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_RequestQueueStats(POSNET_HANDLE hLocalDevice, unsigned long *sent, unsigned long *completed);	


	/*!
		\brief	Wyczyść kolejkę rozkazów oczekujących na wysłanie

		Czyści kolejkę rozkazów oczekujących na wysłanie. Funkcja powinna być wykorzystywana wyłącznie
		w sytuacji, gdy nastąpił krytyczny błąd urządzenia. Rozkazy już wysłane zostaną obsłużone, jeśli
		w dalszej perspektywie pojawi się na nie odpowiedź. Domyślnie rozkazy czyszczone są wyłącznie dla bieżącego
		kontekstu urządzenia.

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param globalnie Jeśli parametr ten jest różny od 0 ignorowany jest kontekst urządzenia.
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_RequestQueueCancelPending(POSNET_HANDLE hLocalDevice,unsigned char globalnie=0);
	/*!
		\brief	Wyczyść kolejkę rozkazów oczekujących na wysłanie

		Czyści kolejkę rozkazów oczekujących. Funkcja powinna być wykorzystywana wyłącznie
		w sytuacji, gdy nastąpił krytyczny błąd urządzenia. Wszystkie otrzymane później
		wyniki dla rozkazów, które były w trakcie wykonywania zostaną odrzucone. 
		Domyślnie rozkazy czyszczone są wyłącznie dla bieżącego
		kontekstu urządzenia.

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param globalnie Jeśli parametr ten jest różny od 0 ignorowany jest kontekst urządzenia.
	*/
	POSNET_API  POSNET_STATUS	__stdcall POS_RequestQueueCancelAll(POSNET_HANDLE hLocalDevice,unsigned char globalnie=0);
	/*!
		\brief	Anuluj rozkaz aktualnie wykonywany przez kasę

		Funkcja jest przydatna w sytuacji, gry aplikacja chce anlulować wyłącznie wykonywany
		rozkaz bez czyszczenia kolejki oczekujących, a pracuje w trybie wyslij-zapomnij.
		Anulowanie następuje w kontekście globalnym urządzenia, jako że tylko jeden rozkaz może być 
		w danej chwili wykonywany przez kasę. 

		\param hLocalDevice	Uchwyt lokalny urządzenia
		\return Uchwyt anulowanego rozkazu lub NULL w przypadku braku rozkazu do anulowania
	*/
	POSNET_API	POSNET_HANDLE	__stdcall POS_CancelExecuting(POSNET_HANDLE hLocalDevice);


	/*!
		\brief	Wywołuje funkcję REPEAT dla utraconej odpowiedzi kasy

		Funkcja jest przydatna w sytuacji, gdy odpowiedź kasy na wysłaną ramkę została utracona w 
		wyniku błędu transmisji z kasy do komputera. Jej użycie powoduje ponowne wysłanie ramki z ustawionym 
		bitem REPEAT. Użycie możliwe jest jeśli rozkaz znajduje się w stanie POSNET_RSTATE_SENT lub POSNET_RSTATE_ACK
		(por. \ref POS_GetRequestState)

		\param hRequest	Uchwyt rozkazu, który ma być ponowiony
		\return Status wykonania
	*/
	POSNET_API      POSNET_STATUS  __stdcall POS_RepeatRequest(POSNET_HANDLE hRequest);

	/*!
		@}
	*/

	// --------------------------------------------------------------------------------------------------------
	/*!
	\defgroup	sync_api	Obsługa synchroniczna kasy
	@{
	*/
	
	// PLACEHOLDER

	/*!
		@}
	*/
	// --------------------------------------------------------------------------------------------------------

	// --------------------------------------------------------------------------------------------------------
	/*!
		\addtogroup	event_handling
		@{
	*/
	/*!
		\brief	Sprawdzenie czy w kolejce zdarzeń asynchronicznych znajdują się obiekty.

		Sprawdza czy w kolejce zdarzeń asynchronicznych znajdują się jakiekolwiek obiekty.
		Wśród tych obiektów może być obiekt karty rabatowej. Obiekty asynchroniczne nie
		posiadają kontekstu urządzenia.

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\return	\ref POSNET_STATUS_OK jeśli są elementy lub \ref POSNET_STATUS_EMPTY jeśli ich nie ma
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_AsyncDataWaiting(POSNET_HANDLE hLocalDevice);
	/*!
		\brief Pobierz z kolejki asynchronicznej następny obiekt.

		Pobrany obiekt należy następnie skasować za pomocą funkcji \ref POS_DestroyRequest .
		
		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param	timeout	Parametr określający czas oczekiwania na nową wartość w kolejce asynchronicznej.
				Jeśli ma wartość INFINITE funkcja czeka w nieskończoność, 0 - wraca natychmiast w przeciwnym
				wypadku oczekuje odpowiednią ilość milisekund na otrzymanie danych.
		\return NULL jeśli nie ma (lub oczekiwanie zakończyło się timeoutem), uchwyt obiektu w przeciwnym razie.
	*/
	POSNET_API	POSNET_HANDLE	__stdcall POS_PopAsyncData(POSNET_HANDLE hLocalDevice,unsigned long timeout);
	/*!
		\brief	Ilość elementów w kolejce zdarzeń asynchronicznych

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\return Ilość elementów w kolejce lub -1 w przypadku błędu
	*/
	POSNET_API	unsigned long	__stdcall POS_AsyncQueueLength(POSNET_HANDLE hLocalDevice);
	/*!
		\brief	Wyczyść kolejkę zdarzeń asynchronicznych

		Czyści kolejkę zdarzeń asynchronicznych bez ich obsługi.

		\param hLocalDevice Uchwyt urządzenia
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_AsyncQueuePurge(POSNET_HANDLE hLocalDevice);

	/*!
		@}
	*/
	// --------------------------------------------------------------------------------------------------------

	// --------------------------------------------------------------------------------------------------------
	/*!
		\defgroup	sale_buffer Obsługa bufora pozycji paragonowych

		\brief	Odebrane pozycje paragonowe są przechowywane w osobnej kolejce. Umożliwia to
				rozdzielenie obsługi poleceń zwykłych od obsługi odbioru danych towarowych,
				a co za tym idzie z punktu widzenia aplikacji - równoległe ich wykonywanie.

		Rozkazy odczytu kolejnych pozycji paragonowych są umieszczane w głównej kolejce rozkazów,
		ale ich wyniki są gromadzone w osobnej kolejce odbiorczej. Dzięki temu obsługa pozycji
		jest niezależna od obsługi rozkazów głównych.
		@{
	*/
	
	/*!
		\brief Pobierz z kolejki pozycji paragonowych następny obiekt. Obiekty paragonowe
		mają swój kontekst urządzenia, ale dla wygody umieszczane są w osobnej kolejce odbiorczej.

		Pobrany obiekt należy następnie skasować za pomocą funkcji \ref POS_DestroyRequest .

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param	timeout	Parametr określający czas oczekiwania na nową wartość w kolejce paragonowej.
		Jeśli ma wartość INFINITE funkcja czeka w nieskończoność, 0 - wraca natychmiast w przeciwnym
		wypadku oczekuje odpowiednią ilość milisekund na otrzymanie danych.
		\return NULL jeśli nie ma (lub oczekiwanie zakończyło się timeoutem), uchwyt obiektu w przeciwnym razie.
	*/
	POSNET_API	POSNET_HANDLE __stdcall POS_PopSalesQueue(POSNET_HANDLE hLocalDevice,unsigned long timeout );
	/*!
		\brief	Ilość elementów w kolejce pozycji paragonowych

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param globalnie Jeśli parametr ten jest różny od 0 zwracana jest ilość obiektów w kontekscie globalnym, a nie lokalnym urządzenia
		(ilość wszystkich pozycji)
		\return Ilość elementów w kolejce lub -1 w przypadku błędu
	*/
	POSNET_API	unsigned long	__stdcall POS_SalesQueueLength(POSNET_HANDLE hLocalDevice,unsigned char globalnie=0);
	/*!
		\brief	Wyczyść kolejkę pozycji paragonowych

		Czyści kolejkę zdarzeń paragonowych bez ich obsługi.

		\param hLocalDevice Uchwyt lokalny urządzenia
		\param globalnie Jeśli ten parametr jest różny od 0 czyszczone są WSZYSTKIE obiekty w kolejce, nie tylko należące
				do bieżącego kontekstu urządzenia.
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_SalesQueuePurge(POSNET_HANDLE hLocalDevice,unsigned char globalnie=0);

	/*!
		@}
	*/
	// --------------------------------------------------------------------------------------------------------


}


#endif

