zobacz obecne www.KONNEKT.info

Dokumentacja do bramek wtyczki SMS

2003-02-21 v1.4
Zmiany

Wtyczka Konnekt->SMS wysyła krótkie wiadomości tekstowe przy pomocy skryptów, które mają do dyspozycji odpowiedni interfejs. Dzięki temu tekstowi dowiesz się co umożliwia wtyczka, a przeglądając gotowe bramki na pewno nauczysz się pisać własne skrypty :). SMS może być wykorzystywany do bardzo wielu celów, niekoniecznie związanych z SMSami wysyłanymi na komórki. Można np. przygotować skrypt wrzucający tekst na bloga, lub newsa na stronę...
Aktualnie jedynym obsługiwanym językiem skryptowym jest język LUA.

Każda bramka składa się z 3 części: definicji w języku XML, skryptu w języku LUA i plików dodatkowych jak logo (.ico). Poniżej znajdziesz opis wszystkich kolejnych części...

Definicja w XML

Podczas uruchamiania programu w katalogu konnekt/sms wczytywane są wszystkie pliki XML. Na ich podstawie przygotowywane są bramki. Poniżej znajduje się przykładowy XML razem z komentarzami, elementy pogrubione są wymagane.

Format pliku musi być poprawny. Wbudowany parser nie posiada kontroli błędów i generalnie ma wyjątkowo uproszczoną konstrukcję. Wszystkie atrybuty muszą być zawarte w cudzysłowach. Aktualnie rozpoznawane są tylko &qt; w atrybutach i &lt i > w tekście.
Jedyne dozwolone kodowanie to Windows-1250

<?xml version="1.0" encoding="Windows-1250"?>
<sms>
<id>ABC</id>
<!--Raz ustawiony, jednoznaczny, krótki identyfikator-->
<name>Przykład</name>
<!--Nazwa bramki-->
<logo>ico.ico</logo>
<!--Logo - format .ico, rozmiary 16x16 i 32x32. Dozwolony (i zalecany) jest standard XP.-->
<author>...</author>
<!--Autor-->
<version>luty 2003</version>
<!-- Wersja -->
<info>Ble ble ble</info>
<!--Informacja pokazująca się w oknie wysyłania-->
<authorURL>http://.../</authorURL>
<!-- URL związany z autorem -->
<gateURL>http://.../</gateURL>
<!-- URL związany z bramką -->
<acceptNumber>(\+48)?0?[56]\d{8}</acceptNumber>
<!-- Wyrażenie regularne - wzorzec (standard Perl/PCRE) definiujące obsługiwane numery.
Znaki specjalne trzeba koniecznie poprzedzać znakiem \ (backslash).
'/' jest również znakiem specjalnym!
Jeżeli wpisany numer telefonu pasuje do wzorca, bramka zostaje wyświetlona na liście
Wyjaśnienie przykładu, kolejne części wzorca dopasowywane są do kolejnych części numeru:
(\+48)? - Może (?) się pojawić ciąg +48. `+' jest znakiem specjalnym.
0? - Może (?) się pojawić znak 0.
[56] - Musi się pojawić znak '5' lub '6' .
\d{8} - Musi się być dokładnie 8 ({8}) cyfr (\d - od digit).
A więc numer +48600000000 będzie pasował, ale 0700111111 już nie (0 na początku pasuje, ale 7 już nie)...
Więcej informacji na ten temat znajdziesz tutaj. -->
<scriptFile>pf.lua</scriptFile>
<!-- Plik ze skryptem. Dozwolone są pliki *.lua i *.luac (wersja skompilowana). -->
<maxChars>469</maxChars>
<!-- Maksymalna liczba znaków na wiadomość. -->
<maxSendCount>20</maxSendCount>
<!-- Liczba możliwych wysłań przez bramke. Po przekroczeniu tej liczby zostanie wyświetlone ostrzeżenie. -->
<maxParts>1</maxParts>
<!-- Na ile części można podzielić jedną wiadomość. Jeżeli bramka dzieli sama, trzeba podać "1"-->
<maxCharsOnServer>150</maxCharsOnServer>
<!-- Maksymalna liczba znaków na jedną część, jeżeli serwer dzieli wiadomości.
Do ustawienia tylko, gdy maxParts jest równy 1, lub 0 -->
<signature disabled="1">Podpis</signature>
<!-- Informacja przy sygnaturce. Przydaje się, gdy sygnaturka ma specyficzny format.
disabled - okno sygnaturki zostanie wyłączone. -->
<params>
<!-- Lista parametrów przekazywanych do skryptu, które mogą być edytowane w konfiguracji
-->
<param name="ABCtext" type="string" tip="Ble ble" default="TEXT">Wpisz coś</param>
<!-- Opis parametru w konfiguracji.
name
Krótka, jednoznaczna nazwa parametru.
type
Typ - string , int , text , bool , pass , hidden.
Dodatkowo, jeśli podany jest typ "session" zmienna nie będzie dostępna w konfiguracji, a jej wartość będzie pamiętana aż do zamknięcia programu.
tip
Podpowiedź wyświetlana w konfiguracji.
default
Wartość domyślna.
-->
</params>
</sms>

skrypt (LUA)

Aby wysłać wiadomość, SMS kompiluje skrypt i uruchamia go za każdym razem od nowa! Jednym słowem stan skryptu i jego zmiennych nie będzie pamiętany pomiędzy wywołaniami. Jeżeli musisz coś zapamiętać pomiędzy sesjami do wykorzystania są funkcje getVar i setVar...
Skrypty mogą być również w skompilowanej formie (*.luac). Jedyny kompilator z jakim współpracuje sms.dll jest ten dostarczony razem z LuaPlus. Skrypt musi posiadać jedną funkcję - sendSMS do której, jako jedyny parametr przekazywana jest tablica asocjacyjna z tymi kluczami/wartościami:

msg
Treść wiadomości. Jeżeli wiadomość była dłuższa niż maxChars każda z części wysyłana jest osobno, a na początku wiadomości dołączony jest jej numer.
to
Numer docelowy (może być dowolnym ciągiem znaków).
from
Sygnaturka / Podpis
...
Pozostałe elementy listy to parametry zdefiniowane w XMLu.

Zwrócona wartość nie jest brana pod uwagę.

Katalogiem aktywnym skryptów jest katalog Konnekta.
Jeżeli bramka ma korzystać z rozszerzonych funkcji internetowych, może okazać się przydatny skrypt "const.lua" ze stałymi do przekazywania do funkcji...

SMS.dll jest obecnie skompilowany z biblioteką LuaState chodzącą na LUA w wersji 4.2.1.

Funkcje

Duża część atrybutów jest myślę na tyle jasna, że pozwoliłem sobie ich nie opisywać.
Jeżeli funkcja zwraca więcej niż jedną wartość, są one podane w kolejności zwracania.
Jeżeli funkcja zwraca bool, to oznacza on, czy operacja się udała, czy nie...

Podstawowe

setInfo(info [, typ])
Dodaje nową informację do okienka ze stanem przesyłanych wiadomości.
info - tekst
typ - typ (INFO_ w const.lua)
setError([komunikat])
Ustawia komunikat błędu. Cała operacja będzie uznana za nieudaną.
setSuccess([komunikat])
Ustawia komunikat "sukcesu". Cała operacja będzie uznana za udaną (domyślnie jest).
bool setParam(nazwa , wartość)
Ustawia wartość parametru (zdefiniowanego w XMLu).
bool setVar(nazwa , wartość)
Ustawia zmienną bramki. Zmienne przechowywane są przez cały czas działania programu, i można je odczytywać przy pomocy getVar. Aby usunąć zmienną, trzeba wywołać setVar tylko z pierwszym parametrem.
wartość getVar(nazwa)
Pobiera wartość zmiennej bramki.
LOG(tekst)
Zapisuje do konnekt.log informację tekstową. Dołączane są do niej fragment przesyłanej wiadomości i nazwa bramki.
include(nazwa_pliku)
Wykonuje plik tak samo jak dofile, z tą różnicą, że ścieżka jest relatywna do ścieżki aktualnie wykonywanego skryptu.
czas time()
Zwraca aktualny czas w sekundach, tak samo jak f-cja time w C.
tekst_w_iso cp2iso(tekst_w_cp)
Zmienia kodowanie Windows-1250 na Iso-8859-2
tekst_w_cp iso2cp(tekst_w_iso)
Zamienia kodowanie znaków Iso-8859-2 na Windows-1250
tekst_bez_polskich hidePL(tekst)
Usuwa ogonki, w tekście kodowanym w standardach zarówno CP jak i ISO.
nowy_tekst urlEncode(tekst)
Zamienia wszystkie znaki nie alfa-numeryczne na %wartość_znaku_w_hexie
nowy_tekst urlDecode(tekst)
Odwraca proces wykonany przez urlEncode :)

Okna dialogowe

alert(tekst [ , tytuł])
Wyświetla standardowe okienko dialogowe.
bool confirm(zapytanie [ , tytuł])
Wyświetla standardowe zapytanie TAK/NIE i zwraca true/false.
token getToken(info , obraz)
Wyświetla informację, obrazek, pole do wpisywania tekstu i zwraca wpisaną wartość. Osławionym przykładem są tokeny Ideii.
info - informacja wyświetlana nad obrazkiem.
obraz - ścieżka do pliku z obrazkiem do wyświetlenia.

token - wpisany tekst.

Wyrażenia regularne

Jeżeli nie znasz Regular Expressions, poczytaj ich opis na stronie www.php.net
Wszystkie wzorce muszą być "zamknięte" w dwa takie same znaki nie alfa-numeryczne. np.:
"/[abc]+/" , lub "#[abc]#"
Drugi przykład jest wygodne o tyle, że nie wymaga escape'owania znaku '/'. Na końcu, za znakiem zamknięcia wzorca można podawać standardowe flagi jak:
i , m, s , x ,
jak również flagi rozszerzone jak:
A - wzorzec przyrównywany jest do całego tekstu , D - znak $ oznacza tylko koniec tekstu , 8 - tekst jest w formacie UTF8.
Trzeba pamiętać, że przekazywane łańcuchy znaków są escape'owane znakiem '\'. Wszystkie '\' które muszą znaleść się we wzorcu muszą być wpisane dwukrotnie. Aby tego uniknąć, można tekst przekazywać jako [[....]].
wynik preg_match(wzorzec , tekst [ , trafienia])
Wykonuje przyrównanie do wzorca.
tekst - tekst do przyrównania
trafienia - tablica do której zostaną zapisane wyniki. Na pozycji 0 zostanie zapisany cały pasujący fragment tekstu, a na kolejnych fragmenty pasujące do poszczególnych podwzorców.
wynik - 0 , lub 1 + liczba pasujących podwzorców.
wynik preg_matchAll(wzorzec , tekst [ , trafienia])
Wykonuje przyrównanie do wzorca. Wzorzec nakładany jest wielokrotnie na cały tekst.
wartości preg_matchReturn(wzorzec , tekst)
Po przyrównaniu pasujący fragment tekstu zwracany jest jako pierwszy, a następnie wszystkie pasujące podzworce. Np:
data , rok , miesiac , dzien = preg_matchReturn('/(\\d{4})-(\\d{1,2})-(\\d{1,2})'/ , 'Dziś jest 2003-02-20');
nowy_tekst preg_replace(wzorzec , zamiana , tekst [ , limit=0])
Podmienia tekst według podanego wzorca.
zamiana - tekst, którym będą podmieniane pasujące do wzorca fragmenty tekstu. Można wykorzystywać znalezione podwzorce, służą do tego znaki $ (jak w Perlu) i \ (jak w PHP).
Po $ lub \ trzeba podać numer podwzorca od 0 do 9, gdzie 0 jest całym pasującym fragmentem.
Podobnie jak w Perlu $& jest równoznaczne $0.
limit - limit łącznej ilości wykonywanych podmian. 0 - bez limitu

Obsługa sieci

Funkcje obsługi sieci bazują w pełni na f-cjach sieciowych windowsowej biblioteki WinInet, tej samej, z której korzysta Internet Explorer. Na MSDN można znaleźć ich pełną dokumentację... Funkcje mają te same nazwy, i zbliżone atrybuty (kolejność na ogół jest identyczna, nie ma za to atrybutów zbędnych i w niektórych przypadkach tych, których obsługi po prostu tutaj nie ma...). W miarę możliwości zachowałem tutaj podobne nazwy atrybutów.
Wszystkie utworzone uchwyty powinno się zamykać, ale nie trzeba, SMS jest wyposażony w kolektor śmieci i po zakończeniu wykonywania skryptu sam je zwolni.
HSession InternetOpen([UserAgent])
Tworzy sesję. Pierwsza rzecz do wywołania.
HConnection InternetConnect(HSession , ServerHost [ , ServerPort=80 , UserName , Password ])
Nawiązuje połączenie z podanym serwerem (IP lub domena).
HRequest HttpOpenRequest(HConnection[ , Method=GET , Action=/ , Referrer , Flags])
Tworzy zapytanie (jeszcze go nie wysyła!). Wersja ustawiona jest na sztywno na HTTP/1.0
Method - GET / POST
Action - plik/katalog o który chcemy się "pytać". Np "/open.php?module=forum".
Flags - INTERNET_FLAG_* z const.lua
bool HttpSendRequest(HRequest [ , Header , Data ])
Wysyła zapytanie
Header - dodatkowe nagłówki do dołączenia
Data - dodatkowe dane do dołączenia po nagłówkach. W tym atrybucie przekazujemy to co chcemy POSTować.
Data InternetReadFile(HRequest)
Pobiera wynik wysłanego zapytania.
bool InternetWriteFile(HRequest , data)
W tej chwili nie widzę jeszcze zastosowania w skryptach... Ale na pewno przyda się kiedyś przy obsłudze FTP.
InternetCloseHandle(HINTERNET)
Zamyka dowolny otwarty uchwyt sieciowy (H*)
Cookie InternetGetCookie(URL)
Pobiera Cookie dla podanego URL'a
bool InternetSetCookie(URL , Name , CookieData)
Ustawia Cookie dla podanego URLa
ErrorNo , ErrorMsg InternetGetLastResponseInfo()
Pobiera kod błędu ostatniej operacji. Przy HTTP najczęściej niewiele zwróci...
Info HttpQueryInfo(HRequest , InfoLevel)
Pobiera informację o zapytaniu. Przydaje się do analizowania nagłówków odpowiedzi serwera, zwłaszcza HTTP_QUERY_STATUS_CODE i HTTP_QUERY_STATUS_TEXT
InfoLevel - HTTP_QUERY_* w const.lua
bool InternetSetOption(HINTERNET , Flag , Data)
Ustawia opcję któregoś z uchwytów.
Flag - INTERNET_OPTION_ w const.lua
Data InternetQueryOption(HINTERNET , Flag)
Pobiera opcję któregoś z uchwytów.
Flag - INTERNET_OPTION_ w const.lua

Zmiany

v1.6

v1.4

 ©Copyright 2002-2003 Stamina