# Obsługa kolejek rozkazów i wyników
[Obsługa synchroniczna drukarki]

## Funkcje
POSNET_API POSNET_HANDLE __stdcall | POS_GetNextResponse (POSNET_HANDLE hLocalDevice)
| Pobierz z kolejki odpowiedzi (rozkazów zakończonych) następny dostępny wynik.
POSNET_API unsigned long __stdcall | POS_GetRequestCount (POSNET_HANDLE hLocalDevice, unsigned char globalnie=0)
| 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.
POSNET_API unsigned long __stdcall | POS_GetResponseCount (POSNET_HANDLE hLocalDevice)
| Pobierz ilość wyników w kolejce wyników.
POSNET_API POSNET_STATUS __stdcall | POS_RepeatRequest (POSNET_HANDLE hRequest)
| Wysyła do drukarki żądanie powtórzenia transmisji odpowiedzi.
POSNET_API POSNET_STATUS __stdcall | POS_RequestQueueCancelAll (POSNET_HANDLE hLocalDevice, unsigned char globalnie=0)
| Wyczyść kolejkę rozkazów oczekujących na wykonanie (zarówno wysłanych jak i oczekujących na wysłanie).
POSNET_API POSNET_STATUS __stdcall | POS_RequestQueueCancelPending (POSNET_HANDLE hLocalDevice, unsigned char globalnie=0)
| Wyczyść kolejkę rozkazów oczekujących na wysłanie (nie ignoruj odpowiedzi na rozkazy już wysłane).
POSNET_API POSNET_STATUS __stdcall | POS_RequestQueueStats (POSNET_HANDLE hLocalDevice, unsigned long *sent, unsigned long *completed)
| Pobierz statystyki kolejek. Statystyki są zwracane w kontekście całego urządzenia.

## Opis szczegółowy

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 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 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 POS_WaitForRequestCompleted który umozliwia synchronizowane oczekiwanie na zakończenie wykonania rozkazu przez drukarkę.

Ostrzeżenie:
  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).

## Dokumentacja funkcji

POSNET_API POSNET_HANDLE __stdcall POS_GetNextResponse | ( | POSNET_HANDLE | hLocalDevice | ) |

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ą 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ą POS_DestroyRequest rozkazu jest równoznaczne ze zniszczeniem odpowiedzi i odwrotnie.

Funkcja jest nieblokująca.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia

Zwraca:
  Uchwyt do odpowiedzi lub NULL w przypadku błędu lub braku następnej odpowiedzi

POSNET_API unsigned long __stdcall POS_GetRequestCount | ( | POSNET_HANDLE | hLocalDevice,
|  | unsigned char | globalnie = `0` |
| ) |  |  |

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.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia
  | 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_GetResponseCount | ( | POSNET_HANDLE | hLocalDevice | ) |

Pobierz ilość wyników w kolejce wyników.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia

Zwraca:
  Ilość wyników dla bieżącego kontekstu urządzenia.

POSNET_API POSNET_STATUS __stdcall POS_RepeatRequest | ( | POSNET_HANDLE | hRequest | ) |

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. POS_GetRequestState)

Parametry:

  | hRequest | Uchwyt rozkazu, który ma być ponowiony

Zwraca:
  Status wykonania

POSNET_API POSNET_STATUS __stdcall POS_RequestQueueCancelAll | ( | POSNET_HANDLE | hLocalDevice,
|  | unsigned char | globalnie = `0` |
| ) |  |  |

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.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia
  | 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` |
| ) |  |  |

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.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia
  | globalnie | Jeśli parametr ten jest różny od 0 ignorowany jest kontekst urządzenia.

POSNET_API POSNET_STATUS __stdcall POS_RequestQueueStats | ( | POSNET_HANDLE | hLocalDevice,
|  | unsigned long * | sent,
|  | unsigned long * | completed |
| ) |  |  |

Pobierz statystyki kolejek. Statystyki są zwracane w kontekście całego urządzenia.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia
  | sent | Do tej zmiennej wpisywana jest ilość wszystkich wysłanych do drukarki rozkazów
  | completed | Do tej zmiennej wpisywana jest ilość wszystkich ukończonych rozkazów