POSNET COMBO LIBRARY: Obsługa kolejek rozkazów i wyników

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

## Funkcje
POSNET_API POSNET_HANDLE __stdcall | POS_CancelExecuting (POSNET_HANDLE hLocalDevice)
| Anuluj rozkaz aktualnie wykonywany przez kasę.
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)
| Wywołuje funkcję REPEAT dla utraconej odpowiedzi kasy.
POSNET_API POSNET_STATUS __stdcall | POS_RequestQueueCancelAll (POSNET_HANDLE hLocalDevice, unsigned char globalnie=0)
| Wyczyść kolejkę rozkazów 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.
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. 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 POS_WaitForRequestCompleted który umozliwia synchronizowane oczekiwanie na zakończenie wykonania rozkazu przez kasę.

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

## Dokumentacja funkcji

POSNET_API POSNET_HANDLE __stdcall POS_CancelExecuting | ( | POSNET_HANDLE | hLocalDevice | ) |

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ę.

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia

Zwraca:
  Uchwyt anulowanego rozkazu lub NULL w przypadku braku rozkazu do anulowania

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.

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

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

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.

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 kasy rozkazów
  | completed | Do tej zmiennej wpisywana jest ilość wszystkich ukończonych rozkazów