# Obsługa obiektów rozkazowych
[Obsługa synchroniczna drukarki]

## Funkcje
POSNET_API POSNET_STATUS __stdcall | POS_CancelRequest (POSNET_HANDLE hRequest)
| Anulowanie obiektu rozkazowego.
POSNET_API POSNET_HANDLE __stdcall | POS_CreateRequest (POSNET_HANDLE hLocalDevice, const char *command)
| Funkcja tworzy nowy obiekt rozkazowy dla drukarki.
POSNET_API POSNET_HANDLE __stdcall | POS_CreateRequestEx (POSNET_HANDLE hLocalDevice, const char *command, const char *parameters)
| Funkcja tworzy nowy obiekt rozkazowy dla drukarki oraz dodaje parametry rozkazu.
POSNET_API POSNET_STATUS __stdcall | POS_DestroyRequest (POSNET_HANDLE hRequest)
| Zniszczenie obiektu rozkazowego i zwolnienie zajmowanej przezeń pamięci.
POSNET_API unsigned long __stdcall | POS_GetRequestAge (POSNET_HANDLE hRequest)
| Wiek rozkazu - czas jaki upłynął od wywołania POS_PostRequest.
POSNET_API POSNET_STATUS __stdcall | POS_GetRequestCommandID (POSNET_HANDLE hRequest, char *retCommand)
| Pobierz numer polecenia, który został użyty przy tworzeniu obiektu.
POSNET_API unsigned long __stdcall | POS_GetRequestCommandSerial (POSNET_HANDLE hRequest)
| Pobierz numer seryjny rozkazu.
POSNET_API POSNET_STATE __stdcall | POS_GetRequestState (POSNET_HANDLE hRequest)
| Zwróć stan rozkazu.
POSNET_API POSNET_STATUS __stdcall | POS_PostRequest (POSNET_HANDLE hRequest, unsigned char mode)
| Fukcja umieszcza obiekt rozkazowy w kolejce rozkazów do wykonania.
POSNET_API POSNET_HANDLE __stdcall | POS_RequestDevice (POSNET_HANDLE hRequest)
| Funkcja służy do pobrania uchwytu urządzenia związanego z rozkazem.
POSNET_API POSNET_STATUS __stdcall | POS_WaitForRequestCompleted (POSNET_HANDLE hRequest, unsigned long timeout)
| Czekaj na zakończenie rozkazu.

## Dokumentacja funkcji

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

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

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

Parametry:

  | hRequest | Uchwyt rozkazu

POSNET_API POSNET_HANDLE __stdcall POS_CreateRequest | ( | POSNET_HANDLE | hLocalDevice,
|  | const char * | command |
| ) |  |  |

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 - Przepływ informacji

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia
  | command | Identyfikator rozkazu dla drukarki

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

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 - Przepływ informacji

Parametry:

  | hLocalDevice | Uchwyt lokalny urządzenia
  | command | Identyfikator rozkazu dla drukarki
  | parameters | Lista parametrów do dodania (zastępuje dodatkowe wywołania POS_PushRequestParam) format: [nazwa parametru],[wartosc] [nazwa parametru],[wartosc] ....[nazwa parametru],[wartosc] UWAGA: Jeśli wartość parametru zawiera w sobie znaki nowej linii lub przecinka należy użyć POS_PushRequestParam aby dodać taki parametr do rozkazu.

Zwraca:
  Zwracany jest uchwyt do nowego obiektu rozkazowego lub NULL w przypadku błędu

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

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 POS_CreateRequest POS_CreateRequest który nie jest automatycznie usuwany w ytybach SPOOLSPECIAL i AUTOCLEAR.

Parametry:

  | hRequest | Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)

POSNET_API unsigned long __stdcall POS_GetRequestAge | ( | POSNET_HANDLE | hRequest | ) |

Wiek rozkazu - czas jaki upłynął od wywołania 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.

Parametry:

  | hRequest | Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)

POSNET_API POSNET_STATUS __stdcall POS_GetRequestCommandID | ( | POSNET_HANDLE | hRequest,
|  | char * | retCommand |
| ) |  |  |

Pobierz numer polecenia, który został użyty przy tworzeniu obiektu.

Parametry:

  | hRequest | Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)
  | retCommand | Bufor znakowy, w którym zostanie umieszczona nazwa polecenia

Zwraca:
  Status wykonania rozkazu

POSNET_API unsigned long __stdcall POS_GetRequestCommandSerial | ( | POSNET_HANDLE | hRequest | ) |

Pobierz numer seryjny rozkazu.

Parametry:

  | hRequest | Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)

Zwraca:
  Token (numer seryjny) powiązany z rozkazem

POSNET_API POSNET_STATE __stdcall POS_GetRequestState | ( | POSNET_HANDLE | hRequest | ) |

Zwróć stan rozkazu.

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

Parametry:

  | hRequest | Uchwyt rozkazu (żądania wychodzącego lub odpowiedzi z drukarki)

POSNET_API POSNET_STATUS __stdcall POS_PostRequest | ( | POSNET_HANDLE | hRequest,
|  | unsigned char | mode |
| ) |  |  |

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.

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

Parametry:

  | hRequest | Uchwyt rozkazu
  | mode | Wybór trybu wysyłania rozkazu Tryby wysyłania rozkazów

POSNET_API POSNET_HANDLE __stdcall POS_RequestDevice | ( | POSNET_HANDLE | hRequest | ) |

Funkcja służy do pobrania uchwytu urządzenia związanego z rozkazem.

Parametry:

  | hRequest | Uchwyt rozkazu

Zwraca:
  uchwyt lokalny urządzenia lub NULL w przypadku błędu gdyż nie można ustalić adresata rozkazu.

POSNET_API POSNET_STATUS __stdcall POS_WaitForRequestCompleted | ( | POSNET_HANDLE | hRequest,
|  | unsigned long | timeout |
| ) |  |  |

Czekaj na zakończenie rozkazu.

Funkcja powoduje zatrzymanie (uśpienie) wołającej ją aplikacji do momentu zmiany stanu rozkazu na POSNET_RSTATE_COMPLETED lub POSNET_RSTATE_ERRCOMPLETED lub upłynięcia czasu wskazanego przez parametr timeout.

Parametry:

  | hRequest | Uchwyt rozkazu
  | timeout | Czas w ms na jaki ma aplikacja być uśpiona. 0 oznacza natychmiastowy powrót

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