Mobilchange news Obsah dokumentace Uživatelská dokumentace Administrátorská dokumentace Rejstřík pojmů Technická podpora Hledání on-line
Programování skriptových aplikací

Tento dokument popisuje, jak naprogramovat skriptovou aplikaci nad MobilChange. Očekává od čtenáře znalost jazyka VBScript nebo Visual Basic.

Obsah dokumentu

Úvod

Pokud nestačí standardní funkčnost MobilChange, je možné ji rozšířit pomocí MobilChange VBS skriptingu. Skriptové aplikace lze používat pouze v MobilChange Enterprise, v MobilChange Standard je tato funkčnost vypnuta.

Všechny uživatelské skriptové aplikace běží v prostředí servisu UMS.TaskManager. Ten hlídá jejich funkci a zajišťuje případné restarty. Skripty se spouští uvnitř Windows Scripting Hosta.

Uživatelské aplikace se ukládají do adresáře MobilChange/script/. Různé ukázkové aplikace najdete v adresáři MobilChange/samples/. Použití příkladů je komentováno přímo ve zdrojovém kódu.

zpět na začátek

Odlišnosti MobilChange VBS skriptingu

Část MobilChange knihoven je napsána ve Visual Basic Scriptu (dále VBS). Vzhledem k tomu, že uživatelský skript by měl být co nejjednodušší, je použita technologie includů, známá například z programovacího jazyka C.

Knihovny se k uživatelskému kódu připojují příkazem
  
'#include "soubor.vbs"
  

Jméno souboru v uvozovkách může obsahovat i cestu, relativní vůči adresáři MobilChange/script/.

Při spuštění služby UMS.Task Manager je v rámci "startup" tasku MX_<jméno úlohy> zkompilován soubor MobilChange/script/<jméno úlohy>.vbs , provedeny includy a výsledný soubor je uložen jako MobilChange/script/run/<jméno úlohy>.vbs . Tento soubor je pak spouštěn. Tj. pokud např. VBscript interpreter hlásí syntaktickou chybu na řádku 200, je třeba najít řádek 200 ve zkompilovaném souboru v adresáři MobilChange/script/run/, chybu opravit ve zdrojovém souboru v adresáři MobilChange/script/ a pak zrestartovat UMS.Task Manager, aby došlo k překompilování skriptu.

Výše uvedené platí do verze MobilChange 4.6.23. Ve vyšší verzích se includování nepoužívá - je nahrazeno technologií WSF jobů:

zpět na začátek

Začátek programu

Zdrojový kód uživatelského skriptu do verze MobilChange 4.6.23 musí vždy začínat následujícími dvěma řádky (ve vyšších verzích není potřebný):
  
Option Explicit
'#include "include\mx_script_app.vbs"
  

zpět na začátek

Uživatelská funkce OnInit()

Při spuštění uživatelského skriptu je po provedení všech potřebných inicializací zavolána funkce OnInit. Jako parametr dostává tři proměnné, které musí nainicializovat.
AppName Do této proměnné musí uživatelský skript zapsat své jméno (jméno, pod kterým byl přidán do systému).
ServerName Sem musí aplikace zadat jméno serveru MobilChange, se kterým chce pracovat. Lokální server (počítač, na němž aplikace běží) se označuje prázdným řetězcem ("").

Ve stávající verzi sem nemá smysl zadávat nic jiného, než prázdný řetězec.

IddleTime Zde musí skript zapsat, jak často má být volána funkce OnIddle. Čas se zadává v milisekundách, doporučené minimum je 5000, maximum 60000. Při ukončování činnosti UMS.Taskmanageru se po tuto dobu čeká na ukončení skriptové aplikace. Proto nenastavujte příliš vysokou hodnotu, aby ukončení Taskmanageru netrvalo příliš dlouho.
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku,
řetězec "ERROR" v případě, že došlo k chybě.

Pokud uživatelský kód vrátí "ERROR", je skript ukončen a zrestartován.

Zde je tedy ukázka kompletní funkce OnInit():
  
Function OnInit( AppName, ServerName, IddleTime )
    AppName = "pizza"       ' application "pizza"
    ServerName = ""         ' local server
    IddleTime = 10000       ' 10 seconds, recommended
    ' There can be done additinal initialization tasks
    OnInit = "OK"          ' return status
End Function
  
POZOR!! Uvnitř OnInit() NELZE použít funkce MobilChange.SendSMS/SendSMSEx - ještě není nainicializováno vše potřebné pro odeslání SMS.

zpět na začátek

Uživatelská funkce OnReceivedSMS()

Jakmile je skriptové aplikace doručena nějaká SMS, je zavolána uživatelská funce OnReceivedSMS(). Ta dostává informace o SMS ve svých třech parametrech. Nicméně tato funkce je zde jen pro zpětnou kompatibilitu se staršími verzemi Mobilchange - preferovaná cesta je používat novou funkci OnNotification(), která rovněž dostává informace o došlých SMS a navíc dostává více informací o zprávě.
FromNumber Telefonní číslo odesilatele v mezinárodním formátu.
TimeReceived Čas příchodu SMS jako textový řetězec ve formátu YYYY/MM/DD hh:mm:ss
MessageBody Text přišlé SMS zprávy.
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku,
řetězec "ERROR" v případě, že došlo k chybě.

Pokud uživatelský kód vrátí "ERROR", je skript ukončen a zrestartován. SMS zůstává ve frontě a po restartu bude skriptu znovu předána.

Ukázka kompletní funkce OnReceivedSMS() v uživatelské aplikaci Pizza. Odpovídá na přijatou SMS a do odpovědi vloží text původní SMS.
  
Function OnReceivedSMS( FromNumber, TimeReceived, MessageBody )
    Dim rc

    MXLog "Working on received SMS..."

    MXLog "Sending reply..." 
    rc = MobilChange.SendSMS( FromNumber, 
            "PIZZA SERVICE: You have ordered pizza -" 
            + MessageBody + "- from phone number " + FromNumber + ".", True )
    MXLog "MobilChange.SendSms() = " & rc
    If rc <> "OK" Then
        MXLog "ERROR: " + MobilChange.LastError
    End If
    
    OnReceivedSMS = "OK"    ' return status
End Function
  

zpět na začátek

Uživatelská funkce OnNotification()

Jakmile je skriptové aplikace doručena nějaká SMS, potvrzení o odeslání, (ne)doručení atd., je zavolána uživatelská funce OnNotification() a jsou jí předány tyto parametry:
MessageType Typ události. Možné hodnoty:
  • "sent_ok" - SMS byla odeslána do SMS centra
  • "sent_ok_nodr" - SMS byla odeslána do SMS centra, ale informace o doručení SMS již nebude doručena
  • "sent_ok_wait" - SMS byla odeslána do SMS centra. Informace o doručení nebo nedoručení bude doručena
  • "sent_ok_dr" - SMS byla úspešne doručena
  • "sent_err_send" - SMS nebyla odeslána
  • "sent_err_timeout" - Chyba v průběhu odesílání SMS
  • "sent_err_ndr" - SMS byla odeslána do SMS centra, ale příjemce není dostupný
  • "void" - Neurčená událost
  • "rcv_sms" - Přijatá zpráva. Je zpracována funkcí OnReceivedSMS
  • "e_toolong" - SMS je delší než nastavený limit
  • "preview" - Náhled zprávy rozložené do jednotlivých SMS
  • "oplock_unsupp" - Špatný aktivační klíč do GSM sítě
  • "oplock_tampered" - Pokus odeslat SMS do zakázané GSM sítě
  • "e_nosms" - Uživatel nesmí užívat MobilChange
Attr Kolekce atributů oznámení, jedná se o instanci objektu FxExtObj.DSVariantCol. Kolekce může obsahovat tyto položky:
  • "msg_type" - Typ oznámení - jedná se o stejnou hodnotu jako má parametr MessageType
  • "description" - Krátký popis oznámení
  • "name" - původní telefonní číslo příjemce SMS
  • "number" - normalizované telefonní číslo příjemce SMS
  • "user_app_id" - aplikační identifikátor SMS zadaný ve funkci SendSmsEx
  • "time" - Čas odeslání SMS ve formátu yyyy/mm/dd HH:MM:SS
  • "rcv" - Čas přijetí oznamovací SMS ve formátu yyyy/mm/dd HH:MM:SS
  • "operator" - Jméno GSM operátora
  • "line" - Jméno linky ke GSM operátorovi
  • "cost" - Cena operace
  • "num" - Počet SMS na které byla rozdělena původní zpráva
  • "text" - Text zprávy
  • "drtext" - Text informace o doručení
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku,
řetězec "ERROR" v případě, že došlo k chybě.

Pokud uživatelský kód vrátí "ERROR", je skript ukončen a zrestartován. SMS zůstává ve frontě a po restartu bude skriptu znovu předána.

zpět na začátek

Uživatelská funkce OnIddle()

Funkce OnIddle() je volána systémem tehdy, pokud nejsou po zadanou dobu (nastavuje uživatel ve funkci OnInit() žádné přijaté zprávy. Je určena například k odesílání zpráv o stavu zařízení, výpisů z databází atd.
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku,
řetězec "ERROR" v případě, že došlo k chybě.

Pokud uživatelský kód vrátí "ERROR", je skript ukončen a zrestartován.

Ukázka funkce OnIddle():
  
Function OnIddle
    ' There can be done anything...
    OnIddle = "OK"          ' return status
End Function
  

zpět na začátek

Uživatelská funkce OnShutdown()

Funkce OnShutdown() je volána systémem při ukončení servisu UMS.TaskManager, například tedy při shutdownu počítače. Umožňuje uzavřít databázová spojení, smazat pracovní soubory...
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku,
řetězec "ERROR" v případě, že došlo k chybě.

Pokud uživatelský kód vrátí "ERROR", je skript ukončen a zrestartován.

Ukázka funkce OnShutdown():
  
Function OnShutdown
    ' There can be done anything...
    OnShutdown = "OK"          ' return status
End Function
  

zpět na začátek

Funkce a properties MobilChange

MobilChange nabízí uživatelským skriptům několik funcí a properties. Pomocí nich mohou uživatelské skripty např. odeslat SMS zprávu.

Funkce MobilChange.SendSMS()

Funkce MobilChange.SendSMS() odesílá SMS zprávu. Syntaxe je:

MobilChange.SendSMS( to, text, nomodify )
MobilChange.SendSMS( to, text, nomodify, fromName, fromSMTP, fromEmail, language, DR )
To (textový řetězec) Telefonní číslo adresáta.
Text (textový řetězec) Text zprávy.
NoModify (True/False) Pokud je True, text zprávy je odeslán přesně tak, jak byl zadán aplikací. Pokud je False, text je zpracován pomocí MobilChange stejným zprůsobem, jako odesílané e-maily, tj. jsou vynechány mezery, překódovaná čeština atd.
FromName (textový řetězec) Jméno uživatele, za kterého aplikace SMS odesílá.
Případné potvrzení o doručení bude posláno na toto jméno.
FromEmail (textový řetězec) E-mail adresa uživatele, za kterého aplikace SMS odesílá, v rámci lokálního e-mail systému (tj. např EX: adresa u Exchange serveru).
Případné potvrzení o doručení bude posláno na tuto adresu.
FromSMTP (textový řetězec) SMTP adresa uživatele, za kterého aplikace SMS odesílá.
Tato adresa je použita při formátování odchozí SMS, pokud NoModify=False.
Language (textový řetězec) Kód jazyka uživatele, za kterého aplikace SMS odesílá.
Případné potvrzení o doručení bude posláno v tomto jazyce.
Povolené kódy odpovídají názvům podadresářů v adressáři MobilChange/data/, tj. CZ, UK, ...
DR (True/False) Pokud je True, je vyžadováno potvrzení o doručení. Pokud je False, nechce aplikace potvrzení o doručení.
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku, řetězec "ERROR" v případě, že došlo k chybě.

Příklad použití:
  
Dim rc
rc = MobilChange.SendSMS( "+420603899285", "Hello, World!", True )
MXLog "MobilChange.SendSms() = " & rc
If rc <> "OK" Then
    MXLog "ERROR: " + MobilChange.LastError
End If
  

zpět na začátek

Funkce MobilChange.SendSMSEx()

Funkce MobilChange.SendSMSEx() odesílá SMS zprávu, přičemž má větší možnosti než SendSMS(). Syntaxe je:

MobilChange.SendSMSEx( To, Text, Nomodify, fromName, fromEmail, fromSMTP, language, DR, SendNotify, Priority, UserAppId, OtherOptions )
To (textový řetězec) Telefonní číslo adresáta.
Text (textový řetězec) Text zprávy.
NoModify (True/False) Pokud je True, text zprávy je odeslán přesně tak, jak byl zadán aplikací. Pokud je False, text je zpracován pomocí MobilChange stejným zprůsobem, jako odesílané e-maily, tj. jsou vynechány mezery, překódovaná čeština atd.
FromName (textový řetězec) Jméno uživatele, za kterého aplikace SMS odesílá. Použijte text "$AJmeno_aplikace" (bez uvozovek).
Případné potvrzení o doručení bude posláno na toto jméno.
FromEmail (textový řetězec) E-mail adresa uživatele, za kterého aplikace SMS odesílá, v rámci lokálního e-mail systému (tj. např EX: adresa u Exchange serveru). Použijte text "$AJmeno_aplikace" (bez uvozovek).
Případné potvrzení o doručení bude posláno na tuto adresu.
FromSMTP (textový řetězec) SMTP adresa uživatele, za kterého aplikace SMS odesílá. Použijte text "$AJmeno_aplikace" (bez uvozovek).
Tato adresa je použita při formátování odchozí SMS, pokud NoModify=False.
Language (textový řetězec) Kód jazyka uživatele, za kterého aplikace SMS odesílá.
Případné potvrzení o doručení bude posláno v tomto jazyce.
Použijte text "AA" (bez uvozovek).
DR (True/False) Pokud je True, je vyžadováno potvrzení o doručení. Pokud je False, nechce aplikace potvrzení o doručení.
SendNotify (True/False) Pokud je True, je vyžadováno potvrzení o odeslání do SMS centra. Pokud je False, nechce aplikace potvrzení o odeslání do SMS centra.
Priority (textový řetězec) Priorita zprávy. povolené hodnoty: "high", "normal", "low" (bez uvozovek).
UserAppId (textový řetězec) aplikační Id zprávy. Pokud je vyplněno, je obsaženo i v potvrzení o odeslání/doručení/nedoručení, tudíž aplikace ví, které zprávy se potvrzení týkalo.
Otheroptions (textový řetězec) další nastavení, oddělená znakem "|". Jsou k dispozici tato nastavení:
  • from_number=XXXX - telefonní číslo, ktere se nastaví jako odesílatel (pokud to ovladač podporuje, jen u přímých připojení ke GSM operátorovi a jen povolená čísla)
  • via_line=YYYY - přes kterou linku MX ma SMS odejít
(návratová
hodnota)		 Textový řetězec "OK", pokud je vše v pořádku, řetězec "ERROR" v případě, že došlo k chybě.

zpět na začátek

Property MobilChange.LastError

Property MobilChange.LastError obsahuje textový popis poslední chyby vzniklé ve skriptovém subsystému MobilChange.

Ukázku použití najdete v popisu funkce MobilChange.SendSMS().

zpět na začátek

Funkce MXLog()

Funkce MXLog se používá k zápisům informací o běhu programu do logu. Standardně je log pouze ve formě konzolového výpisu při ladícím režimu servisu UMS.TaskManager. Syntaxe:

MXLog text

Ukázku použití najdete v popisu funkce MobilChange.SendSMS(). Funkce nemá návratovou hodnotu.

Novinka od MobilChange 3.0: Funkce MXLog též může zapisovat své výstupy do textového souboru "\Mobilchange\log\<datum-YYYYMMDD>.<jméno-skriptu>.txt".
Toto se nastavuje v registry

Po instalaci jsou souborové logy vypnuty.

zpět na začátek

Funkce MXSendMail()

Funkce MXSendMail pošle e-mail zprávu (nezávisle na e-mail systému, který používáte). Syntaxe:

MXSendMail(SenderName, SenderEmail, RecipientName, RecipientEmail, Subject, Text, Priority)

kde Priority je číslo - 1 (low), 2 (normal) nebo 3 (high). Pokud používáte Lotus Notes gateway, pak se nebere ohled na parametry SenderName, SenderEmail - vezmou se z Notes ID uživatele, pod nímž gateway běží.

Návratová hodnota je textový řetězec

Ukázka použití:
  
rc = MXSendMail ("SMS server", "smss@vasefirma.cz", "Josef Novak", "jn@volny.cz", "Automaticka odpoved", _
	"Vase SMS z cisla " & FromNumber & " byla prijata a zpracovana v " & Now, 2)
 

zpět na začátek

Funkce MxDeleteSMS()

Funkce MxDeleteSMS umožňuje smazat příchozí SMS kdykoliv během zpracování. Standardní stav je tento: To při chybě v aplikaci vede k tomu, že aplikace je spouštěna stále dokola - a pokud posílá SMS, uživatel dostává stále stejné SMS. Nyní je možno kdykoli ve zpracování příchozí zprávy (OnReceivedSMS i OnNotification) zavolat funkci MxDeleteSMS, která ihned smaže příchozí zprávu - takže při případně chybě se začne zpracovávat následující došlá SMS. Funkce nemá návratovou hodnotu. Syntaxe:

MxDeleteSMS

Ukázka použití nové funkce:
  
Function OnReceivedSMS( FromNumber, TimeReceived, MessageBody ) 

        MxDeleteSMS 

         ... následuje další zpracování SMS ...
 

zpět na začátek

Přidání skriptu do MobilChange

Pokud chcete používat v MobilChange svou skriptovou aplikaci, je potřeba ji přidat do systému a nastavit směrování a filtraci přišlých SMS, aby dostávala jen ty, které se jí týkají.

Přidání skriptu do MobilChange je důkladně popsáno v tomto dokumentu.

Editace směrovacích pravidel se dělá programem MxRouteCfg.

zpět na začátek

Ladění skriptu

Pokud chcete vidět výstup svého skriptu, je možno sputit UMS.TaskManager v ladicím režimu a tedy na obrazovce. Ve Start Menu zvolte Programs -> MobilChange -> Scripting -> Run UMS.TaskManager in debug mode. UMS.TaskManager se spustí, nechá předkompilovat skripty a po chvíli (max 30 sec) spustí uživatelský skript a ostatní aplikace, které v něm mají běžet.

Nyní klikněte na ikonu v levém horním rohu konzolového okna, zvolte "Properties", a na záložce "Layout" nastavte "Screen buffer size" "Height" na 9999. Pak zmáčkněte "OK" a "Save settings for all windows with same title". Na pravé straně konzolového okna tímto přibyl scrollbar a můžete se dívat na starší výpisy. Stiskem klávesy [Pause]/[Break] pozastavíte běžící programy a jejich výstupy, stiskem jakékoli klávesy je opět spustíte.

Ukončení ladícího běhu UMS.TaskManager se provede stiskem kombinace kláves "Ctrl-C" v konzolovém okně (platí i pro níže uvedený způsob).

Další možností je zakázat laděnou úlohu v umsTaskCfg a spouštět ji "ručně" z command promptu takto:
cscript jméno_skriptu.wsf
nebo, pokud požadujeme ladění v debuggeru příkazem:
cscript //X //D jméno_skriptu.wsf

Pokud chcete, aby Vaše skriptová aplikace běžela v samostatném okně (a její výstup se nemísil s výstupem ostatních UMS.TaskManager aplikací), ukončete UMS.TaskManager (stiskem kláves "Ctrl-C") a v programu umsTaskCfg jí (v "běhových" úlohách) vypněte nastavení "shared console".

Upozornění pro uživatele VoiceChange: VoiceChange běží také v prostředí UMS.TaskManager. Tudíž po dobu, kdy UMS.TaskManager bude zastaven (nepoběží ani jako servis, ani v ladícím módu) nebude Vaše VoiceChange obsluhovat příchozí volání!

zpět na začátek