Cardinal Számítástechnikai Kft. H-1025 Budapest, Pusztaszeri út 91. Tel.: (36) 1 345-79-80 Fax: (36) 1 345-79-90
KIS KELER Internetwork System
KELER Zrt. Az STP KID megvalósítása V6.2.2
© Cardinal Számítástechnikai Kft., 2005-2013.
STP KID
2
Tartalom 1.
BEVEZETÉS ...................................................................................................................................6
2.
KELER IGÉNYEK.........................................................................................................................7 SOAP TECHNOLÓGIA BEVEZETÉSE ............................................................................................7 TELJES KÖRŰ SZOLGÁLTATÁS KIDOLGOZÁSA ...........................................................................7 AUTOMATIZÁLT ELÉRÉS KIDOLGOZÁSA ....................................................................................8 REQUEST-RESPONSE TECHNIKA ALKALMAZÁSA .......................................................................8 VÉGFELHASZNÁLÓI AZONOSÍTÁS MEGSZÜNTETÉSE..................................................................9
2.1. 2.2. 2.3. 2.4. 2.5. 3.
STP KID ..........................................................................................................................................9 KID RÉSZ ......................................................................................................................................9 ÜGYFÉL RENDSZERÉBE INTEGRÁLHATÓ RÉSZ .........................................................................11
3.1. 3.2. 4.
BIZTONSÁG.................................................................................................................................12
5.
ÜTEMEZÉS ..................................................................................................................................14
6.
AZ STP KID ÜZLETI FUNKCIONALITÁSA .........................................................................15
7.
ÜZEMELTETÉS ..........................................................................................................................15 AZ STP KID BEÁLLÍTÁSA, ÜZEMELTETÉSE .............................................................................15
7.1. 8.
AZ STP KID SOAP PROTOKOLL ...........................................................................................16
8.1. 8.2. 8.3. 8.4. 8.5. 8.6. 8.7. 8.8. 8.9. 8.10. 8.11. 8.12. 8.13.
BEVEZETÉS .................................................................................................................................16 ÁLTALÁNOSSÁGOK AZ STP SOAP PROTOKOLLRÓL ...............................................................17 TESZT PROGRAM A SOAP PROTOKOLLHOZ ............................................................................18 LOGIN MŰVELET ........................................................................................................................20 LOGOUT MŰVELET .....................................................................................................................20 REMOTELOGIN ...........................................................................................................................20 REMOTELOGOUT .......................................................................................................................21 CHANGELOGINPASSWORD ........................................................................................................21 CHANGESIGNATUREPASSWORD ................................................................................................22 IMPORTORDERPACK ...............................................................................................................22 SIGNORDERPACK ....................................................................................................................23 SENDORDERPACK ....................................................................................................................24 EERTOZSDEIKOTESEK ...........................................................................................................24
Készült: 2013.12.09.
STP KID 8.14. 8.15. 8.16. 8.17. 8.18. 8.19. 8.20. 8.21. 8.22. 8.23. 8.24. 8.25. 8.26. 8.27. 8.28. 8.29. 8.30. 8.31. 8.32. 8.33. 8.34. 8.35. 8.36. 8.37. 8.38. 9. 9.1. 9.2. 9.3. 9.4. 9.5. 9.6. 9.7.
3
ORDSTATEXPORT ....................................................................................................................25 GETPARTNERORDERS .............................................................................................................25 GETEERNONPAIR ...................................................................................................................26 GETOTCNONPAIR ...................................................................................................................26 GETORDERSTATUS ..................................................................................................................27 GETNOTIFYCATALOG .............................................................................................................27 GETNOTIFY ..............................................................................................................................28 GETCORPCATALOG .................................................................................................................28 GETCORP ..................................................................................................................................29 GETBALANCE ...........................................................................................................................29 EXPORTBALANCE ....................................................................................................................30 GETNOTICECATALOG .............................................................................................................30 GETNOTICE ..............................................................................................................................31 GETSTATEMENTCATALOG......................................................................................................31 GETSTATEMENT.......................................................................................................................32 EXPORTSTATEMENT ................................................................................................................32 GETADVICECATALOG .............................................................................................................33 GETADVICE ..............................................................................................................................33 EXPORTADVICE........................................................................................................................34 ISLOGGEDIN .............................................................................................................................34 GETMEMBERINQUIRIES ..........................................................................................................35 GETGIROCREDITS ..................................................................................................................35 GETRATE ..................................................................................................................................36 EXPORTKELERDATA .............................................................................................................36 EXPORTORDER.........................................................................................................................37
AZ STP KID API KLIENS RÉSZE ............................................................................................38 BEVEZETÉS .................................................................................................................................38 TELEPÍTÉS ..................................................................................................................................38 TÍPUSOK ÉS STÁTUSZKÓDOK .....................................................................................................39 SESSION MŰVELETEK .................................................................................................................39 KÉRÉS ELKÜLDÉS, VÁLASZ FOGADÁS .......................................................................................40 KÉRÉS ELKÜLDÉS, VÁLASZ FOGADÁS WINDOWS KÖRNYEZETBEN ........................................40 KÉRÉS ELKÜLDÉS, VÁLASZ FOGADÁS UNIX KÖRNYEZETBEN .................................................42
Változások: 2005.11.17. Unix kliens bevezetése miatt az STP API felületének megváltoztatása. A Windows és Unix környezetben az API pontos leírása. 2005.12.05. ImportOrderPack SOAP felület módosítása. 2005.12.08. ELSRV tesztprogram kiegészítése %FILE
% karaktersorozatok speciális kezelésére, file-ok base64 kódolásának bevezetése. 2006.03.20. Pontosítások az EÉR Tőzsdei kötések, Megbízás státuszok és Partner megbízások lekérdezés adatszerkezeteiben. 2006.03.20. Az STP.DOC v4.0 (2005.11.24.) és v4.3 (2006.03.20.) közötti eltérések összegyűjtése: Változtak a ChangeLoginPassword és ChangeSignaturePassword műveletek státuszkódjai, két új érték került bevezetésere: NEWPWDFAIL, CHANGEFAIL. Készült: 2013.12.09.
STP KID
4
Változott az ImportOrderPack művelet paraméterezése. Az OrderPackId nem paraméter, hanem az import eredményeként visszaadott kód. Három új művelet került bevezetésre: EERTozsdeiKotesek, OrdStatExport és GetPartnerOrders 2006.03.21. Az STP műveletek leírásának bővítése, az STP és a KID program funkcióinak összekapcsolása a könnyebb érthetőség miatt. 2006.10.06. Új STP funkciók: EÉR ill. OTC páratlan tételek lekérdezése. Ép. transzfer ill. OTC megbízások törlése, prioritás változtatása. A 5.02-77-es KID-del az import formátumok összehangolása (Lásd: KIDIO.DOC), az új státuszok továbbküldése 2007.04.10. Az STP kommunikáció javítása: Az STP KID program és az stp.dll közötti kommunikáció bizonyos körülmények között megállt. A javítás a KID program 5.02-80-as verziójában, és az stp.dll 1.0.0.1 verziójában történt meg. Az stp.dll-be verziószám került, ami a Windows Explorerrel is megnézhető (egér jobbfül a file-on, tulajdonságok, verziószám). A korábbi, hibás stp.dll nem tartalmazott verzió információt. A javítás nem érinti az STP mechanizmus működését, az stp.dll-t ugyanúgy kell használni, mint eddig. 2007.07.31. Az STP kommunikáció javítása: Az STP KID program és az stp.dll közötti kommunikáció adott körülmények között kiesett a szinkronból, ami a kapcsolat megállásához vezetett. A javítás a KID program 5.02-81-es verziójában, és az stp.dll 1.0.0.2 verziójában történt meg. Javításra került az API felületen a callback függvény visszatérési értékének típusa, ami STPStatus-ról CBStatus-ra módosult. 2007.08.08. Az STP kommunikáció javítása: Az stp.dll modulban a kommunikáció ismételten képes volt megállni (beragadni). A megállás oka a Windows socket előírás szerinti kezelése volt. A javítás figyelmen kívül hagyja a socket írás blokkolódását, mindenképpen újraírást hajt végre, aminek következtében a megállás egy idő után megszűnik, és a kommunikáció továbbmegy. A javítás az stp.dll 1.0.0.3 verziójában történt meg. 2007.08.14. Az STP kommunikáció javítása: Az stp.dll modulban nem megfelelő hívási konvencióval voltak a kiajánlott műveletek definiálva, ami bizonyos körülmények esetén a kliens alkalmazás hibás működéséhez és azonnali kilépéshez (elszállás) vezetett. A javítás az stp.dll 1.0.0.4 verziójában történt meg. 2007.08.17. Az STP API felület visszajavítása került (a korábbi javítás egy félreértés miatt született), a callback függvény visszatérési értékének típusa ugyanaz lett, mint a 2007.07.31-ei módosítás előtt volt, vagyis STPStatus. A javítás az stp.dll 1.0.0.5 verziójában történt. 2007.12.17. Az ImportOrderPack függvény kiegészült egy új paraméterrel (PackName). Új STP függvények kerültek bevezetésre: GetOrderStatus, GetNotifyCatalog, GetNotify. 2008.07.02. Az EERTozsdeiKotesek függvény kiegészült egy új (opcionális) paraméterrel (Type). 2009.11.23. Új STP függvények kerültek bevezetésre: GetCorpCatalog, GetCorp. A CB megbízások (Helyi piacos ügylet, Nem helyi piacos ügylet, Részvétel társasági eseményben) STP-n keresztül importálhatók (és beküldhetők). 2013.11.18. Új STP függvények kerültek bevezetésre: GetBalance, ExportBalance, GetNoticeCatalog, GetNotice, GetAdviceCatalog, GetAdvice, ExportAdvice, GetStatementCatalog, GetStatement, ExportStatement, IsLoggedIn, GetMemberInquiries, GetGIROCredits, GetRate, ExportKELERData, ExportOrder. A GetNotifyCatalog bővült egy Készült: 2013.12.09.
STP KID
5
új paraméterrel. Az összes megbízás (amelyhez van import) STP-n keresztül importálható (és beküldhető) lett.
Készült: 2013.12.09.
STP KID
6
1. Bevezetés Ezt a dokumentációt a KELER Rt. megrendelése alapján a Cardinal Kft. készítette. A dokumentáció tartalmazza az KELER Rt. KIS/KID rendszerében az STP KID program kialakításának tervét. Az STP (straight-through processing, magyarul azonnal-végrehajtott feldolgozás, vagy automatizált folyamat) azt jelenti, hogy egy adott rendszerből különböző tranzakciókat, lekérdezéseket indítva, az azokra adott válaszok azonnal, külön emberi beavatkozás nélkül, automatikusan megérkeznek. Az STP rendszerekben a legelőször tisztázandó, hogy pontosan milyen szereplők vannak, és közülük kik tekinthetőek végpontoknak. A tranzakciók és válaszaik mindig végpontok között közlekednek. A KELER Rt. 1996-ban elindította a KIS rendszert, ami azóta is működik. A KIS a KELER Rt. ügyfelei részére egy elektronikus kommunikációs csatorna, amin keresztül a KELER szolgáltatásainak döntő többsége elérhető. A KIS rendszer egyedi fejlesztésű programokból áll, amik speciálisan a KELER Rt. igényeit szolgálják ki. A rendszer jelenleg két fő komponensből áll: a KELER Rt-nél üzemeltett központi számítógépből, a rajta futó szerver programmal (KERNEL), és az ügyfeleknél telepített terminál (KID) programokból. A KID és a KERNEL kliens-szerver kapcsolatban áll egymással. A KERNEL a központi funkciókat úgy látja el, hogy egyrészt a KELER Rt. belső elszámoló rendszereivel áll kapcsolatban, másrészt pedig a KID programokkal. Az elszámoló rendszerekkel folyamatos, real-time kapcsolatban áll, míg a KID programok felé kiszolgáló szerverként működik. Amikor az ügyfeleknek szüksége van rá, a KID program segítségével kapcsolódni tudnak a KERNEL-hez, és azon keresztül a KELER Rt. elszámoló rendszereihez. A jelenlegi architektúrában a végpontokat a KID programok jelentik, mivel automatikus programprogram kapcsolatban csak ezek állnak a KELER rendszereivel. A KELER Rt. célja, hogy a jelenlegi végpontot a KID programon keresztül kiterjesszük az ügyfél saját rendszeréig. A KELER Rt. ezzel egy magasabb szintű szolgáltatást kíván megvalósítani, amit a pénzpiaci ügyletek gyors feldolgozása és az ügyfelek ezirányú igényei is indokolnak. A KELER Rt. esetében az STP KID egy olyan rendszer kialakítását jelenti, ahol a KELER Rt. ügyfelei a saját rendszereikben indíthatják el a tranzakcióikat, amelyek aztán a KIS rendszeren keresztül, elektronikusan jutnak el a KELER elszámoló rendszereihez. Az elszámoló rendszerekben többnyire azonnal megtörténik a tranzakciók feldolgozása. A feldolgozott tranzakciókról a KELER a KIS rendszeren keresztül, közvetlenül az ügyfelek saját rendszereibe juttat el (pl. státusz) információt. A KID program összekapcsolása az ügyfelek saját rendszereivel jelenleg import-export file-okon keresztül, emberi beavatkozással történik. Az ügyfél a saját rendszeréből egy, előre megadott formátumú, file-ba kiexportálja a megbízásait. A file-t beimportálja a KID-be, aláírja, majd elküldi a KELER-nek. A KELER feldolgozza, és a másnapi kivonatban visszaadja a könyvelt tételeket, amit az ügyfél a KID-en letölt, majd kiexportál egy, szintén előre rögzített formátumú, file-ba. Végül a kiexportált file-t importálja az ügyfél a saját rendszerébe. Az eddigi feldolgozási folyamatban túl sok az emberi tényező, és a tranzakciók feldolgozási sebességéhez képest lassú a visszajelzés. A KELER rendszerei a másnapi kivonatnál sokkal korábban is adnak vissza információkat, amiket jelenleg még nem lehet minden esetben átvinni az ügyfelek rendszereibe még az export funkcióval sem.
Készült: 2013.12.09.
STP KID
7
Az ideális megoldás az lenne, ha a KELER KIS rendszerének az ügyfélnél lévő komponense az ügyfél saját rendszereibe integrálható lenne. Az ügyfél mindig csak a saját rendszerében dolgozna, a KIS „csak” az összeköttetést biztosítaná az ügyfél és a KELER között. A KID programot nem lehet egyszerűen eldobni, vagy lecserélni egy STP KID-re, hiszen vannak olyan, többnyire kis ügyfelek, akiknek nincs saját rendszerük, ezért igényt tartanak az eredeti KID-re. A magasabb szintű szolgáltatás nyújtása érdekében a KID program mellett kell lehetőséget biztosítani, az arra igényt tartó ügyfelek részére, hogy saját rendszereiket integrálhassák a KELER rendszereihez.
2. KELER igények Jelen dokumentáció a KELER Rt. és a Cardinal Kft. korábbi egyeztetéseinek során kialakult megvalósítási koncepció alapján készült. A KELER Rt. legfontosabb elvárásai az STP KID program kialakításával kapcsolatban a következők: a SOAP technológia bevezetését a KID teljes körű szolgáltatásához automatizált elérés kidolgozását request-response technika alkalmazása végfelhasználói azonosítás megszűntetését
2.1.
SOAP technológia bevezetése
A KELER a Cardinal javaslatát elfogadva úgy döntött, hogy az ügyfél rendszere és az STP KID közötti kommunikáció a SOAP (simple object access protocol) segítségével történjen. Az ügyfelek jelenleg a saját rendszereikből az adatokat fix formátumú text fileokkal adják át, és veszik vissza. A teljes körű XML átállás az ügyfelek részére esetleg túl nagy befektetést (erőforrás ráfordítást) jelentene, ezért, bár a kommunikáció SOAP lesz, ahol a SOAP üzenet XML formátumú, alapvető követelmény, hogy a jelenlegi fix formátumú adatok is átadhatóak legyenek. A későbbiek során a jelenlegi fix formátumról folyamatosan át lehet térni az XML formátumra. Az új funkciók kialakítása során mindig az adott funkció és környezete fogja eldönteni, hogy szükséges-e fix formátumú adatszerkezet kialakítása, vagy annak kihagyásával, egyből az XML formátum készül-e el. Maga a SOAP kommunikáció csak egy keretrendszert takar, amiben az üzenetek szabványos formában írhatók le ill. kezelhetők. Az üzenetek tartalma tetszőleges lehet: akár XML, akár bármilyen más formátum.
2.2.
Teljes körű szolgáltatás kidolgozása
A KID programban jelenleg az import-export funkciókkal lehetséges más rendszerekből adatokat bevinni ill. kinyerni. A KID import-export lehetőségei nem fedik le a KID teljes funkcionalitását. A képernyőkön több információ érhető el, mint a program kapcsolatot jelenleg megvalósító import-export funkciókon keresztül. Az importálás – a KID programba adatot bevinni – a megbízások többségére működik, de exportálni jelenleg csak a kivonatjellegű információkat (kivonatok, egyenlegek, gyakran használt törzsadatok) és státuszokat lehet. Nincs export lehetőség a megbízásokra, a különböző KELER értesítő üzenetekre.
Készült: 2013.12.09.
STP KID
8
A teljes körű szolgáltatás kidolgozása azt jelenti, hogy ami információt a felhasználók a képernyőn ill. nyomtatásban elérhetnek, azt biztosítani kell program interfésszel is. Az utóbbi években ebben az irányban haladtunk, bővült az importálható/exportálható funkciók halmaza, másrészt az STP KID is ezek egyre nagyobb részét támogatja. A 6.02-02-es verzióban az STP már az összes import/export formátumot támogatja, ami a KID-ben benne van.
2.3.
Automatizált elérés kidolgozása
A KID jelenleg egy grafikus felhasználói felülettel rendelkező program, amiben az egyes funkciók egy kezelő személy folyamatos irányítása mellett vehetők igénybe. A KID-nek ilyen módon még nincs program interfésze, tehát külső programmal nem lehetséges a KID „meghajtása”, adatok átadása, elkérése. A KELER Rt. kérésére a KID programhoz elkészült egy újabb komponens, ami az STP szolgáltatásokat ellátja. Ez az új komponens egy tetszőleges, akár a KIS rendszeren kívüli, program számára is elérhetővé teszi majd a KELER által a KID-en nyújtott szolgáltatásokat. A KID-en történő módosításokon túl természetesen az ügyfelek rendszereiben is szükség lesz fejlesztésekre, ha az STP szolgáltatást igénybe szeretnék venni. Az STP KID programhoz tartozni fog egy azon kívül álló olyan program komponens (rutinkönyvtár), ami az ügyfelek rendszereibe közvetlenül beintegrálható, és biztosítja a megbízható, viszont technikailag alacsony szintű program-program kapcsolatot. A rutinkönyvtárat a Cardinal Kft. készíti el, és az STP szolgáltatást igénybe vevő ügyfelek rendelkezésre bocsátja, így ők mentesülnek a programozói munkának azon szintjétől, ami a szolgáltatás igénybevételéhez elengedhetetlenül szükséges alapfunkciókat látja el, és az ügyfeleknél feleslegesen sok erőforrás ráfordítást igényelne, ha ezt is nekik kellene elkészíteni. A rutinkönyvtár egyben biztosítja, hogy a különböző ügyfeleknél az STP interfész alapfunkcióinak megvalósítása nem lesz más és más, és a közös komponens karbantartása, üzemeltetése várhatóan kisebb feladatot ró mind az ügyfélre, mind pedig a KELER Helpdeskre.
2.4.
Request-response technika alkalmazása
A KIS rendszer jelenleg alapvetően úgy működik, hogy a KELER Rt. szolgáltatásait igénybe vevő ügyfelek az egyes funkciók elindítását ők maguk kezdeményezik, majd várnak a válaszra. Ezt a technológiát request-response (kérés-válasz) alapú működésnek nevezik, ami nagyban eltér az eseményvezérelt működéstől. Amikor az ügyfeleknek szüksége van valamelyik szolgáltatásra, akkor a KID programban elindítanak egy kérést. A kérés eljut a KERNEL-hez, ami feldolgozza azt, majd a választ visszaküldi a KID-nek. A feldolgozás során a KERNEL a KELER-ben előre rögzített folyamatoknak megfelelően dönti el, hogy egy kérést saját maga válaszol-e meg, vagy a KELER elszámoló rendszereihez kell fordulnia. A kérések feldolgozása azonnal elkezdődik, a válaszokat a KID mindig megvárja. Amíg egy kérés nem lett megválaszolva, addig újabb kérés nem indítható. A kérés-válasz párok tehát szinkron módon működnek. A KID programban kérés-válasz alapon működik pl. a megbízások beküldése, a kivonatok lekérésre. A request-response mellett a másik, az elsőtől nagyban eltérő, működési mód az eseményvezérelt működés. Ebben az esetben a folyamatot nem a felhasználó ill. a KID indítja el, hanem a KELER elszámoló rendszerei vagy a KERNEL. Ez a KID programban egy eseményként jelenik meg, ami azt jelenti, hogy bármikor jöhet egy üzenet, amit a KELER-ből küldtek. Az eseményvezérelt működést abban az esetben célszerű használni, ha olyan információra várunk, amiről nem lehet előre tudni, hogy mikor áll majd rendelkezésre. Az eseményvezérelt működési mód ilyen esetben kevesebb erőforrást igényel a kiszolgáló Készült: 2013.12.09.
STP KID
9
rendszerektől, mintha folyamatosan a „van-e már ilyen adat” típusú kéréseket kellene megválaszolni. Az eseményvezérelt működésre külön fel kell készülni, ugyanis egy bejövő üzenetet (eseményt) többnyire azonnal le kell kezelni. A KID programban eseményvezérelten működik pl. a megbízások státusz bejegyzése, a partner tranzakciók kezelése. Az STP KID program esetén mindkét működési módot támogatni kell úgy, hogy az ügyfeleknek lehetősége legyen a KID programban még eseményvezérelten történő feldolgozási folyamatokat is request-response módon lekérni. Ez azt jelenti, hogy az ügyfél igényeitől függően biztosítani kell pl. a megbízási státuszok lekérdezhetőségét is mindamellett, hogy esetleg az ügyfél saját rendszerét eseményvezérelten is értesíteni kell, egy státusz megváltozásakor.
2.5.
Végfelhasználói azonosítás megszüntetése
A KID programot a felhasználók csak akkor használhatják, ha előtte azonosították magukat. A felhasználó a KIS rendszerben mindig egy tényleges, természetes személyt azonosított. A felhasználó azonosítása egy felhasználói azonosító és egy hozzá tartozó titkos jelszó megadásával történik. Az azonosítás után a KID program minden egyes elvégezett műveletet az azonosított személy nevében végez el. Az STP KID programban a felhasználó már nem feltétlen egy természetes személy. Amennyiben az ügyfél meg tudja oldani az átjárhatóságot, úgy biztosítani kell, hogy az STP KID átvegye az ügyfél saját rendszerétől, hogy a műveleteket melyik személy akarja végrehajtatni, és annak nevében (jogaival, lehetőségeivel) járjon el. Ha az ügyfél a saját hatáskörében (pl. szabályozással) megoldja a felhasználó azonosításának kérdését, és a saját rendszerét egy zárt, auditált egységnek elfogadja a KELER, akkor lehetséges az is, hogy az STP KID programban már nem jelenik meg felhasználóként természetes személy. A KIS rendszerben a végfelhasználó fogalmát, és annak azonosítását megszüntetni nem fogjuk, legfeljebb az STP KID programba az ügyfél saját rendszerének egy komponense (tehát egy program) fog belépni egy technikai azonosítóval. Ebben az esetben az STP KID a műveleteket ezen technikai azonosító mögött lévő program nevében fogja elvégezni. A KELER-ben ilyen módon nem az ügyfélnél dolgozó természetes személyek lesznek beazonosítva, hanem csak maga az ügyfél (jogi személy). A rendszer használatával kapcsolatos szabályozási és jogi kérdéseket a KELER Rt. és az ügyfele között kötött STP használati szerződés fogja meghatározni.
3. STP KID Az STP KID programot a jelenlegi KID programból alakítjuk ki úgy, hogy egy STP funkciókat ellátó program komponenst, mint a KID kibővítését készítjük el. A STP KID megoldás két fő részből áll: KID program STP funkciót ellátó része ügyfél rendszerébe integrálható, KIS-en kívüli rész
3.1.
KID rész
A KID program STP funkciókat ellátó része egy kiegészítés a KID-hez. A STP KID továbbra is egy grafikus felhasználói felülettel rendelkező ügyfélprogram, ami képes ugyanúgy Készült: 2013.12.09.
STP KID
10
is működni, mint egy hagyományos KID. Az eltérés a KID-hez képest annyi, hogy az STP KID-nek van program interfésze is, tehát egy tetszőleges külső programmal kapcsolódni lehet hozzá. A kapcsolat kiépítését mindig a külső programból (pl. az ügyfél backoffice rendszere) kell kezdeményezni, az STP KID magától nem fog kapcsolatot létesíteni semmilyen más programmal sem. A kommunikáció az STP KID és az ügyfél rendszere között TCP/IP alapú SOAP lesz, tehát az STP üzemeltetéséhez az ügyfelek részéről a TCP/IP megléte szükséges. Az ügyfél által tetszőlegesen megválasztható TCP/IP portot fogja figyelni a KID program azon a munkaállomáson, ahol az STP funkcionalitást igénybe szeretnék venni. Az STP KID kizárólag csak ezen a porton érkező, előre definiált protokollnak megfelelő kéréseket fog kiszolgálni. Amennyiben az STP KID-et futtató munkaállomás számítógépes hálózati szempontból „messze” van az STP kérést indító (backoffice) rendszertől, akkor az ügyfélnek kell gondoskodnia arról, hogy a TCP/IP kommunikáció az adott porton átjárható legyen a különböző hálózati biztonságot szolgáló eszközökön (pl. routerek konfigurálásra). A SOAP üzenetek formátuma XML, de a rendszer lehetőséget fog adni arra, hogy a jelenleg is használatban lévő fix formátumú import-export file-ok szerkezetével teljesen megegyező adatokat is átadhassanak, ill. a válaszban visszakérhessenek az ügyfelek. A jelenlegi fix formátumú adatok speciális kódolást (base64) kapnak, hogy XML-be beágyazhatóak legyenek. Első lépésben az STP KID a jelenlegi fix formátumot fogja támogatni. Ennek kiterjesztése (lecserélése) XML-re folyamatosan fog megtörténni. Új funkciók bevezetésénél XML formátum mindig fog készülni, a új fix formátum bevezetéséről a KELER az ügyfél igények figyelembevételével fog dönteni. Az STP KID úgy lett kialakítva, hogy a lekérdezésekben megadható a válasz várt formátuma is. A jelenlegi fix és XML formátum mellett ezzel lehetőséget adunk arra, hogy tetszőleges új formátumot is bevezethessen a KELER. Vannak ügyfelek, akik pl. a letöltött kivonatokat SWIFT formátumban szeretnék átvinni a saját rendszerükbe. Egy adott lekérdezés esetén a kérést indító választhat pár, előre meghatározott formátum között. Az XML formátum minden átadható ill. átvehető adathoz kell, a többi formátum megléte pedig az igényektől függ. A kapcsolatfelvételnek része a külső program (vagy a programot kezelő személy) azonosítása. Az STP KID a kapcsolatfelvételt kérőtől egy azonosítót (userid) és egy jelszót fog várni. Az azonosító megfelel a KIS rendszerben használt felhasználói azonosítónak, ami egy csoportkódból és egy rövid névből áll. Sikeres azonosítás után lehet további kéréseket indítani az STP KID felé. Az STP KID a jelszavakat és tévesztéseket pontosan úgy fogja kezelni, mint a KID. A kiépített kapcsolat session jellegű pontosan úgy, mint a KID-KERNEL viszonylatban. A kapcsolatban nincs timeout, tehát ha sokáig nem történik üzenetváltás, akkor sem bontja a kapcsolatot az STP KID. Az STP használat végén, ugyanúgy, mint a KID esetén a KERNELről, ki kell jelentkezni, meg kell szüntetni a kapcsolatot. Ha valamilyen okból a TCP/IP szinten megszakad a kapcsolat (pl. hálózatkiesés, valamelyik program kilép), akkor a megnyitott session automatikusan lezáródik, az újabb kérések végrehajtásához új kapcsolatfelvétel és azonosítás szükséges. Az STP KID funkciói kezdetben nem fognak kiterjedni a teljes KID funkcionalitásra. Első lépésként a jelenlegi import-export funkciók lesznek elérhetőek a jelenlegi fix Készült: 2013.12.09.
STP KID
11
formátumos állapotban pár, a működéshez elengedhetetlen adminisztrációs művelettel együtt. A teljes KID funkcionalitás kialakítása egy hosszabb folyamat. Az STP KID program tökéletesen illeszkedni fog a jelenlegi, hálózatban használt KID programokhoz. Nem szükséges az ügyfélnél újabb KID kialakítása pusztán az STP funkció igénybevétele miatt, elég az egyik munkaállomáson egy STP funkciót tartalmazó KID elindítása. Hálózatos működés esetén az eddigi KID és az STP KID közös adatbázist is használhat, tehát ha egy olyan adatot, amit a KID megőriz, már lekértek, akkor az STP felületen az azonnal hozzáférhető külön letöltés nélkül. Ez a működés csökkenti a KELER rendszerek terhelését. Az STP KID idővel az ügyfél igényei szerint támogatni fogja mind a request-response, mind pedig az eseményvezérelt működési módot. Első fázisban az STP KID-ben a requestresponse működés készült el, az eseményvezérelt működést ügyfél ill. KELER igény alapján a későbbiekben várható. A KID-ben eseményvezérelt működésű folyamatokhoz requestresponse működésű STP felület készült.
3.2.
Ügyfél rendszerébe integrálható rész
Az STP KID programhoz fog tartozni egy olyan rutinkönyvtár, ami az STP szolgáltatás igénybevételéhez szükséges alapműveleteket tartalmazza, és az ügyfél saját rendszereibe integrálható. A rutinkönyvtárat a Cardinal készíti az KID program STP komponensével együtt. A rutinkönyvtár alapműveletei a következő feladatokat látják el: TCP/IP szintű kommunikáció a rutinkönyvtár és az STP KID között azonosítási és titkosítási protokoll a TCP/IP felett SOAP protokoll a titkosított szint felett általános parancs (STP kérés kiadása, válasz megvárása) a SOAP felett A rutinkönyvtár az ügyfél (backoffice) rendszereit készítő fejlesztők felé kizárólag csak a legmagasabb szintű, általános parancs kiadásához szükséges felületet biztosítja. Az alacsonyabban lévő szinteket elfedi, az ügyfél fejlesztőinek ezekkel nem kell foglalkoznia. A rutinkönyvtár dokumentációját mind a KELER, mind az ügyfelek megkapják. Ez a dokumentáció több részből áll, és tartalmazza az alapműveletek leírását, az STP KID-en végrehajtatható STP kérések definícióival együtt. A dokumentáció alapvetően három fő részre osztható: alapműveletek leírása (a rutinkönyvtár és műveleteinek használata, illesztési, integrációs utasítások, lehetőségek, stb.) technikai STP kérések és válaszaik (pl. kapcsolatfelvétel, azonosítás, session nyitás, kijelentkezés, kérések és válaszok szerkezete, mező kitöltési és értelmezési útmutató) üzleti STP kérések és válaszaik (pl. forintátutalás megbízás átadása, T768 kivonat átvétele, kérések és válaszok szerkezete, mező kitöltési és értelmezési útmutató) A rutinkönyvtár alapműveleteire épített magasabb, üzleti logikát megvalósító szintek kialakítása már az ügyfél feladata, tehát a dokumentációban szereplő kérések alapján egy komplett üzleti folyamat (pl. forintátutalás készítése, kapcsolatfelvétel, azonosítás, forintátutalás átadása, forintátutalás hitelesítése, beküldése, megbízás státusz elkérése, státusz adminisztrálása a saját rendszerben) összeállítása, és megvalósítása nem a rutinkönyvtárra,
Készült: 2013.12.09.
STP KID
12
nem az STP KID-re, nem a KELER-re és nem a Cardinalra tartozik. A példában szereplő folyamat legelső és legutolsó része az ügyfél saját rendszerére hivatkozik, amiből látszik, hogy a folyamatok a legtöbb esetben túlmutatnak az STP KID határain. A végpont az ügyfél rendszere, esetleg azon túl az ügyfél partnere, megbízója. A rutinkönyvtár megvalósításához felhasznált technikai megoldások a lehető legkevesebbet feltételezik a felhasználás körülményeiről. Olyan alapvető szabványok megléte lesz csak szükséges, ami általában minden fejlesztői környezetben automatikusan teljesül: Microsoft Windows fejlesztői környezetben a rutinkönyvtár szabványos dll felületet fog biztosítani, amihez egy C nyelvű header file-t mellékelünk. Unix környezetben a rutinkönyvtár egy lefordított lib, és a hozzá tartozó C nyelvű header file. Amennyiben az ügyfélnek más, egyedi rendszere van, vagy a fenti megoldások közül egyik sem működik nála, a Cardinal Kft. munkatársai lehetőséget kérnek, hogy az ügyfél rendszerében az STP rutinkönyvtárat forráskódból lefordíthassák. Az ügyfélnél a Cardinal által készített forráskód nem maradhat, csak lefordított, futtatható (ill. más programokba szerkeszthető) program. A forrás nyelvből történő fordításhoz szabványos C++ fordítóra van szükség. A rutinkönyvtár fordításához használható pl. a GNU C++ fordító legalább 3.2 verziója. A rutinkönyvtár nem használ fel olyan technológiákat, amik további befektetéseket, költségeket, esetleg szakmai hozzáértést, külön üzemeltetést igényel az ügyfelek részéről (pl. külön adatbázis-kezelő, profitorientált cégek által készített speciális fejlesztőkörnyezet, egyéb, nem standard rutinkönyvtárak, stb.). A rutinkönyvtár felhasználási területét egyrészt a Cardinal Kft. és a KELER Rt. közötti, másrészt a KELER Rt. és ügyfele közt kötött szerződés szabályozza. A rutinkönyvtár kizárólag az STP KID megvalósítására használható.
4. Biztonság Mind az ügyfelek, mind a KELER Rt. részére nagyon fontos az STP KID, és az általa megvalósított kommunikáció biztonsága. Az STP KID-ben megvalósított kommunikációs protokoll az ügyfél (backoffice) rendszere (a rutinkönyvtár) és az STP KID között a következő feltételek mellett fog működni: a kommunikáció alapja TCP/IP egy előre, az ügyfél által szabadon választható TCP/IP porton keresztül a kommunikáció kezdetén egy session kiépítése során minden esetben szabványos kulcscsere történik Diffie-Hellman algoritmussal és véletlenszerűen választott kulcsokkal a kulcscsere után a kommunikáció a továbbiakban titkosított, szabványos AES (Rijndael) algoritmussal az AES algoritmusban használt kulcs mérete 128 bit a kommunikáció packet alapú, hibadetektáló algoritmussal biztosított a packetek biztonságos átvitele
Készült: 2013.12.09.
STP KID
13
az STP funkció használatához felhasználói azonosítás (userid és jelszó) szükséges, ami session-höz kötött a felhasználói azonosítás ugyanúgy kétféle lehet, mint képernyőn a KID programban: belépés az STP KID-be vagy bejelentkezés a KERNEL-re az STP KID belépés során a jelszót a KID ellenőrzi, harmadik sikertelen próbálkozás után a felhasználót kitiltja a rendszerből, ami a továbbiakban csak KERNEL bejelentkezéssel oldható fel KERNEL bejelentkezés során a jelszó ellenőrzése a KELER-ben történik, harmadik sikertelen próbálkozás esetén a felhasználó kitiltásra kerül, amit a továbbiakban csak KELER Adminisztrátor személy oldhat fel jelszavakat közvetlenül sem a KID, sem a KERNEL nem tárol, kizárólag csak a jelszavakból egyirányú függvénnyel képzett (digest) kódot a jelszó a KID programig kódolatlanul kerül átküldésre a korábban kiépített titkosított csatornán keresztül a bejelentkezési jelszó tetszőlegesen, bármikor megváltoztatható, akár az STP felületen keresztül is (jelenleg az angol ABC nagybetűi és számok használhatók, max. 12 karakterig) az STP-n átadott megbízások aláírás nélkül jutnak el a KID programba a korábban kiépített titkosított csatornán az STP-n átadott megbízásokra a KID program pontosan azokat az ellenőrzések fogja elvégezni, amiket a kézi rögzítés során ill. a korábbi importnál is elvégzett (szintaktikai és szemantikai ellenőrzések, hogy a megbízások megfelelnek-e a KELER-ben hatályos üzletszabályzatnak) az STP-n átadott megbízásokat ugyanúgy kell aláírni (digitális aláírással ellátni), mint ahogyan azt korábban a felhasználók képernyőn is tették: az aláíráshoz meg kell adni az aláíró felhasználói azonosítóját és egy külön, aláírási jelszót, az aláírás elvégezhető az STP-n keresztül is, aláírás nélkül megbízást a KELER nem fogad be az aláírási jelszót a KID program nem ellenőrzi, az aláírási jelszó hiba csak a KELERbe történő beküldés során fog kiderülni az aláírási jelszó ugyanúgy, mint a bejelentkezési jelszó, bármikor tetszőlegesen megváltoztatható, akár az STP felületen keresztül is a megbízásokon lévő digitális aláírást a KID program készíti, szabványos, 512 bites RSA algoritmus használatával az aláíráshoz használt RSA kulcsot a KID program tárolja a megbízásokat az aláírás után ugyanúgy, mint korábban a felhasználóknak a képernyőn, külön be kell küldeni a KELER-be, automatikusan megbízásokat a KID nem továbbít a KELER felé, a beküldés elvégezhető az STP-n keresztül is a KELER-ből lekért adatokat az STP KID ugyanúgy fogja tárolni, mint eddig a KID program tette, titkosított file-okban
Készült: 2013.12.09.
STP KID
14
az STP KID programon keresztül, a KELER-ből lekért információk (értesítő üzenetek, egyenleg, számlakivonat) nem hitelesítettek digitális aláírással (kivéve a „Tőzsdekereskedési visszaigazolás” kivonatot) az STP-n keresztül érkezett kéréseket a KID program naplózza
5. Ütemezés A KIS rendszerben az STP funkcionalitás bevezetését több lépésben, fokozatosan vezeti be a KELER Rt. A folyamatos bevezetés több szempontból is előnyös mind az ügyfeleknek, mind a KELER-nek, mind a Cardinalnak. A hirtelen nagy változásokat az ügyfelek nehezen, csak lassan tudják követni. Az STP kialakítása mellett, azzal párhuzamosan, a KID programon folyamatos verziós fejlesztések is történnek, tehát a KIS szolgáltatása folyamatosan bővül. Az STP és a verziós feladatok fejlesztéseit össze kell hangolni. A lépcsőzetes kialakítás során az STP KID folyamatosan fog közelíteni a KELER Rt. eredeti igényeihez, miközben lehetőség nyílik arra, hogy az STP funkciók teljes elkészítése előtt már gyakorlati tapasztalatok álljanak rendelkezésre a felhasználásról, a működésről, módot adva ezzel az esetleges módosításokra, újragondolásra, és ezáltal az ügyfél igények jobb kiszolgálására. Az ütemterv a következő: STP infrastruktúra kialakítása (STP KID alapok, és rutinkönyvtár elkészítése, requestresponse működési mód és az alapvető működéshez szükséges, technikai kérések, válaszok kialakítása) Legfontosabb real-time funkciók (pl. OTC megbízások, megbízás státuszok) bevezetése a jelenlegi fix formátummal További lekérdezés (kivonatok, egyenlegek, üzenetek, törzsadatok) exportok bevezetése a jelenlegi fix formátummal További megbízás importok, státusz exportok bevezetése a jelenlegi fix formátummal SWIFT bevezetése (a meglévő SOAP kérésekhez a fix formátumok mellé a SWIFT formátum kialakítása) XML bevezetése (a meglévő SOAP kérésekhez a fix formátumok mellé a tényleges XML formátum kialakítása) Eseményvezérelt működési mód bevezetése (a meglévő request-response mellé) Teljes KID funkcionalitás lefedés az STP kapcsolódási felületen
Készült: 2013.12.09.
STP KID
15
6. Az STP KID üzleti funkcionalitása A STP KID program funkcionalitását a 6.02-01-es verziótól az összes alrendszerre kiterjesztettük és bővítettük. A következőket tartalmazza: Megbízások importja Kivonatok lekérdezése és exportja Társasági értesítők lekérdezése és exportja Egyenleg lekérdezések Partner értesítő üzenetek Beérkezett üzenetek/notify-ok lekérdezése Beérkezett üzenetek/értesítők lekérdezése Megbízás státuszok Prematching (validálás, felfüggesztés, felfüggesztés visszavonása) Alklíringtagi kötések
7. Üzemeltetés 7.1.
Az STP KID beállítása, üzemeltetése
A KID programban az STP szolgáltatás működése paraméterezhető, a KELER Rt. az ügyfeleivel kötött szerződés keretében az STP-t külön-külön szolgáltathatja. A KID programban az STP funkció igénybevételéhez első lépésben a szolgáltatást engedélyezni kell. Az engedélyezést KID programonként lehet beállítani a KELER-ben üzemeltetett Adminisztrátor program segítségével. Ezt a kapcsolót az ügyfél egymaga nem képes a KID-ben átállítani, ehhez mindenképpen KELER közreműködés szükséges. Az ügyfélnél telepített KID programok sokszor hálózatos üzemmódban futnak, tehát ugyanazt a programot többen is használhatják egyszerre egy időben. Az STP szolgáltatás miatt nem kell külön programot telepíteni (és karbantartani), az STP funkciót az eredeti KID programba teljesen beintegráltuk. Így pontosan ugyanaz a program szolgál az STP kiszolgálására, mint a hagyományos „kézi” használatra. Az STP szolgáltatás üzemeltetéséhez az ügyfélnél ki kell jelölni egy Windows-os munkaállomást, ahol a KID program STP üzemmódban fog futni. Ezen a munkaállomáson a KID munkakönyvtárában található INI-filet kell beállítani az STP-hez a következőképpen. Fel kell venni egy STP szekciót, és abban két bejegyzést kell elhelyezni: engedélyezés, és a kommunikáció portja. Pl.: [STP] ENABLE = “Y” PORT = 7000
Készült: 2013.12.09.
STP KID
16
Az ENABLE bejegyzés mondja meg a KID program számára, hogy a hálózatosan használt példányokból pontosan melyik fogja ellátni az STP funkciót. Amíg a KELER az STP szolgáltatást nem engedélyezi, addig az ENABLE bejegyzésnek nincs hatása. Egy KID programon belül kizárólag csak egy STP módú program indítható el. A PORT bejegyzés adja meg, hogy az STP KID melyik TCP/IP porton figyeli a hozzá történő kapcsolódást és adatforgalmat. A PORT értékét az ügyfél tetszőlegesen megválaszthatja, így a saját belső hálózatának működéséhez , szabályozásához igazítható az STP kommunikáció. A PORT bejegyzés default értéke: 7000, amit az INI-file bejegyzéssel felül lehet bírálni. A kiválasztott munkaállomáson az STP szolgáltatás működtetésének alapvető követelménye, hogy a Windows munkaállomásra a TCP/IP kommunikációt ellátó operációsrendszer alkotóelemek telepítve legyenek. (Ez a mai Windows munkaállomások esetén már a Windows telepítésével együtt automatikusan megtörténik. Régebbi Windows verziók esetén fordulhat elő, hogy a TCP/IP telepítését külön kell elvégezni. További információkat erről a Windows telepítő dokumentációjában lehet megtalálni.) A KELER engedélyezés és a kiválasztott munkaállomás INI-beállításai után a KID programot elindítva azonnal életbe lép az STP funkció, blokkolva ezzel a KID további összes funkcióját az adott munkaállomáson. Az STP működését a KID nyitóképernyőjén megjelenő ablak mutatja, amiben a KID folyamatosan vár egy külső parancsra. Az STP KID-be befutó összes kommunikáció időponttal és a végrehajtató azonosítójával együtt naplózásra kerül. Az STP napló bejegyzések a KID normál naplójába kerülnek be. Az STP szolgáltatás leállítását a nyitóképernyőn megjelent, az STP működést jelző, ablak bezárásával lehet megállítani. Az ablak bezárása után a KID program pontosan olyan állapotba kerül, mintha az STP nélkül éppen most indították volna el. Innentől kezdve „normál” KIDként használható a program a teljes funkcionalitásával együtt. Bizonyos időközönként (pl. nap végén) az STP KID programból teljesen is ki kell lépni. Ezzel biztosítható, hogy a KELER-ből küldött program update-ek érvényre juthassanak. Amennyiben szükséges (pl. upgrade miatt), elképzelhető, hogy a KELER az STP KID-ek üzemeltetését frissítési időszakban előírja és/vagy nem engedélyezi.
8. Az STP KID SOAP protokoll 8.1.
Bevezetés
Ez a fejezet részletesen tárgyalja az STP KID által használható műveleteket. A leírás tartalmazza a műveletek típusát, paramétereit, visszatérési értékeit és hatását az STP KID programban. Az STP KID program a Cardinal Kft. által készített Unicom kommunikációs modult használja az STP szerver funkciók ellátására. Azon alkalmazásoknak, amik az STP szolgáltatást igénybe szeretnék venni, szintén ugyanezen Unicom modul kliens részét kell használniuk, amihez egy egyszerű API felületet definiáltánk. Az STP KID folyamatosan bővül, ezért ebben a fejezetben leírt SOAP műveletek még bővülhetnek! Az STP KID program az Unicom kommunikációs rétegére ráépülve egy speciálisan az STP-re kialakított, struktúrájában SOAP protokollt használja. A SOAP keretrendszerről további információk a http://www.w3.org/TR/soap weboldalon találhatók.
Készült: 2013.12.09.
STP KID
17
Az Unicom modul API interface-ével a SOAP parancsokat file ill. memóriabuffer formájában lehet átküldeni az STP KID-nek. Az STP KID a válaszokat az Unicom modulon keresztül szintén file vagy memóriabuffer formájában fogja visszaküldeni.
8.2.
Általánosságok az STP SOAP protokollról
Az STP KID program a SOAP protokollon két kikötést használ: Egyrészt a SOAP-hoz tartozó XML tagek namespace-e kötelezően „soap” kell legyen, tehát az adat legelején szerepelnie kell a xmlns:soap=”http://www.w3c.org/2003/05/soap-envelope”
bejegyzésnek. Másrészt az XML formájú SOAP adat karakterkódolása kötelezően UTF-8 kell legyen, tehát az XML headerben szerepelnie kell az encoding=”UTF-8”
bejegyzésnek. Az STP KID a SOAP műveletek fejléc (SOAP header) részében a következő mezőket használja: Command: Megadja, hogy pontosan milyen parancs végrehajtását kéri a kliens az STP KID programtól. UniqId: A kliens által adott, tetszőleges értékű kód, ami a parancs egyedi azonosítására szolgál. Az STP KID program ezzel az azonosítóval csupán annyit tesz, hogy a válasz üzeneteiben visszaadja azt, amit kapott. Így a kliens fejlesztőjének lehetősége nyílik arra, hogy a parancs kéréseket és az azokra érkezett esetleges válaszokat egyértelműen párosíthassa. Encrypt: A kliens a megadott parancsra több különböző formában kérheti vissza a választ. Jelenleg itt csak az XML érték a megengedett. A parancsok törzs (SOAP body) részében található a parancs tagje, amin belül a paraméterek felsorolása történik. Ezenkívül, a parancsoktól függően további kiegészítő információk is találhatóak a törzsben, amit a parancsok részletes leírásánál lehet megtalálni. Példa az STP KID program egy parancsára: <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> 1 Login <Encrypt>XML <soap:Body> <Pars> CARDINAL <UserId>TEST:KISS KISS HUN
Készült: 2013.12.09.
STP KID
18
A parancsokra az STP KID által adott válasz szintén SOAP üzenet formájában jut vissza a klienshez. A válasz üzenetek a fejlécben pontosan visszaadják azokat az információkat, amit a parancsban kaptak. Ha hiba történt, akkor a törzsben standard SOAP hibajelzés is megjelenik. A törzs ezenfelül, függetlenül a parancs végrehajtásának sikerétől, tartalmaz egy Status bejegyzést, amiben kód és kiegészítő szöveg formájában megtalálható a parancs végrehajtásának eredménye. Példa az előző parancs sikeres végrehajtására: <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> 1 Login <Encrypt>XML <soap:Body> <Status> OK A bejelentkezés sikerült.
8.3.
Teszt program a SOAP protokollhoz
Az STP KID SOAP protokolljának megismerése, és az STP funkció kipróbálása céljából az STP KID programhoz a Cardinal mellékel egy rövid tesztprogramot, aminek neve ELSRV. A tesztprogrammal egyszerű utasítás-sorozat hajtatható végre az STP KID programmal. Az ELSRV program Windows környezetben futtatható, parancssoros (Windows parancs értelmezőből – Command Prompt – kell indítani) program. A tesztprogram működéséhez szükséges file-ok: ELSRV.EXE – maga a parancssoros tesztprogram STP.DLL – kommunikációs modul ELSRV.INI – a tesztprogram paramétereit tartalmazó file *.SOAP file-ok – a SOAP parancsok file-jai Az ELSRV a működéséhez szükséges paramétereket a munkakönyvtárában (alapesetben az exe könyvtárával azonos könyvtár) található ELSRV.INI file-ból veszi. Az INI-file egyszerű text, amit pl. a notepad (jegyzettömb) programmal szerkeszthető. Az INI-file három szekciót tartalmaz: ELSRV, COMMANDS és FILES. A szekciók nevei szögletes zárójelek között találhatók. Az ELSRV szekcióban két bejegyzés lehetséges: HOST és PORT. A HOST után kell írni az STP KID programot futtató Windows-os számítógép nevét vagy TCP/IP címét. A PORT értéke egy szám legyen, aminek meg kell egyeznie az STP KID INI-file-jában szereplő port értékkel. Ha az ELSRV.INI-ben a PORT nincs kitöltve, akkor az STP KID programhoz hasonlóan a tesztprogram is a 7000-es TCP/IP portot használja alapértelmezettként.
Készült: 2013.12.09.
STP KID
19
A COMMANDS szekcióban tetszőleges számú bejegyzés lehet, de azok neveinek formátuma kötött: CMD, ahol n egy tetszőleges szám. A bejegyzés értéke egy filenév kell legyen, ami a SOAP parancsot tartalmazó file-t azonosítja. A tesztprogram a sikeres kapcsolat létrehozása után először a CMD1 bejegyzésben szereplő SOAP parancsfile-t fogja elküldeni az STP KID programnak, majd megvárja és kiírja annak válaszát. A válasz megérkezése után veszi a következő bejegyzést: CMD2, majd azt is elküldi, és így tovább, amíg vannak az INIfile-ban CMD bejegyzések. Ha hiba történik, vagy a tesztprogram visszakapta a legutolsó parancs válaszát is, akkor lezárja a kapcsolatot, és kilép. A tesztprogram, egyszerűsége miatt, nem vizsgálja a SOAP parancsok státuszait, tehát a kommunikációs hiba nélkül megérkezett, de egyébként hibás státuszt tartalmazó parancs után is ki fogja adni a következő parancsot. A .SOAP file-ok xml file-ok, amiket megnézni pl. az Internet Explorerrel lehet. Szerkesztéshez xml editor, vagy egy egyszerű notepad (jegyzettömb) is használható. A FILES szekcióban tetszőleges számú bejegyzés lehet, de azok neveinek formátuma kötött: FILE, ahol az id egy tetszőleges karaktersorozat. A bejegyzés értéke egy filenév kell legyen, aminek egy tetszőleges, de létező file-ra kell mutatnia. A SOAP parancsok xml file-jában tetszőleges ponton szerepelhet %FILE% (százalék karakterek között az INI-file bejegyzés) karaktersorozat. Az ELSRV program a SOAP parancsban lévő ilyen speciális karaktersorozatokat lecseréli az INI-file bejegyzésben megadott file tartalmára. A file-nak tetszőleges tartalma lehet (akár bináris is), ugyanis az xml-helyesség megtartása miatt az ELSRV base64 kódolást végez rajta. Példa az ELSRV.INI file-ra: [ELSRV] HOST = stptest.company.hu PORT = 7000 [COMMANDS] CMD1 = login.soap CMD2 = import.soap CMD3 = logout.soap [FILES] FILE1 = c:\stptest\test.dat
Példa az import.soap file-ra: <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> 2 ImportOrderPack <Encrypt>XML <soap:Body> <Pars> PRO %FILE1% PROORD HUN
Készült: 2013.12.09.
STP KID
20
Az import.soap file-ban az OrderFile mező értéke „%FILE1%”. Az ELSRV program ennek helyére a „c:\stptest\test.dat” file base64 kódját fogja beilleszteni, és azt küldi el az STP KID programnak. Figyelem! Ezt a speciális karaktersorozatokra érzékeny, base64 kódolást az ELSRV tesztprogram végzi, és nem az STP rutinkönyvtár. Az STP API felületen keresztül ilyen hivatkozások nem használhatóak, pontosabban az STP könyvtár a %FILE1% karaktersorozaton nem fog változtatni.
8.4.
Login művelet
Feladata: Technikai művelet, az alap infrastruktúra része, kapcsolódás után a kliens azonosítja magát az STP KID program felé. A Login parancsot minden más művelet előtt, de csak egyszer kötelező használni. Érvényes belépés nélkül más műveletet az STP KID nem szolgál ki. Paraméterek: ClientNo – Az ügyfél KID-beli azonosítója. (A KELER-nél ez a kód általában BETxxxx, BATxxxx alakú) Kitöltése nem kötelező, mert a KID programnak van default ügyfélkódja. UserId – A felhasználó azonosítója a KID programban. A KID-beli csoportkód és rövid név kettősponttal elválasztva, csupa nagybetűvel. (pl.: TEST:KISS) LoginPwd – A felhasználó bejelentkezési jelszava. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A belépés sikerült LOGINFAIL – A belépés nem sikerült.
8.5.
Logout művelet
Feladata: Technikai művelet, az alap infrastruktúra része, a kapcsolat lezárása előtt ez a parancs kilép az STP KID programból. A Login művelet párjaként, használatos. A Logout után egy új sikeres Login műveletig más parancsot az STP KID nem fog végrehajtani. Paraméterek: Nincs paramétere. Státusz: OK – A kilépés sikerült.
8.6.
RemoteLogin
Feladata: Technikai művelet, az alap infrastruktúra része, bejelentkezés a KELER Rt. központi számítógépére. Közvetlen vonali kapcsolat kiépítése az kliens és a KELER rendszerei között. Az RemoteLogin művelet az egyetlen, ami korábbi Login nélkül is használható, ilyenkor a felhasználó azonosítását a KELER központi gépe végzi el. A RemoteLogin Login nélküli hívása arra az esetre van fenntartva, ha a felhasználó az STP KID Készült: 2013.12.09.
STP KID
21
programból már kitiltotta magát, tehát a Login biztosan nem sikerül, de ezt a kitiltást a KELER központban már feloldották. Ha a bejelentkezés sikeres, akkor a helyi kitiltást is feloldja a rendszer. Paraméterek: ClientNo – Az ügyfél KID-beli azonosítója. (A KELER-nél ez a kód általában BETxxxx, BATxxxx alakú) Kitöltése nem kötelező, mert a KID programnak van default ügyfélkódja. UserId – A felhasználó azonosítója a KID programban. A KID-beli csoportkód és rövid név kettősponttal elválasztva, csupa nagybetűvel. (pl.: TEST:KISS) LoginPwd – A felhasználó bejelentkezési jelszava. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A belépés sikerült LOGINFAIL – A belépés nem sikerült.
8.7.
RemoteLogout
Feladata: Techniaki művelet, az alap infrastruktúra része, kijelentkezés a KELER központi számítógépéről. A RemoteLogin párjaként, használatos. Ha már nincs szükség a vonali kapcsolatra a KELER központtal, akkor ezzel a művelettel a kapcsolat elbontható. További, a KELER kapcsolatot nem igénylő, ún. lokális műveletek továbbra is elvégezhetőek maradnak. Paraméterek: Nincs paramétere. Státusz: OK – A kilépés sikerült.
8.8.
ChangeLoginPassword
Feladata: Technikai művelet, az alap infrastruktúra része, a felhasználó bejelentkezési jelszavának megváltoztatása. Jelszót változtatni csak akkor lehet, ha a KELER központba korábban már bejelentkezett a felhasználó a RemoteLogin paranccsal. Paraméterek: OldLoginPwd – A felhasználó régi bejelentkezési jelszava. NewLoginPwd – A felhasználó új bejelentkezési jelszava Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A jelszóváltoztatás sikerült. NOTLOGGEDIN – Még nem jelentkezett be a KELER központba. OLDPWDFAIL – Hibás a megadott régi bejelentkezési jelszó. Készült: 2013.12.09.
STP KID
22
NEWPWDFAIL – Hibás az új bejelentkezési jelszó. (Nem felel meg a jeszlópolicynek: minimum hossz, bonyolultság, stb.) CHANGEFAIL – A módosítás nem sikerült.
8.9.
ChangeSignaturePassword
Feladata: Technikai művelet, az alap infrastruktúra része, a felhasználó aláírási jelszavának megváltoztatása. Jelszót változtatni csak akkor lehet, ha a KELER központba korábban már bejelentkezett a felhasználó a RemoteLogin paranccsal. Paraméterek: OldSigPwd – A felhasználó régi bejelentkezési jelszava. NewSigPwd – A felhasználó új bejelentkezési jelszava Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A jelszóváltoztatás sikerült. NOTLOGGEDIN – Még nem jelentkezett be a KELER központba. OLDPWDFAIL – Hibás a megadott régi aláírási jelszó. NEWPWDFAIL – Hibás az új aláírási jelszó. (Nem felel meg a jeszlópolicy-nek: minimum hossz, bonyolultság, stb.) CHANGEFAIL – A módosítás nem sikerült.
8.10. ImportOrderPack Feladata: Technikai művelet, megbízási csomag importálása a KID programba. Az STP csatornán keresztül ezzel a művelettel lehetséges megbízások bejuttatása a rendszerbe. Megbízás alatt értünk minden olyan tranzakciót, amit az ügyfél a KELER elszámoló rendszerei felé hitelesítetten küld. Ide tartoznak a pénz átutalás, értékpapír transzfer, DVP ügyletek, ugyanúgy, mint a prematch státusz módosítás (validálás, felfüggesztés), vagy a tranzakció törlése az elszámoló rendszerekből. Paraméterek: OrderType – Az importálandó megbízások típusa. KID-beli hárombetűs megbízás azonosító (pl. HUF, EPT, ZAR, PRO, stb.) OrderFile – Az importálandó file base64 kódolással. A lehetséges file formátumok leírását a KELER által kiadott KIDIO.DOC tartalmazza. OrderFormat – Az importlandó file típusa. Ez egy azonosító, ami megadja, hogy mi a formátuma az OrderFile mezőben szereplő adatnak. Ez határozza meg, hogy az importáló rutin pontosan milyen konverziót fog végezni. Az értéke általában a megbízás hárombetűs kódja kiegészítve az „ORD” szóval. Pl.: „HUFORD”, „EPTORD”. ValidateType – Az ellenőrzés szigorúsága. Lehetséges értékei: STRICT vagy COMPLIANT. Ha a ValidateType értéke STRICT, akkor a beimportálandó file-ban Készült: 2013.12.09.
STP KID
23
nem lehetnek hibák. Bármilyen hibát talál a KID program, az egész csomag visszautasításra kerül. Ha a ValidateType értéke COMPLIANT, akkor az importálandó file-ban lehetnek hibák. Ilyenkor a KID a hibás tételeket kihagyja, és csak a jó tételeket importálja be. A hibák száma nem lehet több 20-nál, egyébként az egész file visszautasításra kerül. A KELER esetén jelenleg csak a STRICT ellenőrzés használható. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) PackName – A 6-os programban megváltozott a jelentése, megegyezik a PackSubject paraméterrel. PackSubject – Ez lesz a csomag neve a KID programban. Max. 60 karakteres lehet. Státusz: OK – A importálás sikerült. IMPORTFAIL – Az importálás nem sikerült. Részletes hibalista a válasz OrderPack/OrderError részében található. A visszaadott válasz Status része OrderPack bejegyzéseket tartalmaz. Ahány KID megbízási csomag képződött az importálandó file-ból, annyi OrderPack bejegyzés jön létre. Minden OrderPack tartalmaz egy-egy OrderPackId mezőt, amiben a keletkezett KID megbízási csomagok azonosítója található. További, megbízási csomagokra vonatkozó, STP műveletekben ezzel az azonosítóval lehet hivatkozni a megbízási csomagra.
8.11. SignOrderPack Feladata: Technikai művelet, megbízási csomag hitelesítése (digitális aláírása). Az összes megbízási csomagot az importálás után, de még a beküldés előtt mindenképpen hitelesíteni kell. A hitelesítés mechanizmusa pontosan megegyezik a KID programban jelenleg is használt hitelesítéssel, tehát az aláíráshoz egy aláírási jelszót kell megadni. Az aláírás helyességét az STP KID pontosan ugyanúgy nem ellenőrzi, mint ahogy azt a KID program sem teszi. A hitelességet a KELER központ fogja ellenőrizni a beküldés pillanatában. Az STP csatornán keresztül egy megbízási csomagra akár több aláírás is elhelyezhető, viszont a központ csak akkor fogja a megbízást hitelesnek elfogadni, ha az aláírók (akár technikai – szerver – azonosítóról van szó, akár természetes személy áll a tranzakció indítása mögött) jelszavai helyesek, és a hozzájuk rendelt jogosultságok (aláírási pontok) összesen elérik a KELER-ben előírt szintet. Paraméterek: OrderPackId – Csomag azonosító, amivel az átadott megbízási csomagra hivatkozni lehet. (Kizárólag csak olyan csomagot lehet aláírni, amit az STP-n keresztül adtak át a KID programnak.) UserId – Az aláíró felhasználó azonosítója a KID programban. A KID-beli csoportkód és rövid név kettősponttal elválasztva, csupa nagybetűvel. (pl.: TEST:KISS) SigPwd – Az aláírási jelszó. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Készült: 2013.12.09.
STP KID
24
Státusz: OK – Az aláírás sikerült. SIGNFAIL – Az aláírás nem sikerült.
8.12. SendOrderPack Feladata: Technikai művelet, megbízási csomag beküldése a KELER-be. Az STP keresztül importált, és korábban a SignOrderPack művelettel hitelesített megbízási csomagot ezzel a művelettel lehet eljuttatni a KELER elszámoló rendszerei felé. Egy importált csomag automatikusan nem fog bekerülni a KELER rendszereibe, csak ennek a parancsnak a sikeres végrehajtása esetén! Paraméterek: OrderPackId – Csomag azonosító, amivel az átadott megbízási csomagra hivatkozni lehet. (Kizárólag csak olyan csomagot lehet beküldeni, amit az STP-n keresztül adtak át a KID programnak.) Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A beküldés sikerült. SENDFAIL – A beküldés nem sikerült.
8.13. EERTozsdeiKotesek Feladata: Üzleti tartalmú művelet, az alklíring tagok tőzsdei kötéseinek lekérdezése. Ez a művelet megfelel a KID program „Értékpapír elszámolási rendszer (EÉR)” – „Számlainformációk” – „Alklíring tagok kötései” menüpontban elérhető funkciónak. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Type – Ha értéke „DELTA” akkor csak a legutolsó letöltés után beérkezett tételeket adja, egyébként az összes aznapi tételt Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált tőzsdei kötések Base64 kódolásban. Az exportált adat szerkezete megfelel a KIDIO.DOC dokumentációban szereplő tőzsdei kötések formátumnak. (lásd. KIDIO: 4.2.63. Alklíring tagok kötései) Készült: 2013.12.09.
STP KID
25
8.14. OrdStatExport Feladata: Üzleti tartalmú művelet, megbízás státuszok exportálása. A KID program EÉR vagy OTC (Bruttó elszámolás) alrendszerébe érkező megbízás státuszok exportálása. Ez az STP művelet megfelel a KID program „Értékpapír elszámolási rendszer (EÉR)” – „Megbízások” – „Megbízások státusza” ill. a „Bruttó-DVP elszámolási rendszer (OTC)” – „Megbízások” – „Megbízások státusza” menüpontokban elérhető funkcióknak. Itt az utolsó lekérés óta érkezett megbízás státuszokat tárolja a KID program. Az eredeti megbízási tétel hivatkozási száma (pl. bizonylatszám) található itt a státusz információval együtt, időrendi sorrendben. Az 5.02-77-es verziótól újabb státuszokkal bővül (F1: Ép. fedezett, F0: Ép. fedezetlen, PO: Ép. fedezett örökítendő). Paraméterek: SubSys – Alrendszer hárombetűs kódja („EER” vagy „OTC”), amelyikből exportálni szeretnénk, alapértelmezett „OTC”. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – Az export sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált megbízás státuszok Base64 kódolásban. Az exportált adat szerkezete megfelel a KIDIO.DOC dokumentációban szereplő megbízás státuszt leíró formátumnak. (lásd. KIDIO: 2.2. Megbízások exportja, ORDSTAT adatszerkezet) Mindenféle megbízáshoz ugyanaz az adatszerkezet leírás tartozik, a megbízás típusa az ORDSTAT struktúrán belül található, tehát pontosan ugyanaz a struktúra írja le az értékpapír transzferre (FOP transzfer), és az OTC ügyletekre (DVP transzfer) vonatkozó státuszokat.
8.15. GetPartnerOrders Feladata: Üzleti tartalmú művelet, partner megbízások lekérdezése. Ez az STP művelet megfelel a KID program „Értékpapír elszámolási rendszer (EÉR)” – „Megbízások” – „KELER üzenetek” – „Partner megbízási tétel” ill. a „Bruttó-DVP elszámolási rendszer (OTC)” – „Megbízások” – „KELER üzenetek” – „Partner megbízási tétel” listában elérhető funkciónak. A különböző partner tételek közül jelenleg csak az EPT (FOP transzfer) és a PRO (DVP prompt) használható. Paraméterek: Date – Melyik napra kéri le (ÉÉÉÉHHNN formában) OrderType – Megbízás hárombetűs kódja (EPT, PRO) Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Készült: 2013.12.09.
STP KID
26
Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált partner megbízások Base64 kódolásban. Az exportált adat szerkezete megfelel a KIDIO.DOC dokumentációban szereplő EPT ill. PRO megbízás státusszal bővített formátumának. (lásd. KIDIO: 2.2. Megbízások exportja, 4.1.1. Értékpapír transzfer megbízás, 5.1.1. Bruttó elszámolás PROMPT kötés)
8.16. GetEERNonPair Feladata: Üzleti tartalmú művelet, a páratlan megbízások lekérdezésére. Ez az STP művelet megfelel a KID program „Értékpapír elszámolási rendszer (EÉR)” – „Megbízások” – „Páratlan ügyletek” alatt elérhető funkciónak. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált páratlan tételek Base64 kódolásban. Az exportált adat szerkezete megfelel a KIDIO.DOC dokumentációban szereplő EÉR páratlan ügyletek formátumának. (lásd. KIDIO: 4.2.64. EÉR páratlan ügyletek)
8.17. GetOTCNonPair Feladata: Üzleti tartalmú művelet, a páratlan megbízások lekérdezésére. Ez az STP művelet megfelel a KID program „Bruttó-DVP elszámolási rendszer (OTC)” – „Megbízások” – „Páratlan ügyletek” alatt elérhető funkciónak. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz:
Készült: 2013.12.09.
STP KID
27
OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált páratlan tételek Base64 kódolásban. Az exportált adat szerkezete megfelel a KIDIO.DOC dokumentációban szereplő OTC páratlan ügyletek formátumának. (lásd. KIDIO: 5.2.7. OTC páratlan ügyletek)
8.18. GetOrderStatus Feladata: Üzleti tartalmú művelet, egy megbízási csomagra érkezett státuszok lekérdezésére. Ez az STP művelet megfelel a KID program „Elküldött megbízások – Csomag banki státusza” alatt elérhető funkciónak. Paraméterek: OrderPackId – A lekérdezni kívánt csomag azonosítója. (Kizárólag csak olyan csomagot lehet lekérdezni, amit az STP-n keresztül adtak át a KID programnak.) Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. ERRLOCKED – Nem elérhető az adat, más felhasználó foglalja. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált státuszok Base64 kódolásban. Az exportált adat szerkezete megfelel a KIDIO.DOC dokumentációban szereplő Banki státuszok exportformátumának.
8.19. GetNotifyCatalog Feladata: Technikai művelet, a programnak adott napra küldött notify-ok listáját adja vissza. Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Alapértelmezés a mai nap.
Készült: 2013.12.09.
STP KID
28
Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Type – Opcionális paraméter, ha az értéke „WITHCONTENT”, akkor magát a Notifyt is beleírja az outputba Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Status: Az elérhető notify-ok Item tag-ekben. Egy notify-adatai: Id (azonosító), Date (beérkezési dátum), Text (rövid leírás), Value (a notify teljes tartalma Base64 kódolásban, csak Type= WITHCONTENT esetén kerül kitöltésre).
8.20. GetNotify Feladata: Technikai művelet, egy adott notify lekérdezése Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Alapértelmezés a mai nap. Id – A lekérdezni kívánt notify azonosítója (a GetNotifyCatalog adja). Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A notify teljes tartalma Base64 kódolásban.
8.21. GetCorpCatalog Feladata: Üzleti tartalmú művelet, a programban elérhető külföldi társasági események listáját adja vissza. Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Alapértelmezés az összes nap (vagyis nincs szűrés).
Készült: 2013.12.09.
STP KID
29
Type – A lekérdezni kívánt esemény típus (“TELJ”: a teljesült társasági események, “NEMTELJ”: a nem teljesült társasági események). Alapértelmezés az összes típus (vagyis nincs szűrés). Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Status: Az elérhető események Item tag-ekben. Egy esemény adatai: Id (azonosító), Date (beérkezés dátuma), Text (a típusa: “TELJ” vagy “NEMTELJ”).
8.22. GetCorp Feladata: Üzleti tartalmú művelet, egy adott külföldi társasági esemény lekérdezése Paraméterek: Id – A lekérdezni kívánt esemény azonosítója (a GetCorpCatalog adja). Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – Az esemény teljes tartalma Base64 kódolásban.
8.23. GetBalance Feladata: Üzleti tartalmú művelet, az aktuális egyenleget tölti le a KELER szerverről. Az egyenleg típusa PVR, DNR, EER lehet. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Type – Az egyenleg típusa, „PVR”, „DNR”, „EER” lehet. Státusz: OK – A lekérdezés sikerült. Készült: 2013.12.09.
STP KID
30
NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült.
8.24. ExportBalance Feladata: Üzleti tartalmú művelet, egy adott egyenleget kiexportál Paraméterek: Type – Az egyenleg típusa, „PVR”, „DNR”, „EER” lehet. Format – Az exportálás formátuma. Jelenleg „KIDIO” (ez a KIDIO-ban leírt karakteres export formátum, ez az alapértelmezés) ill. XML lehet (ISO20022 csak DNR esetében létezik). Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. ERRPARAM – Hibás paraméterezés. QUERYFAIL – A lekérdezés nem sikerült. EXPORTFAIL – Az exportálás nem sikerült. Visszatérési érték: Value – A kiexportált egyenleg tartalma Base64 kódolásban.
8.25. GetNoticeCatalog Feladata: Üzleti tartalmú művelet, a programnak adott napra küldött értesítők (notice-ok) listáját adja vissza. Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Alapértelmezés a mai nap. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Type – Opcionális paraméter, ha az értéke „WITHCONTENT”, akkor magát a Notice-t is beleírja az outputba Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült.
Készült: 2013.12.09.
STP KID
31
Visszatérési érték: Status: Az elérhető notify-ok Item tag-ekben. Egy notice-adatai: Id (azonosító), Date (beérkezési dátum), Text (rövid leírás), Value (a notice teljes tartalma Base64 kódolásban, csak Type= WITHCONTENT esetén kerül kitöltésre).
8.26. GetNotice Feladata: Üzleti tartalmú művelet, egy adott notice lekérdezése (jelenleg csak az OTC notice kérdezhető le, mert csak ahhoz létezik export formátum). Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Alapértelmezés a mai nap. Id – A lekérdezni kívánt notice azonosítója (a GetNoticeCatalog adja). Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. EXPORTFAIL – Az exportálás nem sikerült. Visszatérési érték: Value – A notice teljes tartalma Base64 kódolásban.
8.27. GetStatementCatalog Feladata: Üzleti tartalmú művelet, az adott napra készült kivonatok listáját adja vissza. Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült.
Készült: 2013.12.09.
STP KID
32
Visszatérési érték: Result: Az aznapra elérhető kivonatok StmCat.StmCatItem tag-ekben. Egy kivonatadatai: Type (kivonat típusa), Date (beérkezési időpontja ÉÉÉÉHHNNÓÓPPMM alakban).
8.28. GetStatement Feladata: Üzleti tartalmú művelet, egy kivonat letöltése a szerverről Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Type – A lekérdezni kívánt kivonat típusa. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült.
8.29. ExportStatement Feladata: Üzleti tartalmú művelet, egy kivonat exportálása Paraméterek: Date –YYYYMMDD formában. Type – Az exportálni kívánt kivonat típusa. Format – Az exportálás formátuma. Jelenleg „KIDIO” (ez a KIDIO-ban leírt karakteres export formátum, ez az alapértelmezés) ill. „XML” lehet (ISO20022 csak PVR, DNR kivonatok esetében). Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. EXPORTFAIL – Az exportálás nem sikerült. Visszatérési érték:
Készült: 2013.12.09.
STP KID
33
Value – A kiexportált kivonat tartalma Base64 kódolásban. Energiapiaci riport esetében (mivel több file van egy kivonatban) eltér az output szerkezete: minden egyes output file-hoz egy Item taget készítünk a Status tag alatt. Ennek az Itemnek a szerkezete: Type – A riport típusa Text: File kiterjesztés (PDF stb.) Value: A riport Base64 kódolásban
8.30. GetAdviceCatalog Feladata: Üzleti tartalmú művelet, egy adott időintervallumban készült értesítők listáját adja vissza. Paraméterek: FromDate – A lekérdezni kívánt intervallum eleje YYYYMMDD formában. ToDate – A lekérdezni kívánt intervallum vége YYYYMMDD formában. SubSys – Értesítők típusa („TES”). Jelenleg csak a társasági esemény értesítők léteznek a KID-en, ez az alapértelmezés. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Result: Az aznapra elérhető értesítők AdvCat.AdvCatItem tag-ekben. Egy értesítőadatai: Id (kivonat azonosítója), Date (beérkezési dátuma ÉÉÉÉHHNN alakban).
8.31. GetAdvice Feladata: Üzleti tartalmú művelet, egy értesítő letöltése a szerverről Paraméterek: Date – A lekérdezni kívánt nap YYYYMMDD formában. Id – A lekérdezni kívánt értesítő azonosítója. SubSys – Értesítők típusa („TES”). Jelenleg csak a társasági esemény értesítők léteznek a KID-en, ez az alapértelmezés.
Készült: 2013.12.09.
STP KID
34
Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. NOTLOGGEDIN – Nincs bejelentkezve a szerverre. ERRLOCKED – Más felhasználó már használja az adatot (értesítőt tölt le). QUERYFAIL – A lekérdezés nem sikerült.
8.32. ExportAdvice Feladata: Üzleti tartalmú művelet, egy értesítő exportálása Paraméterek: Date –YYYYMMDD formában. Id – Az exportálni kívánt értesítő azonosítója. SubSys – Értesítők típusa („TES”). Jelenleg csak a társasági esemény értesítők léteznek a KID-en, ez az alapértelmezés. Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. EXPORTFAIL – Az exportálás nem sikerült. Visszatérési érték: Value – A kiexportált értesítő tartalma Base64 kódolásban.
8.33. IsLoggedIn Feladata: Technikai művelet, ellenőrzi, hogy az STP KID program be van-e jelentkezve a KELER szerverére. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz:
Készült: 2013.12.09.
STP KID
35
OK – Él a kapcsolat a KELER szerverével. DISCONNECT – Nincs kapcsolat a KELER szerverével.
8.34. GetMemberInquiries Feladata: Üzleti tartalmú művelet, DER tagi lekérdezés exportálása. Paraméterek: Type – Az exportálni kívánt tagi lekérdezés típusa: Típus
Lekérdezés
POU
Befogadott üzletkötések
PON
Elõzõ napi záró nyitott kötésállomány
POI
Aktuális nyitott kötésállomány
POH
Végrehajthatatlan opciólehívások
POA
Végrehajtatlan feltételesen bef. poz.átadások
ARK
Árkülönbözet
ALL
Üzletkötések allokáláshoz
POZ
Zárolt pozíciók
BIZ
Biztosítékigény
SOR
Delivery sorsolások
NOJ
Notional jegyzék Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. QUERYFAIL – A lekérdezés nem sikerült. EXPORTFAIL – Az exportálás nem sikerült.
Visszatérési érték: Value – A kiexportált kivonat tartalma Base64 kódolásban.
8.35. GetGIROCredits Feladata: Üzleti tartalmú művelet, a GIRO jóváírások lekérdezésére. Készült: 2013.12.09.
STP KID
36
Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Type – Ha értéke „DELTA” akkor csak a legutolsó letöltés után beérkezett tételeket adja, egyébként az összes aznapi tételt Format – Az exportálás formátuma. Jelenleg „KIDIO” (ez a KIDIO-ban leírt karakteres export formátum, ez az alapértelmezés) ill. „XML” lehet (ISO20022). Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált GIRO jóváírások Base64 kódolásban.
8.36. GetRate Feladata: A legutóbb letöltött árfolyam lekérdezése és exportálása. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Format – Az exportálás formátuma. Jelenleg „KIDIO” (ez a KIDIO-ban leírt karakteres export formátum, ez az alapértelmezés) ill. „XML” lehet (ISO20022). Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált árfolyamok Base64 kódolásban.
8.37. ExportKELERData Feladata: KELER törzsadat exportálása.
Készült: 2013.12.09.
STP KID
37
Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) Type – Az exportálni törzsadat azonosítója: Azonosító
Törzsadat
EPTORZS
Értékpapír törzsadatok
TUTORZS
Ügyfelek értékpapír számlái
PVRTORZS
Ügyfelek forint számlaszámai
LETEP
Nem forgalomképes értékpapírok
KMERTEK
Kollaterál értékek
TESTZS
Társasági események törzsadat
RKTORZS
Részvénykönyvi értékpapír törzsadat
Format – Az exportálás formátuma. Jelenleg „KIDIO” (ez a KIDIO-ban leírt karakteres export formátum, ez az alapértelmezés) ill. „XML” lehet (kizárólag a PVRTORZS esetében). Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált törzsadat Base64 kódolásban.
8.38. ExportOrder Feladata: Elküldött megbízási csomag exportálása státuszinformációkkal együtt. A következő megbízásoknak létezik export formátuma: HUF, HCT, EPT, DET, PRO, RPO, DVD, ALL, PIZ, PAA, OPL, FFE, DCS, PKI, DNO, LIM, OKK, PVE, PVM. Paraméterek: Language – Nyelv kiválasztása, amilyen nyelven a hibák és státuszok szövegeit kéri. (KELER esetén a lehetséges értékek: HUN, ENG) OrderPackId – A lekérdezni kívánt csomag azonosítója. (Kizárólag csak olyan csomagot lehet lekérdezni, amit az STP-n keresztül adtak át a KID programnak.)
Készült: 2013.12.09.
STP KID
38
Format – Az exportálás formátuma. Értéke: „Actual (aktuális státuszok, alapértelmezés) illetve History (státusztörténet) lehet. Státusz: OK – A lekérdezés sikerült. NODATA – Nincs lekérdezhető adat. EXPORTFAIL – Nem sikerült az exportálható formátumot előállítani. QUERYFAIL – A lekérdezés nem sikerült. Visszatérési érték: Value – A kiexportált adat Base64 kódolásban.
9. Az STP KID API kliens része 9.1.
Bevezetés
Az STP KID program az Unicom kommunikációs modulon keresztül SOAP parancsokkal vezérelhető. Az ügyfeleknél végzendő programozói munka egyszerűsítése végett elkészült az STP KID-hez az Unicom modul egy egyszerű API-ja (application programming interface), amivel általánosan kezelhető az összes kérés ill. azok válaszaik.
9.2.
Telepítés
Az STP KID API kliens programcsomagot (ami tartalmazza ezen dokumentációt is) a KELER Zrt-től egy ZIP kiterjesztésű, tömörített file-ban kapják meg az ügyfelek. A file neve keler_stp_client.zip. Az STP API nem igényel külön telepítési eljárást, a zip file tartlamát egyszerűen egy tetszőleges alkönyvtárba ki kell csomagolni. A zip file a következő komponenseket tartalmazza: File
Megjegyzés
elsrv.dat
Az elsrv.dat igazából egy Windows exe file, ami az Internetes levelezést szűrő vírusvédő programok miatt lett átnevezve DAT kiterjesztésűre. A kicsomagolás után a file-t át kell nevezni elsrv.exe névre! Az elsrv.exe-ről bővebben lásd a 8.3 fejezetet.
stp.dat
Az stp.dat igazából egy Windows dll file, ami az Internetes levelezést szűrő vírusvédő programok miatt lett átnevezve DAT kiterjesztésűre. A kicsomagolás után a file-t át kell nevezni stp.dll névre. Az stp.dll az STP kommunikációt megvalósító modul, amit az ügyfeleknek a saját rendszereikbe kell integrálniuk. Az STP funkcionalitás ezen dll-ben lévő függvényhívásokon
Készült: 2013.12.09.
STP KID
39 keresztül érhető el.
stp.h
Az stp.h egy C programozási nyelven írt interface leírás az stp.dll-ben található függvényekhez.
stp.doc
Ez a dokumentáció, amit éppen most olvas.
import.soap
Példa SOAP üzenet az ImportOrderPack STP művelethez.
login.soap
Példa SOAP üzenet a Login STP művelethez.
logout.soap
Példa SOAP üzenet a Logout STP művelethez.
modlpwd.soap
Példa SOAP művelethez.
modspwd.soap
Példa SOAP üzenet a ChangeSignaturePassword STP művelethez.
rlogin.soap
Példa SOAP üzenet a RemoteLogin STP művelethez.
rlogout.soap
Példa SOAP üzenet a RemoteLogout STP művelethez.
sendord.soap
Példa SOAP üzenet a SendOrderPack STP művelethez.
signord.soap
Példa SOAP üzenet a SignOrderPack STP művelethez.
9.3.
üzenet
a
ChangeLoginPassword
STP
Típusok és státuszkódok
Az API-ban található egy STPSession típus, amin keresztül a különböző STP műveletek elvégezhetők. Minden művelet visszatérési értéke egy státuszkód, ami jelzi, hogy az adott API művelet végrehajtása hogyan sikerült. A státuszkód lehetséges értékei a következők: typedef enum { STP_OK, STP_ERROR_FATAL, STP_ERROR_MEMORY, STP_ERROR_FILE, STP_ERROR_DISCONNECT STP_TIMEOUT } STPStatus;
9.4.
Session műveletek
A session-ök létrehozásával kapcsolatban két művelet létezik: Az elsővel létre lehet hozni egy sesssion-t, a másikkal pedig be lehet azt zárni. A létrehozás során meg kell adni egy hálózati gépnevet (vagy TCP/IP címet), egy TCP/IP portot és egy timeout értéket, amin belül a kapcsolatfelvételt hajlandó a rendszer elfogadni. Unix környezetben az API a timeout paramétert nem használja. STPStatus STP_OpenSession(STPSession *psession, const char *host, int port, int timeout); STPStatus STP_CloseSession(STPSession *psession);
Készült: 2013.12.09.
STP KID
40
A kapcsolódás visszatérési értéke STP_OK, STP_ERROR_FATAL, STP_TIMEOUT lehet, míg a vonalbontás eredménye STP_OK, STP_ERROR_FATAL lehet.
9.5.
Kérés elküldés, válasz fogadás
Azért, hogy ne kelljen minden egyes új STP funkció kialakítása esetén módosítani az API-t, az STP KID kérések elküldése és fogadása általánosan lett kidolgozva. Az API-ban lehetőség van a kérések memóriából vagy fájlból történő elküldésére, valamint a válaszok memóriába illetve file-ba történő fogadására. Az STP alatti Unicom layer Windows környezetben aszinkron socket kommunikációra épül, míg Unix operációs rendszeren szinkron működik. Emiatt a kérés küldésnek és a válasz fogadásnak az interface-e különbözik a két környezetben.
9.6.
Kérés elküldés, válasz fogadás Windows környezetben
Windows környezetben a kérés küldése szinkron művelet, de a válasz aszinkron érkezik meg. Emiatt a válaszok kezelésére egy callback-es mechanizmust vezettünk be. typedef STPStatus (CALLBACK * STPCallback)( STPSession session, STPStatus status, const char *fname, void *buffer, size_t size, void *userdata); STPStatus STP_SendRequestFromFile(STPSession session, const char *fromfile, const char *tofile, STPCallback callback, void *userdata); STPStatus STP_SendRequestFromBuffer(STPSession session, const void *buffer, size_t size, const char *tofile, STPCallback callback, void *userdata);
Az elküldés a korábban megnyitott session-ön keresztül továbbítja a kérést, aminek SOAP formátumúnak kell lennie. A függvények visszatérési értéke STP_OK, ha a küldés sikerült, és STP_ERROR_FATAL, ha valamilyen hiba volt. File-ból történő küldéskor a fromfile paraméterben kell megadni, hogy a SOAP adatot melyik file-ból kell kiolvasni. Memóriából történő küldéskor a buffer paraméterben kell megadni a kérés memóriacímét, a size paraméterben pedig a kérés méretét. A tofile paraméterben adható meg, hogy a választ melyik file-ba tegye az API. Ha ennek a paraméternek az értéke NULL, akkor a válasz memóriabufferben fog megérkezni. Amikor a válasz megérkezett, meghívódik a callback paraméterben megadott függvény az alábbi paraméterekkel: status
A callback hívásakori státusza, lehetséges értékei: STP_OK: a válasz sikeresen megérkezett
Készült: 2013.12.09.
STP KID
41 STP_ERROR_FILE: a válasz file-ba mentésekor hiba történt STP_ERROR_DISCONNECT: a szerver elbontotta a kapcsolatot STP_ERROR_MEMORY: a válasz részére történő memória allokálásakor hiba történt STP_ERROR_FATAL: kommunikációs hiba történt
fname buffer
A request küldésekor megadott file-név (tofile). Ha nem NULL, akkor az adott nevű file tartalmazza a választ és a buffer paraméter értéke NULL. Ha a request küldésekor a tofile paraméter NULL volt, akkor a válasz a buffer a paraméterben van, és a size adja meg a buffer méretét. Az fname paraméter értéke ilyenkor NULL. Az itt kapott memóriabuffert az API allokálja és az alkalmazásnak kell felszabadítania az STP_FreeBuffer művelettel. Ha az API nem tudott a buffernek memóriát allokálni, akkor a buffer pointer értéke NULL.
size userdata
A buffer paraméter mérete. A küldéskor megadott userdata pointer értéke.
A callback visszatérési értéke STP_OK vagy STP_ERROR_DISCONNECT lehet. Ha STP_ERROR_DISCONNECT, akkor az API bontja a kapcsolatot, és a session a továbbiakban nem használható. A fenti callback-es mechanizmus szinkron jellegű felhasználása is lehetséges a STP_WaitForResponse művelet segítségével: STPStatus STP_WaitForResponse(STPSession session, int timeout);
A fenti függvény addig futtat egy egyszerű eseményciklust, amíg az alábbi események valamelyike be nem következett: a timeout lejárt, ekkor a függvény visszatérési értéke STP_TIMEOUT a válasz megérkezett, és a megadott callback lefutott, ekkor a visszatérési érték a callback visszatérési értéke a kapcsolat megszakadt, ekkor a visszatérési érték STP_ERROR_DISCONNECT Az eseményciklus minden – nem belső – eseményt dispatch-ol. Amennyiben a fenti eseményciklusnál bonyolultabb feldolgozásra van szükség a válaszra várás alatt, akkor azt az STP modult felhasználó alkalmazásfejlesztőknek kell megírnia. A callback-ben visszakapott buffer által elfoglalt memóriaterület felszabadításáról szintén az STP modult felhasználó alkalmazásfejlesztőknek kell gondoskodnia. Ezt a memóriát az STP_FreeBuffer művelettel KELL felszabadítani: void STP_FreeBuffer(void *buffer);
Készült: 2013.12.09.
STP KID
9.7.
42
Kérés elküldés, válasz fogadás Unix környezetben
Unix környezetben mind a kérés küldése mind a válasz fogadása szinkron művelet, ezért nincs szükség a bonyolult callback-es mechanizmusra. STPStatus STP_SendRequestFromFile(STPSession session, const char *fromfile); STPStatus STP_SendRequestFromBuffer(STPSession session, const void *buffer, size_t size);
Az elküldés a korábban megnyitott session-ön keresztül továbbítja a kérést, aminek SOAP formátumúnak kell lennie. A függvények visszatérési értéke STP_OK, ha a küldés sikerült, és STP_ERROR_FATAL, ha valamilyen hiba volt. File-ból történő küldéskor a fromfile paraméterben kell megadni, hogy a SOAP adatot melyik file-ból kell kiolvasni. Memóriából történő küldéskor a buffer paraméterben kell megadni a kérés memóriacímét, a size paraméterben pedig a kérés méretét. A kérésre a választ az STP_WaitForResponse művelet segítségével lehet megkapni: STPStatus STP_WaitForResponse(STPSession session, int timeout, const char *fname, void **pbuffer, size_t *pbufsize);
A fenti függvény a session paraméterben megadott kapcsolaton addig várja a választ, amíg az alábbi események valamelyike be nem következett: a timeout lejárt, ekkor a függvény visszatérési értéke STP_TIMEOUT a válasz megérkezett, ekkor a visszatérési érték STP_OK az API nem tudott memóriát foglalni a válasz számára, ekkor a visszatérési érték STP_ERROR_MEMORY az API-ban file-kezelési hiba történt, ekkor a visszatérési érték STP_ERROR_FILE a kapcsolat megszakadt, ekkor a visszatérési érték STP_ERROR_DISCONNECT kommunikációs hiba, ekkor a visszatérési érték STP_ERROR_FATAL A válasz érkezhet file-ba, vagy az API által allokált memória bufferbe. Az fname paraméterben adható meg, hogy a választ melyik file-ba tegye az API. Ha ennek a paraméternek az értéke NULL, akkor a pbuffer paraméter fog a válaszra, a pbufsize paraméter pedig a válasz méretére mutatni. Ha a válasz bufferben érkezett, akkor visszakapott buffer memóriaterületét az STP_FreeBuffer művelettel KELL felszabadítani: void STP_FreeBuffer(void *buffer);
Készült: 2013.12.09.
