Mobilchange news Obsah dokumentace Uživatelská dokumentace Administrátorská dokumentace Rejstřík pojmů Technická podpora Hledání on-line
Integrace aplikací třetích stran do MobilChange

Technický návod

  1. Úvod
  2. Logika CTL souborů
  3. Konfigurace aplikace v MobilChange
  4. Odeslání SMS
    1. Textová SMS
    2. Binární SMS
  5. Reporty o zpracování zprávy
  6. Příjem SMS zpráv
  7. Schopnosti jednotlivých odesílacích kanálů MobilChange

Úvod

MobilChange (dále MX) se svým okolím komunikuje pomocí textových souborů ve filesystému. Nad nimi jsou postaveny i "vyšší" komunikační nástroje - např. COM objekt pro odesílání SMS. Tento dokument popisuje doporučený postup pro odesílání i příjem SMS pomocí souborů.

MX počítá s tím, že SMS může najednou odesílat i přijímat několik aplikací, a to i souběžně s běžnými uživateli používajícími MX z e-mail klienta nebo WWW formuláře. Každá aplikace je identifikována svým jménem - to může být vcelku libovolné, ale mělo by obsahovat jen anglická písmena.

Poznámky:

zpět na začátek

Logika CTL souborů

Každá komunikace mezi MX a okolím je složena ze dvou souborů. První z nich (řídící, CTL) obsahuje informace "co udělat" - o co jde, od koho, komu..., druhý obsahuje vlastní data ke zpracování. První soubor v sobě vždy obsahuje odkaz na soubor druhý. Tj. například při odesílání SMS se do adresáře mail/in/ ukládá soubor s příponou CTL, který obsahuje informace od koho SMS je, komu a jak se má doručit, a také odkaz na soubor druhý, s příponou TXT. V něm je text SMS k odeslání.

Při vytváření těchto dvoji souborů je doporučen následující postup:

  1. Vytvořit datový soubor (TXT), naplnit jej daty a zavřít.
  2. Vytvořit řídící soubor, ale s jinou příponou (např. ".writing").
  3. Naplnit jej daty a zavřít.
  4. Přejmenovat řídící soubor na příponu CTL.
Okamžikem přejmenování říkáme MX, že je jí soubor k dispozici - od té doby na něj naše aplikace již nesmí sahat.

Jméno CTL i TXT souboru musí být unikátní - tj. není možné např. opakovat stejné jméno TXT souboru pro více zpráv.

Příjem souborů od MX by měl probíhat stejnou logikou - teprve pokud se objeví řídící soubor se správnou příponou, otevřeme jej a načteme z něj potřebné informace a jméno datového souboru.

zpět na začátek

Konfigurace aplikace v MobilChange

Pro odesílání SMS zpráv stačí vymyslet unikátní jméno pro novou aplikaci a vytvořit pro ní adresář pro příjem zpráv: (MobilChange)/script/in/(jméno aplikace)/.

Pro příjem zpráv je dále potřeba v aplikaci mxRouteCfg udělat nové směrovací pravidlo - filtr na telefonní číslo i na text zprávy nastavte na ".*" (bez uvozovek), pokud chcete dostat všechny zprávy. Dále zvolte jazyk "aa" a volbu "pokračovate ve zpracování dalších pravidel pro tuto zprávu" - tím umožníte i dalším aplikacím, aby SMS zpracovaly. Pokud nechcete, aby SMS došla i do e-mailu, pak u poslední aplikace v seznamu, jejímž filtrům by SMS odpovídala, nastavte volbu "zastavit zpracování pravidel pro tuto zprávu". Následně doporučujeme v mxRouteCfg otestovat, zda směrování zpráv probíhá podle Vašich představ.

zpět na začátek

Odeslání SMS

Odeslání SMS se provádí vytvořením dvojice souborů - *.CTL a *.TXT v adresáři (MobilChange)/mail/in/ - též nasdíleno jako share MxInQueue.

Soubor *.CTL obsahuje informace o odesilateli a příjemci SMS, o režimu jejího odesílání a odkaz na soubor *.TXT. Ten pak obsahuje vlastní text SMS.

Textová SMS

Řídící soubor s příponou .CTL by měl mít formát dle následujícího popisu. Měňte jen položky označené tučnou kursivou. Červeně jsou vyznačeny doporučené hodnoty - pokud nevíte, použijte je.

[system]
type=email
priority=normal
 Povolené jsou hodnoty "high", "normal" a "low", kde SMS vyšší priority předbíhají ve zpracování ty s nižší prioritou
sent=3ffaede7
 Čas vytvoření SMS - počet sekund od 1.1.1970 jako hexačíslo. Pokud Vaše aplikace neumí vytvořit, nechte zde tuto ukázkovou hodnotu.
TIP: printf( "%08.8x", time() );
subject= Subjekt e-mail zprávy. Nemá smysl u zpráv generovaných z aplikace = nechte prázdné.
nomodify=1
 1 = Nemodifikovat text zprávy.
0 = Přeformátovat zprávu - odstranit nadbytečné mezery, přidat informace o odesilateli...
display_cc=
display_to=
msg=TEST_1_3ffaede7.txt
 Jméno textového souboru ve stejném adresáři. Soubor obsahuje text SMS zprávy. Pokud to transportní kanál umožňuje, odesílá se v plné kvalitě, tj. včetně konců řádků a podobných znaků.
dr=1
 1 = Požadován Delivery Report
0 = Nepožadován DR
Delivery Reporty nejsou podporovány vždy - záleží od použitého ovladače a zařízení.
displayonly=0
 1 = SMS "jen na displej" - zobrazí se, i když má uživatel plné úložiště SMS. Další SMS stejného typu ji přepíše.
0 = Klasická SMS
user_app_id=15454 Aplikační ID dané SMS. MX toto číslo nijak nezpracovává, jen ho předává v každé další informační zprávě o této SMS, takže aplikace ví, o které SMS se mluví.
Pokud nemátežádné ID k vyplnění, nechte položku prázdnou, tj.
user_app_id=
replyrequired=0
 1 = Po zobrazení SMS telefon upozorní, že odesilatel požaduje odpověď - a většinou rovnou nabídne psaní SMS. Není podporováno u všech telefonů - pokud to telefon neumí, SMS jen normálně zobrazí.
0 = Klasická SMS
from_number=9001230
 Telefonní číslo, které se má nastavit jako odesilatel SMS. Tato funkce je podporována jen na některých ovladačích. Je možno nastavit jen čísla, která se dohodnou s operátorem.
Pokud nechcete číslo nastavovat, položku neuvádějte!
via_line=line3
 Explicitní určení, přes kterou linku má SMS odejít.
Pokud nechcete směrování nastavovat, položku neuvádějte!
maxlen=3
 Na kolik SMS se má text maximálně rozdělit, pokud je delší než 160 znaků?
Pokud nechcete určovat, položku neuvádějte!
[user]
cmd=email=$Ajméno_aplikace
 Doplňte jméno své aplikace.
cmd=address=
cmd=assist_n=
cmd=assist_p=
cmd=off_ph_2=
cmd=city=
cmd=company=
cmd=country=
cmd=custom_1=
cmd=custom_2=
cmd=custom_3=
cmd=custom_4=
cmd=custom_5=
cmd=custom_6=
cmd=custom_7=
cmd=custom_8=
cmd=custom_9=
cmd=custom_10=
cmd=department=
cmd=off_fax=
cmd=first_name=
cmd=home_ph_1=
cmd=home_ph_2=
cmd=last_name=
cmd=mobile=
cmd=office=
cmd=pager=
cmd=off_ph_1=
cmd=postcode=
cmd=state=
cmd=title=
cmd=usr1=
cmd=usr2=
cmd=usr3=
[from]
name=$Ajméno_aplikace
gateway=*
email=$Ajméno_aplikace
smtp=$Ajméno_aplikace		 Doplňte jméno své aplikace.
[to]
to=jméno adresáta
name=jméno adresáta		 Vyplňte jméno adresáta, nebo (pokud není k dispozici) jeho telefonní číslo. Používá se pro větší přehlednost při prohlížení fronty či archivu.
company=
dept=
title=
assist_ph=
type=TO
number=telefonní číslo
 Telefonní číslo adresáta. MX umí jak "+420603123456", tak "603123456".

Sekce [to] se může libovolněkrát opakovat - SMS je pak odeslána na více adresátů.

V textovém souboru odkazovaném položkou msg je text, který se má odeslat. Pokud je delší než maximální délka SMS, je rozdělen na více částí. Pokud obsahuje češtinu, je převeden do textu "bez hacku a carek".

Binární SMS

Řídící soubor s příponou .CTL by měl mít formát dle následujícího popisu. Měňte jen položky označené tučnou kursivou. Červeně jsou vyznačeny doporučené hodnoty - pokud nevíte, použijte je.

[system]
type=email
class=3
priority=normal
 Povolené jsou hodnoty "high", "normal" a "low", kde SMS vyšší priority předbíhají ve zpracování ty s nižší prioritou
sent=3ffaede7
 Čas vytvoření SMS - počet sekund od 1.1.1970 jako hexačíslo. Pokud Vaše aplikace neumí vytvořit, nechte zde tuto ukázkovou hodnotu.
subject=
display_cc=
display_to=
displayonly=0
nomodify=1
msg=TEST_1_3ffaede7.txt
 Jméno textového souboru ve stejném adresáři. Soubor obsahuje SMS zprávu v PDU formátu.
dr=1
 1 = Požadován Delivery Report
0 = Nepožadován DR
Delivery Reporty nejsou podporovány vždy - záleží od použitého ovladače a zařízení.
user_app_id=15454 Aplikační ID dané SMS. MX toto číslo nijak nezpracovává, jen ho předává v každé další informační zprávě o této SMS, takže aplikace ví, o které SMS se mluví.
Pokud nemátežádné ID k vyplnění, nechte položku prázdnou, tj.
user_app_id=
from_number=9001230
 Telefonní číslo, které se má nastavit jako odesilatel SMS. Tato funkce je podporována jen na některých ovladačích. Je možno nastavit jen čísla, která se dohodnou s operátorem.
Pokud nechcete číslo nastavovat, položku neuvádějte!
via_line=line3
 Explicitní určení, přes kterou linku má SMS odejít.
Pokud nechcete směrování nastavovat, položku neuvádějte!
[user]
cmd=email=$Ajméno_aplikace
 Doplňte jméno své aplikace.
cmd=address=
cmd=assist_n=
cmd=assist_p=
cmd=off_ph_2=
cmd=city=
cmd=company=
cmd=country=
cmd=custom_1=
cmd=custom_2=
cmd=custom_3=
cmd=custom_4=
cmd=custom_5=
cmd=custom_6=
cmd=custom_7=
cmd=custom_8=
cmd=custom_9=
cmd=custom_10=
cmd=department=
cmd=off_fax=
cmd=first_name=
cmd=home_ph_1=
cmd=home_ph_2=
cmd=last_name=
cmd=mobile=
cmd=office=
cmd=pager=
cmd=off_ph_1=
cmd=postcode=
cmd=state=
cmd=title=
cmd=usr1=
cmd=usr2=
cmd=usr3=

[from]
name=$Ajméno_aplikace
gateway=*
email=$Ajméno_aplikace
smtp=$Ajméno_aplikace		 Doplňte jméno své aplikace.
[to]
to=jméno adresáta
name=jméno adresáta		 Vyplňte jméno adresáta, nebo - pokud není k dispozici - jeho telefonní číslo. Používá se pro větší přehlednost při prohlížení fronty či archivu.
company=
dept=
title=
assist_ph=
type=TO
number=telefonní číslo
 Telefonní číslo adresáta. MX umí jak "+420603123456", tak "603123456".

Sekce [to] se nesmí opakovat. Telefonní číslo v ní určené musí být totožné s číslem, které je zakódováno v PDU zprávě. U některých ovladačů se pro skutečné odeslání používá číslo z PDU; číslo v sekci [to] se však používá pro routing SMS na správnou odesílací linku.

V textovém souboru odkazovaném položkou msg je SMS v PDU formátu - bez dalších znaků, tj. bez konců řádků atd. PDU musí být plnohodnotné - pro kontrolu doporučujeme program PduSpy.

zpět na začátek

Reporty o zpracování zprávy

Do adresáře (MobilChange)/script/in/(jméno aplikace)/ jsou doručovány reporty o zpracování SMS v MX. Report se vždy skládá ze dvou souborů:
Z řídícího souboru používejte jen položku msg, která odkazuje na jméno souboru datového. V datovém souboru jsou pak zakódovány všechny potřebné informace.

POZOR! Neprovádějte zpracování tak, že čekáte na soubor *.txt - mohlo by dojít k problémům se sdílením souborů. Čekejte na objevení se souboru *.notify.sms, načtěte jej a použijte položkou msg odkazovaný textový soubor.

První položkou v TXT souboru je "msg_type". Ta obsahuje jméno zprávy, která je zasílána. Existují následující typy zpráv, které se týkají odesílané SMS:

Textový soubor může obsahovat následující položky:

Jméno položky
 Popis
 Zprávy, v nichž se vyskytuje
msg_type
 Jméno typu zprávy.
 všechny
description
 Popis daného typu zprávy - human readable (pro ladění atd.)
 všechny
name
 Jméno adresáta
 všechny
number
 Telefonní číslo, na které byla/měla být zpráva odeslána.
všechny kromě e_nosms
user_app_id
 Aplikační ID z odesílané zprávy
 všechny
time
 Čas odeslání ve tvaru YYYY/MM/DD hh:mm:ss
 všechny kromě e_nosms
operator
 Jméno GSM operátora, jehož sítě se to týkalo.
Pozor! Není v normalizovaném tvaru, zapisuje se zde to, co vrátí GSM modul.
 všechny kromě e_nosms
line
 Jméno linky, přes kterou SMS odcházela
 všechny kromě e_nosms
cost
 Cena odeslání
 všechny kromě e_nosms
num
 Na kolik SMS byl text rozdělen?
 všechny kromě e_nosms
rcv
 Čas doručení na cílový mobilní telefon.
 sent_ok_dr
text
 Náhled rozdělení SMS.
POZOR! Tato položka může obsahovat i znaky typu "konec řádku" atd., a proto je ohraničena řídícími znaky - na začátku je 0x02 (STX), na konci 0x03 (ETX).
 všechny kromě e_nosms
drtext
 Text DR/NDR zprávy od operátora.
POZOR! Tato položka může obsahovat i znaky typu "konec řádku" atd., a proto je ohraničena řídícími znaky - na začátku je 0x02 (STX), na konci 0x03 (ETX).
 sent_err_ndr. sent_ok_dr, sent_err_timeout
errors
 Popis problémů.
POZOR! Tato položka může obsahovat i znaky typu "konec řádku" atd., a proto je ohraničena řídícími znaky - na začátku je 0x02 (STX), na konci 0x03 (ETX).
 sent_err_send

Ukázka reportu:

msg_type=sent_ok_wait
description=Your message has been sent to SMS center. Delivery or non-delivery report will be send.
name=MZa
user_app_id=15454
number=420777267556
time=2004/01/06 17:29:28
operator=Virtual/Debug
line=line1
cost=1.05
num=1
text=[STX]*stav#F:$AMainRouter test SMS s koncem radku[ETX]

Formátovací soubory pro reporty si můžete prohlédnout v adresáři (MobilChange)/data/aa/. Zde uvidíte konkrétní pořadí položek i to, které položky jsou v kterém typu souborů.

zpět na začátek

Příjem SMS zpráv

Do adresáře (MobilChange)/script/in/(jméno aplikace)/ jsou kromě reportů o zpracování odesílaných zpráv předávány též přijaté zprávy, u nichž byl nastaven routing do dané aplikace (via mxRouteCfg).

Zpracování CTL/TXT souborů je popsáno zde - u přijatých SMS je to stejné.

Formát TXT souboru přijaté SMS zprávy je následující:

msg_type=rcv_sms
 Typ: přijatá SMS
number=+420603123456
 Telefonní číslo odesilatele
time=2004/01/06 18:24:41
 Čas doručení SMS do MX ve tvaru YYYY/MM/DD hh:mm:ss
operator=Paegas
 Jméno GSM operátora, v jehož síti je přihlášen daný GSM modul.
Pozor! Není v normalizovaném tvaru, zapisuje se zde to, co vrátí GSM modul.
line=line1
 Jméno linky, přes kterou SMS přišla.
U Premium SMS je za jménem linky podtržítko a telefonní číslo, na které byla SMS odeslána, tj. např. line1_9004530.
text=[STX]abc[ETX]
 Text SMS.
Pokud jde o binární SMS, může zde být PDU tvar SMS - nebo zde nemusí být nic.
POZOR! Tato položka může obsahovat i znaky typu "konec řádku" atd., a proto je ohraničena řídícími znaky - na začátku je 0x02 (STX), na konci 0x03 (ETX).
binary=0
 0 = textová SMS
1 = binární SMS
pdu=0015454454...
 PDU tvar zprávy - u binárních SMS.
Může zde být i u textových zpráv, ale není zaručeno.

zpět na začátek

Schopnosti jednotlivých odesílacích kanálů MobilChange

Ovladač
 Binární SMS
 Delivery reporty
 Nastavení čísla odesilatele
 Premium SMS - více čísel na jedné lince
 Rychlost
T-Mobile UCP/EMI (emi.dll)
 ano
 ne
 ano
 ano
 10/sec
Vodafone CZ (oskar.dll)
 ano
 ne
 ano
 ano
 10/sec
Eurotel BMG (cimd.dll)
 ano
 ne
 ne
 ne
 13/sec
Eurotel M2M (m2m.dll)
 ano
 ano - textové i binární SMS, nemění velikost zprávy
 ano
 ano
 2/min
O2 SMS Connector (WebServices)
 ano
 ano - textové i binární SMS, nemění velikost zprávy ano
 ano
 ?
GSM moduly a telefony Siemens, Ericsson; GSM brány 2N, Ericsson
 ano
 ano - jen u textových zpráv, zkracují text SMS o několik znaků
 ne
 ne
 5/min
GSM moduly a telefony Nokia
 ano
 ano - jen u textových zpráv, při nastavení drtype=128 nemění velikost zprávy ne
 ne
 5/min

zpět na začátek