Funkcje API - wstęp

Zestaw funkcji API systemu CDN XL pozwala na wykonanie wielu użytecznych zadań, bez konieczności uruchamiania samego systemu. W zależności od tego w jakim języku programowania (Visual Basic, C#) funkcje API zostały zaimplementowane, mamy możliwość tworzenia zewnętrznych programów wykonujące określone zadania bądź komunikację pomiędzy CDN XL a innym systemem. Funkcje API są również bezpieczniejsze niż wykonywanie gotowych zapytań SQL bezpośrednio na bazie danych.

Do najważniejszych i najczęściej wykorzystywanych funkcji API systemu CDN XL należą: XLLogin, XLPolaczenie, XLOpisBledu, XLLogout. Generalnie zasada korzystania z funkcji API polega na wywołaniu danej funkcji i podaniu jej jako argument odpowiednio przygotowanej struktury danych. Po poprawnym wykonaniu funkcji, ta sama struktura będzie zawierać dodatkowe (żądane) informacje. Przykład wywołania funkcji XLLogin w języku C#:

cdn_api.XLLoginInfo_17 xlLoginInfo = new cdn_api.XLLoginInfo_17();
loginInfo.ProgramID = "program korzystający z funkcji api";
loginInfo.Winieta = -1;
loginInfo.Wersja = wersja;
Int32 idSesji = 0;
Int32 wynik = cdn_api.cdn_api.XLLogin(loginInfo, ref idSesji);

W przykładzie strukturą danych przekazywanych do funkcji jest obiekt xlLoginInfo. Przed przekazanie do funkcji musi on zawierać dwa obowiązkowe parametry: nazwę programu wywołującego funkcję logowania oraz numer wersji używanych funkcji API. Parametr Winieta określa, która formatka powitalna pokaże się przed wywołaniem okna logowania do systemu (-1 oznacza brak formatki powitalnej). Po poprawnym wykonaniu funkcji w parametrze idSesji zwracany jest identyfikator sesji, który należ używać przy wywoływaniu kolejnych funkcji.

Po zalogowaniu możliwe jest pobranie informacji o istniejącej sesji. Służy do tego funkcja XLPolaczenie. Wywołujemy ją analogicznie jak poprzednio.

cdn_api.XLPolaczenieInfo_17 xlPołączenieInfo = new cdn_api.XLPolaczenieInfo_17();
połączenieInfo.Wersja = 17;
cdn_api.cdn_api.XLPolaczenie(połączenieInfo);
String connStr = połączenieInfo.ConnectString;

Najbardziej użytecznym elementem struktury xlPołaczenieInfo jest ConnectString, zwracający parametry połączenia do bazy danych.

Do wylogowania z systemu służy funkcja XLLogout, która przyjmuje tylko jeden argument: identyfikator sesji uzyskany po poprawnym zalogowaniu. Każda z funkcji API zwraca liczbę całkowitą informującą o wyniku jej działania. Wartość 0 (zero) oznacza, że funkcja zakończyła się powodzeniem. Inne wartości oznaczają błąd lub ostrzeżenie. Dobrym sposobem obsługi zwracanych wyników jest użycie funkcji XLOpisBledu, która zamienia kod komunikatu na jego słowny opis. Parametrami obowiązkowymi jakie należy przekazać do tej funkcji są numer funkcji, która zwraca wynik oraz wersja API. Przykład funkcji obsługującej wyniki zwracane przez funkcje API:

private void OpisBłęduAPI(Int32 wersja, Int32 numerFunkcji, Int32 numerBłędu)
{
cdn_api.XLKomunikatInfo_17 xLKomunikatInfo_17 = new cdn_api.XLKomunikatInfo_17();
xLKomunikatInfo_17.Funkcja = numerFunkcji;
xLKomunikatInfo_17.Blad = numerBłędu;
xLKomunikatInfo_17.Wersja = wersja;
cdn_api.cdn_api.XLOpisBledu(xLKomunikatInfo_17);
MessageBox.Show(this, "Funkcja: " + numerFunkcji + "\nBłąd: " + numerBłędu + "\nKomunikat: " + xLKomunikatInfo_17.OpisBledu,
"Błąd funkcji API", MessageBoxButtons.OK, MessageBoxIcon.Error);
}

Funkcja ta wyświetla okno dialogowe z informacją o funkcji i błędzie, który ta zgłosiła. Należy tu pamiętać, że parametr numerFunkcji nie jest nazwą, a odpowiednio zdefiniowanym numerem funkcji API. Przykładowo XLNowyDokumentMag ma numer 8, a XLZamknijDokumentMag to numer 11. Szczegółowe informacje o numerach poszczególnych funkcji dostępne są w dokumentacji API.