#ifndef _posnetH_
#define _posnetH_

/*

	Nagłówek w wersji: 1.0

*/


/*!
	\mainpage Biblioteka interfejsu drukarki POSNET COMBO DF
	
	Spis Treści

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

	\b "SPECYFIKACJA PROTOKOŁU COMBO DF 1.01 / THERMAL 3.01 v 010"

	<hr>

	\section sec_intro	Wprowadzenie

	Podstawowe założenia, które zostały przyjęte przy projektowaniu biblioteki dla
	drukarki POSNET COMBO DF są następujące:
	  - komunikacja za pośrednictwem RS-232, USB (VCP lub DXX)
	  - wielowątkowość i wielo-urządzeniowość biblioteki (brak zmiennych globalnych)
	  - obsługa zdarzeń asynchronicznych (zmiany statusu urządzenia)
	  - 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
	  - maksymalna zgodność API z biblioteką dla kas COMBO/NEO
	  .
    
	Ze względu na to, że ilość rozkazów wykorzystywanych w komunikacji z drukarką 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
	drukarki w tym dodanie nowych czy zmiana ilości i rodzaju parametrów nie wymagają 
	zmian w bibliotece komunikacyjnej, a jedynie dostosowania aplikacji do tych zmian.

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

	\section sec_flow	Przepływ informacji

	W aplikacji istnieją 2 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" ]	
		NOWY -> OCZEKUJACY [label="POS_PostRequest" fontname=Helvetica fontsize=8];
		OCZEKUJACY -> K0;
		K0 -> WYSLANY [label="transmisja do drukarki" fontname=Helvetica fontsize=8];
		WYSLANY -> ZAKONCZONY [label="sekwencja wykonana\n lub blad" fontname=Helvetica fontsize=8];
		ZAKONCZONY -> K1 [label="Rozkaz" 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. Dodatkowo dla każdego
	urządzenia istnieje osobny wątek wykonujący cykliczne zapytania o status urządzenia.

	\section sec_async	Zdarzenia asynchroniczne

	\subsection sec_async_events Zdarzenia asynchroniczne

	Drukarka POSNET COMBO DF posiada możliwość generacji 
	zdarzeń zmiany statusu urządzenia 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. Aplikacja główna może zostać 
	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ć status urzadzenia (polling).

	UWAGA: Z natury działania drukarki sprawdzenie pełnego statusu drukarki składa się
	z dwóch niezaleznych operacji, w związku z tym w momencie przejscia drukarki ze stanu
	poprawngo do stanu awarii mechanizmu drukującego wystąpią dwa kolejne zdarzenia 
	asynchroniczne (pierwsze wskazujące zmiane statusu drukarki, drugie statusu mechanizmu).

	UWAGA: Jeśli status drukarki nie wskazuje na błąd mechanizmu drukarki wartość statusu
	mechanizmu jest nieistotna (nieważna).

	\section sec_example	Przykładowa sekwencja poleceń

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

	\code

	\\ Przygotowanie i otwarcie urzadzenia 
	void *hDevice=NULL;
	hDevice=POS_CreateDeviceHandle(type);
	POS_SetDebugLevel(hDevice,POSNET_DEBUG_ALL & 0xFFFFFFFE);
	POS_SetDeviceParam(hDevice,POSNET_DEV_PARAM_COMSETTINGS,(void*)"COM1,9600,8,N,1,H");
	void *hLocalDevice=POS_OpenDevice(hDevice);

	\\ Wysłanie kolejnych rozkazów paragonu
	\\ Wersja z uzupełnianiem parametrów pojedynczo
	hRequest = POS_CreateRequest(hLocalDevice,"trinit");
	POS_PushRequestParam(hRequest,"bm","1");
	POS_PostRequest(hRequest,POSNET_REQMODE_SPOOL);

	\\ Oczekiwanie na wykonanie rozkazu
	POS_WaitForRequestCompleted(hRequest,5000);

	\\ Sprawdzenie statusu wykonania
	if (POS_GetRequestStatus(hRequest) != POSNET_STATUS_OK) { OBSLUGA_BLEDU }

	\\ Usuniecie rozkazu
	POS_DestroyRequest(hRequest);

	\\ Nastepne polecenia, wersja z tworzeniem rozkazu z parametrami	
	hRequest = POS_CreateRequestEx(hLocalDevice,"trline","na,Bułka Standardowa\nvt,0\npr,35");
	POS_PostRequest(hRequest,POSNET_REQMODE_SPOOL);
	POS_WaitForRequestCompleted(hRequest,5000);
	if (POS_GetRequestStatus(hRequest) != POSNET_STATUS_OK) { OBSLUGA_BLEDU }
	POS_DestroyRequest(hRequest);
	hRequest = POS_CreateRequestEx(hLocalDevice,"trpayment","ty,0\nre,0\nwa,35");
	POS_PostRequest(hRequest,POSNET_REQMODE_SPOOL);
	POS_WaitForRequestCompleted(hRequest,5000);
	if (POS_GetRequestStatus(hRequest) != POSNET_STATUS_OK) { OBSLUGA_BLEDU }
	POS_DestroyRequest(hRequest);
	hRequest = POS_CreateRequestEx(hLocalDevice,"trend","to,35\nfp,35");
	POS_PostRequest(hRequest,POSNET_REQMODE_SPOOL);
	POS_WaitForRequestCompleted(hRequest,5000);
	if (POS_GetRequestStatus(hRequest) != POSNET_STATUS_OK) { OBSLUGA_BLEDU }
	POS_DestroyRequest(hRequest);

	\\ zamkniecie urzadzenia
	POS_CloseDevice(hLocalDevice);
	POS_DestroyDeviceHandle(hDevice);

	\endcode

	Biblioteka posiada zestaw aplikacji demonstrujących różne sekwencje
	poleceń dla drukarki.

	  -  demo_lowlevel - demonstruje przykładową realizację pojedynczej transakcji (paragonu)
	  -  demo_requests - prezentuje różne sposoby obsługi parametrów poleceń oraz sposobu wysyłania rozkazów i odbioru danych
	  -  demo_async2 - prezentuje realizację obsługi statusu drukarki za pośrednictwem zdarzeń (Event) w systemie Windows lub semaforów dla systemu Linux
	  -  demo_async3 - prezentuje realizację obsługi statusu drukarki za pośrednictwem funkcji typu callback
	  -  demo_all - prezentuje około 20 różnych przydatnych sekwencji drukarki, w tym różne warianty sprzedaży, fakturę VAT, formatki, raporty i ustawienia,
	  demo to obsługuje zdarzenia nieprzewidywane metodą pollingu za pośrednictwem funkcji POS_GetPrnDeviceStatus
	  .
    Kod poszczególnych programów demonstracyjnych zawiera w komenarzach dodatkowe informacje na temat ich działania.

	\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_WaitForRequestCompleted Lib "posnet.dll" (ByVal H As Long, ByVal P As Long) As Long
	\endverbatim

	Podobny kod dla Delphi 7

	\verbatim
	function POS_WaitForRequestCompleted (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:

	libposcmbth.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 drukarki 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 drukarką 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 minimalnego rozmianu bufora znakowego nazwy polecenia, nazwy parametru
	*/
	#define	POSNET_NAMELENGTH_MAX	16

	/*!
	\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 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_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
		drukarki.
		.

	*/
	#define POSNET_INTERFACE_USB	0x0002

	/*! @}

	*/


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

		Zapis/Odczyt
		
		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+DTR/DSR, (R)Hardware RTS/CTS, (D)Hardware DTR/DSR
	*/
	#define	POSNET_DEV_PARAM_COMSETTINGS	0x00020001

	/*!
		\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 Numer seryjny drukarki 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 drukarek 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 Interwał pomiędzy automatycznymi odpytaniami o status drukarki

	TYLKO ZAPIS

	Parametr - wskaźnik na liczbę typu unsigned long (32 bit) zawierającą żądany czas pomiędzy zapytaniami w sekundach.
	*/
	#define POSNET_DEV_PARAM_STATUSPOLLINGINTERVAL		0x0002000A


	/*!
	\brief	Pobranie uchwytu portu szeregowego

	TYLKO ODCZYT

	Parametr - Windows - wskaźnik na HANDLE, Linux - wskaźnik na liczbę typu int
	*/

	#define POSNET_DEV_PARAM_FILEHANDLE		0x0002000E	


	/*!
		@}
	*/


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

	/*!
		\brief	Utworzenie uchwytu do nowego urządzenia. 
		
		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);	



	/*!
		@}
	*/

	/*! \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 drukarki.
		@{
	*/
	
	#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 drukarki
	#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_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_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_CASHREGBASE			0x00430000 //!< Bazowy kod błędu wykonania rozkazu drukarki [błędy 0x00430000 - 0x0043FFFF]
	#define	POSNET_STATUS_CASHREGCOMMBASE		0x00440000 //!< Bazowy kod błędu transmisji rozkazu do drukarki [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

		UWAGA: W celu efektywnego zarządzania błędami (w sytuacji, gdy drukarka zwraca błędy w róznych postaciach)
		zarządzanie błędami zostało zunifikowane - nazwa rozkazu zostaje umieszczona w polu "cm" odpowiedzi, 
		kod błędu natomiast umieszczany jest także w polu o nazwie "!error" odpowiedzi. 
		Dzięki temu postać odpowiedzi jest identyczna w przypadku błędów ramki i błędów.

		\param hRequest Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)
		\return Funkcja zwraca kod błędu związany z rozkazem. W przypadku odebrania odpowiedzi o błędzie 
				wykonania rozkazu zwracane są kody odebrane od drukarki, 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 drukarki na rozkaz, po jego zakończeniu w wyniku błędu drukarki – kod błędu drukarki zwiększony jest o wartość 0x00430000.
				Kody o wartościach 0x00440000-0x0044FFFF wykorzystywane są w przypadku negatywnej odpowiedzi drukarki 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 drukarki"
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_GetRequestStatus(POSNET_HANDLE hRequest);

	/*!
		\brief Pobranie statusu drukarki. Drukarka jest periodycznie odpytywana o status i rezultat tej operacji jest przechowywany.
		Funkcja jest blokująca jeśli wykonywane jest odpytywanie.

		\param hLocalDevice Lokalny uchwyt urządzenia
		\param statusMode Sposób uzyskania statusu - 0 - zwróć ostatni status automatyczny , 1 - odpytaj urządzenie jeśli brak statusu - blokujące!
		\param globalStatus Status urządzenia zwracany przez rozkaz sdev (-1 jeśli nie odpytano)
		\param printerStatus Status mechanizmu drukującego  (nieistotny jeśli sdev=-1)
		\return Funkcja zwraca status wykonania rozkazu, oraz wypełnia pola parametrów globalStatus i printerStatus
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_GetPrnDeviceStatus(POSNET_HANDLE hLocalDevice,const char statusMode,long *globalStatus,long *printerStatus);

	/*!
		@}
	*/



	// --------------------------------------------------------------------------------------------------------
	/*! \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 wywołanie funkcji w momencie otrzymania
		pakietu danych asynchronicznych.
	*/
	#define POSNET_EVENT_CALLBACK	0x0004
	/*! 
		@}
	*/

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


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

		Drukarka ma możliwość generacji zdarzeń asynchronicznych w postaci zmian statusu drukarki, które muszą być przesłane do aplikacji. 
		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 o status
		
		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. Jako lParam takiego komunikatu wysyłany jest
				złożony status urządzenia (w/g wzoru: (Status urządzenia * 65536)+status mechanizmu )
		\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
		- złożony status urządzenia (w/g wzoru: (Status urządzenia * 65536)+status mechanizmu ) . 
	*/
	typedef void (POSNET_CALLBACK_T)(unsigned long status);

	/*!
		\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:
										 //!< !sdev, !sprn
	#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 - efektywnie
										  //!< umożliwia umieszczenie rozkazu w kolejce WYŁĄCZNIE gdy jest ona pusta,
										  //!< za wyjątkiem rozkazów !sdev i !sprn
	#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 - nie dotyczy to rozkazów
											 //!< wykonanych znajdujących się w kolejce odbiorczej).
	#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_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 drukarki.

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

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

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param	command	Identyfikator rozkazu dla drukarki
		\return	Zwracany jest uchwyt do nowego obiektu rozkazowego lub NULL w przypadku błędu
	*/
	POSNET_API	POSNET_HANDLE	 __stdcall POS_CreateRequest(POSNET_HANDLE hLocalDevice, const char *command);
	/*!
		\brief	Funkcja tworzy nowy obiekt rozkazowy dla drukarki oraz dodaje parametry rozkazu.

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

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

		\param	hLocalDevice	Uchwyt lokalny urządzenia
		\param	command	Identyfikator rozkazu dla drukarki
		\param  parameters Lista parametrów do dodania (zastępuje dodatkowe wywołania \ref POS_PushRequestParam) 
		format: [nazwa parametru],[wartosc]\n[nazwa parametru],[wartosc]\n....[nazwa parametru],[wartosc]
		UWAGA: Jeśli wartość parametru zawiera w sobie znaki nowej linii lub przecinka należy użyć \ref POS_PushRequestParam aby
		dodać taki parametr do rozkazu.
		\return	Zwracany jest uchwyt do nowego obiektu rozkazowego lub NULL w przypadku błędu
	*/
	POSNET_API      POSNET_HANDLE  __stdcall POS_CreateRequestEx(POSNET_HANDLE hLocalDevice, const char* command,const char *parameters);
	/*!
		\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 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 drukarki i
		automatycznie wysyłany w miarę zwalniania się bufora drukarki. 
		\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 drukarka jest wolna i dopiero gdy jest wolna umożliwia
		umieszczenie rozkazu w buforze. W ten sposób w danej chwili do drukarki 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 drukarki 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 -  dla anulowanego rozkazu należy
		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 (żądania wychodzącego lub odpowiedzi z drukarki)
	*/
	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 (żądania wychodzącego lub odpowiedzi z drukarki)
	*/
	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 (żądania wychodzącego lub odpowiedzi z drukarki)
		\param retCommand   Bufor znakowy, w którym zostanie umieszczona nazwa polecenia
		\return Status wykonania rozkazu
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_GetRequestCommandID(POSNET_HANDLE hRequest,char *retCommand);
	/*!
		\brief	Pobierz numer seryjny rozkazu

		\param hRequest Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)
		\return Token (numer seryjny) powiązany z rozkazem
	*/
	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 (żądania wychodzącego lub odpowiedzi z drukarki)
	*/
	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  odkładane są na listę parametrów
				za pomocą kolejnych wywołań funkcji POS_PushRequestParam. Drukarka 
				COMBO DF przyjmuje parametry bez względu na ich kolejność.
		@{
	*/

	/*!
		\brief	Wstaw parametr rozkazu
		\param	hRequest	Uchwyt rozkazu
		\param  param_name		Nazwa parametru reprezentowana jako ciąg znaków w konwencji języka C (zakończony znakiem 0)
		\param	param_value		Wartość parametru reprezentowana jako ciąg znaków w konwencji języka C (zakończony znakiem 0)
	*/
	POSNET_API	POSNET_STATUS	__stdcall POS_PushRequestParam(POSNET_HANDLE hRequest,const char *param_name,const char *param_value);

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

	/*!
		\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	Pobierz wartość parametru i przesuń na następne pole

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param retName Wskaźnik do bufora znakowego, w którym funkcja umieści nazwę odebranego parametru. Długość tego bufora MUSI być conajmniej
						POSNET_NAMELENGTH_MAX
		\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_PopResponseValue(POSNET_HANDLE hRequest,char *retName, char * retVal, unsigned long retValLen);
	/*!
		\brief	Pobierz watość parametru po nazwie

		\param	hRequest	Uchwyt zapytania/odpowiedzi
		\param paramName Wskaźnik do bufora znakowego, w którym znajduje się nazwa poszukiwanego pola 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_GetResponseValue(POSNET_HANDLE hRequest,const char *paramName, 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. sprawdzanie bazy towarów)
		gdyż umożliwia efektywniejsze (szybsze) wykonywanie rozkazów, których wynik jest
		mniej istotny.

		Tryb "interaktywny" 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 drukarkę.

		\warning	Nie ma możliwości przeglądania kolejki rozkazów oczekujących/wysłanych. Jest to spowodowane 
		ich asynchronicznym w stosunku do apliacki wykonywaniem i zawartość tej kolejki może się
		zmieniać w trakcie wykonywania zapytań 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.
		UWAGA: Uchwyt wyniku jest tożsamy z uchwytem rozkazu, który go spowodował - oznacza to,
		że niszczenie za pomocą \ref POS_DestroyRequest rozkazu jest równoznaczne ze zniszczeniem
		odpowiedzi i odwrotnie.

		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 drukarki
						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 (nie ignoruj odpowiedzi na rozkazy już wysłane)

		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 wykonanie (zarówno wysłanych jak i oczekujących na wysłanie)

		Czyści kolejkę rozkazów wychodzą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	Wysyła do drukarki żądanie powtórzenia transmisji odpowiedzi

		Funkcja jest przydatna w sytuacji, gdy chcemy powtórzyć odbiór ramki jeśli nastąpił timeout i istnieje
		podejrzenie, że drukarka otrzymała rozkaz ale odpowiedź do nas nie powróciła. Do powtórzenia używana
		jest de facto sekwencja 'rpt'. Uniemożliwia to przypadkowe podwójne wykonanie sekwencji jeśli wcześniej nie
		dotarła do drukarki (zostanie zwrócony błąd 13).
		Użycie możliwe jest jeśli rozkaz znajduje się w stanie POSNET_RSTATE_SENT. 
		(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 drukarki
	@{
	*/
	
	// PLACEHOLDER

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

}


#endif

