Protokol GDEP
Podporované typy a verzie zariadení
Konfigurácia komunikačnej linky
Konfigurácia komunikačnej stanice
Konfigurácia meraných bodov
Literatúra
Zmeny a úpravy
Revízie dokumentu
Podporované typy a verzie zariadení
Protokol GDEP (Game Data Exchange Protocol) je implementovaný vo verzii 2.4 (aktuálne k 05/2006). Protokol slúži na
posielanie a prijímanie SMS a MMS správ, spracovanie WAP požiadaviek a hranie SMS hier.
Protokol je postavený na štandardoch TCP, HTTP (resp. HTTPS) a XML. Účastníkmi komunikácie sú GAP server (GAme Platform)
na strane Orange a aplikácia (D2000 KOM proces).
Implementácia v D2000 podporuje nasledovné správy protokolu:
Tab. č. 1
| Správa | Smer | Popis |
|---|---|---|
| HELLO | KOM->GAP | Prihlasovanie sa (meno+heslo) ku GAP platforme pri nadväzovaní spojenia. |
| INQUIRE_LINK | KOM->GAP GAP->KOM |
Testovanie funkčnosti spojenia pri dlhšej dobe nečinnosti. |
| INQ_RSP | KOM->GAP GAP->KOM |
Odpoveď na INQUIRE. |
| RECEIVE (sms) | GAP->KOM | Prijatie SMS správy od GAP servera. |
| RCV_RSP (sms) | KOM->GAP | Potvrdenie prijatia SMS správy D2000 KOM procesom. |
| SEND (sms) | KOM->GAP | Poslanie SMS správy. |
| SND_RSP (sms) | GAP->KOM | Potvrdenie prijatie SMS správy GAP serverom. |
| ACCEPTED | GAP->KOM | Potvrdenie prijatie SMS alebo MMS správy SMS/MMS centrom. |
| ACC_RSP | KOM->GAP | Odpoveď D2000 KOM procesu na správu ACCEPTED. |
| RECEIPT (sms) | GAP->KOM | Potvrdenie prijatie SMS správy koncovým užívateľom. |
| REC_RSP | KOM->GAP | Odpoveď D2000 KOM procesu na správu RECEIPT. |
| BY | KOM->GAP | Ukončenie spojenia zo strany D2000 KOM procesu. |
| BY_RSP | GAP->KOM | Odpoveď GAP servera na správu BY. |
| NAK | GAP->KOM | Odmietnutie neprípustnej správy. |
Nasledovné správy protokolu NIE SÚ v aktuálnej verzii implementované:
Tab. č. 2
| Správa | Smer | Popis |
|---|---|---|
| RECEIVE (wap) | GAP->KOM | Prijatie WAP požiadavky od GAP servera. |
| RCV_RSP (wap) | KOM->GAP | Potvrdenie prijatia WAP požiadavky D2000 KOM procesom. |
| RECEIVE (mms-xml) | GAP->KOM | Prijatie MMS správy od GAP servera. |
| RCV_RSP (mms-xml) | KOM->GAP | Potvrdenie prijatia MMS správy D2000 KOM procesom. |
| SEND (mms-xml) | KOM->GAP | Poslanie MMS správy. |
| SND_RSP (mms-xml) | GAP->KOM | Potvrdenie prijatie MMS správy GAP serverom. |
| RECEIPT (mms) | GAP->KOM | Potvrdenie prijatie MMS správy koncovým užívateľom. |
| SCORE | KOM->GAP | Zmena skóre hráča. |
| SCO_RSP | GAP->KOM | Odpoveď GAP servera na správu SCORE. |
| NICK | KOM->GAP | Správa prezývok (nickov) hráča: vytváranie, rušenie, pridávanie, mazanie a hľadanie. |
| NICK_RSP | GAP->KOM | Odpoveď GAP servera na správu NICK. |
Konfigurácia komunikačnej linky
Kategória komunikačnej linky: TCP/IP-TCP
TCP Parametre:
- Host: String max. 80 znakov – meno servera vo formáte INET (meno alebo číselná adresa a.b.c.d).
- Port: Číslo TCP portu (1 až 65535).
- Číslo linky: Nepoužité, zadajte ľubovoľné číslo.
Poznámka: Protokol GDEP je postavený nad HTTP alebo HTTPS protokolom. D2000 KOM proces neobsahuje HTTPS komunikáciu - táto je riešená modulárne pomocou programu stunnel. Program stunnel je schopný zabaliť do SSL vrstvy klientskú aj serverovskú časť komunikácie. Keďže GDEP protokol vyžaduje na oboch stranách (GAP server aj D2000 KOM) implementáciu klienta aj servera, je nutné spustiť dva stunnel procesy:
- jeden v serverovskom móde, ktorý bude čakať na pripojenie sa GAP servera a po spracovaní SSL vrstvy dáta prepošle na dohodnutý port, na ktorom čaká D2000 KOM ako GDEP server (viď parameter Server Port),
- ďalší v klientskom móde, ktorý čaká na dohodnutom porte. K nemu sa pripojí D2000 KOM (klientska časť) a po zabalení dát do SSL vrstvy ich stunnel pošle na zadefinovaný cieľový počítač a port (serverovský port GAP servera). Preto bude v parametri Host zrejme uvedený localhost a v parametri Port uvedený port, na ktorom čaká stunnel proces v klientskom móde.
Konfigurácia komunikačnej stanice
Komunikačný protokol: GDEP
Adresa stanice: nepoužitá (zadajte 1)
Poznámka: Na linke musí byť PRESNE JEDNA komunikačná stanica.
Parametre protokolu stanice
Môžu byť zadané nasledovné parametre protokolu stanice:
Tab. č. 3
| Kľúčové slovo | Plný názov | Popis | Jednotka | Náhradná hodnota |
|---|---|---|---|---|
| RD | Relogin Delay | Čakanie pred pokusom o znovupripojenie sa ku GAP serveru | sec | 10 |
| TKI | TCP KeepInit option | KeepInit nastavenie TCP protokolu. | - | False |
| CE | Station Communication Error | Počet neúspešných pokusov o pripojenie sa, po ktorých stanica prechádza do stavu StCOMERR. | - | 1 |
| HE | Station Hard Error | Počet neúspešných pokusov o pripojenie sa, po ktorých stanica prechádza do stavu StHARDERR. | - | 3 |
| U | User Name | Užívateľské meno na prihlásenie sa ku GAP serveru. | - | - |
| P | UserPassword | Heslo na prihlásenie sa ku GAP serveru. | - | - |
| HH | HTTP Host | IP adresa alebo meno servera uvádzané v HTTP requeste. | - | - |
| HP | HTTP Port | Port servera uvádzaný v HTTP requeste. | - | 0 |
| SP | Server Port | Port, na ktorom počúva KOM ako server. | - | 1000 |
| TSI | Timeout Send Inquire | Timeout, po ktorom KOM pošle INQUIRE správu (0=vypnuté). | sec | 90 |
| TRI | Timeout Receive Inq_Rsp | Timeout, do ktorého KOM očakáva INQ_RSP (odpoveď na INQUIRE). | sec | 10 |
| TRA | Timeout Receive Accept | Timeout, po ktorom vyhlási KOM proces správu za timeoutovanú (úroveň potvrdenia 2), ak dovtedy nepríde správa ACCEPTED. | sec | 10 |
| TRR | Timeout Receive Receipt | Timeout, po ktorom vyhlási KOM proces správu za timeoutovanú (úroveň potvrdenia 3), ak dovtedy nepríde správa RECEIPT. | sec | 60 |
| K1 H1 P1 K2 H2 P2 |
KOM Name 1 Host Address 1 Port Number 1 KOM Name 2 Host Address 2 Port Number 2 |
Pri nasadení v redundantnom systéme D2000 (dva procesy D2000 KOM): ak sa meno počítača, na ktorom beží proces D2000 KOM zhoduje s parametrom K1 (resp. K2), pri pripájaní sa na GAP server bude HELLO správa obsahovať voliteľné parametre host a port s hodnotami H1 a P1 (resp. H2 a P2). Takto GAP vie, na ktorý z dvoch procesov D2000 KOM sa má pripojiť. |
Konfigurácia meraných bodov
Merané body sú definované svojou adresou, ktorá musí zodpovedať adrese uvedenej v nasledujúcich tabuľkách. Názvy meraných bodov sa môžu líšiť a sú uvedené iba kvôli odvolávke na ne v ďalšom texte.
Príjem SMS správ: Po príjme SMS správy sa nastavia hodnoty nasledovných meraných bodov (pokiaľ sú body nakonfigurované).
Tab. č. 4
| Adresa | Typ | Názov bodu | Popis |
|---|---|---|---|
| 1 | TxtO | Rcv_Id |
64-bitové ID prijatej SMS správy (správa RECEIVE). Po spracovaní správy aplikáciou treba zápisom do tohto meraného bodu oznámiť KOM procesu, že môže potvrdiť prijatie správou RCV_RSP a zároveň sprístupniť aplikácii ďalšiu
SMS správu (pokiaľ čaká vo fronte). |
| 2 | TxtI | Rcv_Serv_Id | Parameter serv_id prijatej správy. [service ID that this message belongs to.] |
| 3 | TxtI | Rcv_AppAddr | Parameter appaddr prijatej správy. [destination number. It can be short or long number dedicated to the service (External Application). It is identification of the game. It is never encrypted. ] |
| 4 | TxtI | Rcv_AppAddrType | Atribút type parametra appaddr. |
| 5 | TxtI | Rcv_Msisdn | Parameter msisdn prijatej správy. [source number. Can be encrypted, see the type attribute.] |
| 6 | TxtI | Rcv_MsisdnType | Atribút type parametra msisdn. |
| 7 | Ci | Rcv_Employee | Parameter employee prijatej správy. [if application have enabled mark of employee, then element employee has value 0 – if source MSISDN is NOT employee 1 – if source MSISDN is employee] |
| 8 | Ci | Rcv_Dcs | Parameter dcs prijatej správy. [parameter data_coding of the GDEP protocol (DCS) [SMPP PS v3.4]. (8-bit integer defined in the ASCII). Default = 0.] |
| 9 | Ci | Rcv_Esm | Parameter esm prijatej správy.
[parameter esm of the SMPP protocol (DCS) [SMPP PS v3.4]. (8-bit integer defined in the ASCII). Default = 0.] |
| 10 | TxtI | Rcv_Recv_Date | Parameter receive_date prijatej správy. [time of receive SMS to SMS center.] |
| 11 | TxtI | Rcv_Coding | Atribút coding parametra content. [type of coding in the element content. Currently used are: text ASCII text, base64 content is coded by code base64 – this is used for binary data.] |
| 12 | TxtI | Rcv_Content | Parameter content prijatej správy. [nothing but data. Data sent by the subscriber to the External Application (SMS).] |
| 13 | TxtI | Rcv_MsgPart | Parameter msg_part prijatej správy (trojica ref_num/seg_num/tot_seg). [ref_num - contain a originator generated reference number so that a segmented short message may be reassembled into a single original message seg_num - sequence number of particular message within the concatenated message tot_seg - indicating the total number of fragments] |
Posielanie SMS správ: Pri posielaní SMS správy je potrebné nastaviť hodnoty nasledovných meraných bodov (pokiaľ sú body nakonfigurované). Správa sa pošle až po nastavení hodnoty meraného bodu
Snd_AppDefId.
Značka (o) uvedená pri meranom bode znamená, že bod je voliteľný (nemusí byť nakonfigurovaný, pretože GDEP protokol tento atribút uvádza ako nepovinný).
Tab. č. 5
| Adresa | Typ | Názov bodu | Popis |
|---|---|---|---|
| 101 | TxtO | Snd_Serv_Id | Parameter serv_id odosielanej správy. [service ID that this message belongs to.] |
| 102 | TxtO | Snd_Rcv_Msg_Id (o) | Parameter rcv_msg_id odosielanej správy. [ID of received message (RECEIVE) that this message is a response to] |
| 103 | TxtO | Snd_AppAddr | Parameter appaddr odosielanej správy. [source number. It can be either short or long (MSISDN) number assigned to the service.] |
| 104 | Co | Snd_AppAddrType (o) | Atribút type parametra appaddr. |
| 105 | TxtO | Snd_Msisdn | Parameter msisdn odosielanej správy. [destination number. In case of a mobile telephone number, it can be encrypted. In case of a short number, the destination number is the short number only. Can be encrypted, the type is present in the type attribute.] |
| 106 | Co | Snd_MsisdnType (o) | Atribút type parametra msisdn. |
| 107 | TxtO | Snd_BillMsisdn (o) | Parameter billmsisdn odosielanej správy. [MSISDN to which the message will be billed (this tag is only used with specific applications, where the billed subscriber is not the recipient of the message. This option must be approved at the Game Platform by agreement with the marketing dept.) Can be encrypted, the type is present in the type attribute.] |
| 108 | Co | Snd_BillType (o) | Atribút type parametra billmsisdn. |
| 109 | Co | Snd_Flags (o) | Parameter flags odosielanej správy. [32-bit numbers displayed decimally in ASCII format. Flags are combined with OR binary function. Unused bits are reserved. SMS_FLAG_RECEIPT bit 1 - delivery receipt requested SMS_FLAG_REPLACE bit 2 - SM replacement requested on SIM card position under bits 4-6 SMS_FLAG_POSITION bit 4-6 - SIM position for SM replacement position range: from 1 to 7, 0 is unused] |
| 110 | TxtO | Snd_Expiration (o) | Parameter expiration odosielanej správy. [validity period of the SM in the GSM time encoding (i.e. YYMMDDhhmmsst), or the character „-", if not defined] |
| 111 | TxtO | Snd_Delivery (o) | Parameter delivery odosielanej správy. [delivery time of the SM in the GSM time encoding (i.e. YYMMDDhhmmsst), or the character „-", if not defined.] |
| 112 | TxtO | Snd_BillKey | Parameter billkey odosielanej správy. [billing key, 4 characters long string consisting of (0..9) and (A .. Z). Each application will have 4 keys to be used in this field] |
| 113 | TxtO | Snd_Evbill_Id (o) | Parameter evbill-id odosielanej správy. [service identifier in the event billing in case this type of billing method should be used.] |
| 114 | TxtO | Snd_EvbillIdSeq (o) | Parameter evbill-id-seq odosielanej správy. [service identifier in the event billing in case this type of billing method should be used.] |
| 115 | Co | Snd_Dcs (o) | Parameter dcs odosielanej správy. [parameter data_coding of the SMPP protocol (DCS) [SMPP PS v3.4]. (8-bit integer defined in the ASCII). Default = 0.] |
| 116 | Co | Snd_Esm (o) | Parameter esm odosielanej správy. [parameter esm of the SMPP protocol (DCS) [SMPP PS v3.4]. (8-bit integer defined in the ASCII). Default = 0.] |
| 117 | TxtO | Snd_Score (o) | Parameter score odosielanej správy. [game is sending score for the subscriber with – MSISDN. Format: +score – Game Platform adds this score value to the daily counter -score – Game Platform subtracts this score value from the daily counter score – Game Platform replaces the daily counter by this score value (daily counter is parameter, which is bind to MSISDN, nick, game and day. This counter will be changed only by GDEP protocol)] |
| 118 | TxtO | Snd_ScoreNick (o) | Atribút nick parametra score. [– if this attribute will be used it will define the particularly used nick of the subscriber defined by MSISDN. Score will update the daily counter for this MSISDN and nick. If this attribute will not be used daily counter for MSISDN and default value nick="" will be used.] |
| 119 | TxtO | Snd_ScoreFinish (o) | Atribút finished parametra score. [if this attribute will be used (with the any value, default value will be empty string ""), the Game Platform will add the new issue to the table C_SCORE, where will be add each player so many time how many will finish the game successfully. Use this attribute only after successful finishing of the game by the player.] |
| 120 | TxtO | Snd_Coding | Parameter content odosielanej správy. [type of coding in the element content Currently used are: text ASCII text base64 content is coded by code base64 – this is used for binary data.] |
| 121 | TxtO | Snd_Content | Parameter content odosielanej správy. [nothing but data. Data sent by the External Application (SMS) to the subscriber.] |
| 122 | TxtO | Snd_Category (o) | Parameter category odosielanej správy. [element can be used to specify category of content that is to be sent, character string 1-64 bytes long] |
| 123 | Co | Snd_AppDefId | Ľubovolné aplikáciou vygenerované kladné celé číslo, ktoré (pre aplikáciu) definuje zasielanú SMS správu. Potvrdenia o doručení resp. nedoručení SMS-ky budú obsahovať toto číslo (meraný bod Rsp_AppDefId), pokiaľ KOM proces nebol medzitým reštartovaný. |
| 130 | TxtI | Snd_64bit_Id | 64-bitový identifikátor, ktorý nastaví KOM proces pri posielaní SMS správy. Keďže GDEP protokol pracuje s unikátnym 64-bitovým identifikátorom (jeho hodnotu inicializuje GDEP server pri pripojení sa D2000 KOM procesu), potvrdenia o doručení sú vnútorne označené týmto 64-bitovým ID-čkom. Pokiaľ bol KOM proces reštartovaný, po nábehu môžu prísť od GAP servera potvrdenia o doručení správ, ktoré boli poslané ešte pred reštartom. V takom prípade D2000 KOM proces nastaví Snd_AppDefId na hodnotu -1 a aplikácia môže spárovať potvrdenia podľa nastaveného Snd_64bit_Id. |
Príjem potvrdení o doručení SMS správ: Po prijatí správ ACCEPTED, RECEIPT a NAK sa nastavia hodnoty nasledovných bodov (ako posledný sa nastaví Rsp_AppDefId).
Tab. č. 6
| Adresa | Typ | Názov bodu | Popis |
|---|---|---|---|
| 131 | Co | Rsp_AppDefId | Príslušné Snd_AppDefId poslanej SMS správy alebo -1, ak správa s takýmto číslom
nebola nájdená v zozname odoslaných a nepotvrdených správ (napr. po reštarte KOM procesu). Po spracovaní potvrdenia o doručení musí aplikácia meraný bod Rsp_AppDefId nastaviť na 0, čo spôsobí jednak poslanie potvrdenia GAP serveru (správa ACC_RSP resp. REC_RSP, podľa toho, aké na akú správu D2000 KOM odpovedá) a jednak D2000 KOM môže nastaviť ďalšiu hodnotu, pokiaľ má v zásobníku ďalšie potvrdenia o doručení. |
| 132 | Ci | Rsp_ErrNo | Číslo chyby: 0- bez chyby, ďalšie možné hodnoty viď norma [1]. Ak bola prijatá správa RECEIPT, tak Rsp_ErrNo kopíruje hodnotu parametra state s výnimkou hodnôt 2 (delivered) a 6 (accepted) - vtedy je správa považovaná za úspešne doručenú a Rsp_ErrNo=0. |
| 133 | Ci | Rsp_CnfType | Úroveň potvrdenia správy: úroveň 1 - správa bola odoslaná GAP serveru (Rsp_ErrN=0) alebo nastala chyba pri posielaní (Rsp_ErrNo=-1) úroveň 2 - prišla správa ACCEPTED (s nulovým alebo nenulovým chybovým kódom, ktorého hodnota je v Rsp_ErrNo) alebo vypršal timeout Timeout Receive Accept (Rsp_ErrNo=-2) úroveň 3 - prišla správa RECEIPT alebo vypršal timeout Timeout Receive Receipt (Rsp_ErrNo=-3) |
| 134 | TxtI | Rsp_ErrDesc | Textový popis chyby (pri vypršaní timeoutu) alebo hodnota err_type pri negatívnej správe ACCEPT. [err_type - type of error, one of SMSC, MMSC, INTERNAL
|
| 135 | TxtI | Rsp_Serv_Id | 64-bitové ID poslanej SMS správy, ku ktorej sa toto hlásenie vzťahuje. |
| Hodnoty nasledujúcich bodov sú platné iba pri prijatí správy RECEIPT. | |||
| 136 | TxtI | Rec_Submit_Date | Parameter submit_date správy RECEIPT. [date of delivery of sended SMS message to SMS center] |
| 137 | TxtI | Rec_Done_Date | Parameter done_date správy RECEIPT. [date of delivery of sended SMS message to destination] |
| 138 | Ci | Rec_State | Parameter state správy RECEIPT. [state of the message, can have the following values (as described in [2] SMPP 3.4, chapter 5.2.28 message_state):
Poznámka: V prípade, že je prijatá správa RECEIPT so state=1 (prechodný enroute stav), ešte sa raz čaká s timeoutom Timeout Receive Receipt na prijatie správy RECEIPT s finálnym stavom. |
| 139 | TxtI | Rec_Msisdn | Parameter msisdn správy RECEIPT. [msisdn that the message is delivered to. It can be encrypted.] |
| 140 | TxtI | Rec_MsisdnType | Atribút type parametra msisdn. |
Identifikácia stavu komunikácie:
Tab. č. 7
| Adresa | Typ | Názov bodu | Popis |
|---|---|---|---|
| 199 | Di | GAP_SrvConnected | Informácia o tom, či je GAP server pripojený na D2000 KOM proces. Po rozpade komunikácie môže nastať situácia, že D2000 KOM sa pripojí na GAP server, ale GAP server sa spätne nepripojí na D2000 KOM proces. Pokiaľ napr. do minúty po obnovení spojenia na GAP server (stav stanice je StON) je hodnota bodu GAP_SrvConnected FALSE, odporúčame vyskúšať reštart procesu D2000 KOM a ak to nepomôže, kontaktovať zodpovedných za GAP server. |
Atribút type (Rcv_AppAddrType, Rcv_MsisdnType) môže nadobúdať nasledovné hodnoty (číselné hodnoty sú zadávané pri posielaní SMS správ, textové hodnoty prichádzajú pri prijímaní SMS správ):
Tab. č. 8
| Hodnota | Číslo | Popis |
|---|---|---|
| msisdn | 1 | Číslo mobilného užívateľa v tvare +421905123456. |
| alias | 2 | Zašifrované číslo účastníka (šifrovanie vykonáva GAP server), ktorého výsledkom je 32-znakový reťazec (hexa kód). Príklad šifrovania: 421905014940 -> 2F8E47BCAAAB12CA3E19B7DCC2DFDE84. |
| ow | 3 | Norma [1] neuvádza bližšiu definíciu, ale tento typ sa používa iba pri MMS správach. |
Literatúra
[1] Game Data Exchange Protocol Specification 2.4 (poskytnuté spoločnosťou Orange Slovensko, a.s.)
[2] SMPP PS v3.4 (Short Message Peer to Peer Protocol Specification v3.4)
Zmeny a úpravy
-
Revízie dokumentu
- Ver. 1.0 – 2. máj 2006: implementácia protokolu
Súvisiace stránky: