►► G-SMS OpenSMS











Versione: 1.10




Cos'e'?
OpenSMS™ è uno script language che consente la gestione e l'invio di SMS da qualsiasi Provider.

OpenSource
OpenSMS è OpenSource e liberamente estendibile da parte degli utenti.
Questo documento illustra tutte le direttive e le specifiche del linguaggio.

Software Compatibili
Per il corretto funzionamento di OpenSMS, è necessario un browser o un software che interpreti gli script. Attualmente i software che supportano OpenSMS sono:

G-SMS
Nato nel 2005, G-SMS è un software con interfaccia usabile per l'invio di SMS. Dalla versione 1.50 e' OpenSMS-compatibile.

Se hai prodotto un software compatibile OpenSMS e vuoi inserirlo in questo elenco, contattaci!

File di Definizione di un Provider
Per definire un provider si deve creare un file di testo, con estensione ".sms". Ad esempio: "MioProv.sms" potrebbe essere un nome valido per un file di definizione.
Il file deve essere strutturato nel formato degli INI-files: le sezioni sono raggruppate con un titolo compreso tra parentesi quadrate (es: [Global]) ed i valori sono assegnati con la sintassi: VARIABILE=VALORE

Struttura di un file di Definizione
Vediamo subito un esempio di un file di Definizione:

[Global]
OpenSMSVer=1.02
Name=NomeDelProvider
NStep=N
CheckSMSStep=Y
Engine=Z
TextModel=K
Accept=tipi di testo da accettare
AcceptCharSet=charset da accettare
AcceptEncoding=encoding supportati
AcceptLanguage=linguaggi accettati
Agent=Nome identificativo del browser

[STEP1]
URL=http://www.mioprovider.com/login.html
Nparam=3
Param1=login={USER}
Param2=pass={PWD}
Param3=ambient=smssender
Referer=..
PhraseOK=..
..

[STEP2]
URL=..
Referer=..
PhraseOK=..
..

...

[STEPN]
URL=..
Referer=..
PhraseOK=..

Alcune regole:
1) All'interno di ogni sezione, NON E' IMPORTANTE l'ordine di inserimento delle variabili.
2) Le sezioni sono solo di 2 tipi: [Global] contiene i parametri Globali da passare al motore di invio, [STEPX] contiene le informazioni sulla pagina X-esima.
3) Alcune variabili sono NECESSARIE e quindi vanno obbligatoriamente inserite. Altre invece sono OPZIONALI . Nelle prossime sezioni saranno definiti i diversi tipi di variabili.

Nelle sezioni [STEP] e' possibile specificare delle DIRETTIVE (tra parentesi graffe {}), ovvero delle variabili che verranno interpretate dal software.
Ad esempio, {USER} dev'essere sostituita dallo username dell'utente.
Tutte le direttive sono specificate più sotto nella sezione apposita.

Quanti passi sono necessari per l'invio di un SMS?
La risposta non e' univoca, per questo OpenSMS prevede 3 fasi sequenziali:

> LOGIN

> CONTROLLO SMS (1 STEP)

> INVIO

Le fasi di Login e Invio possono essere lunghe N passi (STEP), mentre la fase di Controllo SMS e' lunga 1 passo.
La Variabile "CheckSMSStep" (vedi sotto) definisce il numero dello step di Controllo SMS; tutti gli step precedenti servono per la fase di Login, mentre i successivi per la fase di invio.
Quindi, detto x lo Step corrente:

1<=x<CheckSMSSteps indica gli step per il login
x=CheckSMSStep indica lo step di Controllo SMS
CheckSMSStep<x<=Nstep indica gli step per l'invio




Variabili per la sezione [Global]

OpenSMSVer
Opzionale: NO
Specifica la versione di OpenSMS utilizzata. la versione e' della forma X.YZ, con X,Y,Z interi compresi tra 0 e 9.
ESEMPIO: OpenSMSVer=1.00

Name
Opzionale: NO
Specifica il nome del Providers
ESEMPIO: Name=Alice

NStep
Opzionale: NO
Specifica il numero totale di passi (STEP) necessari per l'invio dell'SMS
ESEMPIO: NStep=4

CheckSMSStep
Opzionale: NO
Specifica il numero del passo in cui avviene il controllo SMS residui.
Se si pone CheckSMSStep=0, NON verrà effettuato il controllo SMS. Gli sms massimi saranno quelli specificati in SMSmax e verranno decrementati di 1 ad ogni invio.
Utile nel caso si voglia realizzare un invio "ceco", senza cioè controllo degli sms residui.
ESEMPIO: CheckSMSStep=3

Engine
Opzionale: SI
Specifica il motore di invio da utilizzare, nel caso il software preveda piu' di un motore. Di default si assume Engine=0.
ESEMPIO: Engine=1

TextModel
Opzionale: SI
Specifica il Modello di testo da utilizzare per l'invio dell'SMS, nel caso il Software preveda l'utilizzo di Modelli di testo predefiniti. Di default TextModel=0.
ESEMPIO: TextModel=1

Accept
Opzionale: SI
Specifica i tipi di documenti da accettare.
ESEMPIO: Accept=text/html

AcceptCharSet
Opzionale: SI
Specifica il set di caratteri da accettare.
ESEMPIO: AcceptCharSet=ISO-8859-1

AcceptEncoding
Opzionale: SI
Specifica il tipo di encoding supportato.
ES: AcceptEncoding=gzip

AcceptLanguage
Opzionale: SI
Specifica i linguaggi accettati.
ESEMPIO: AcceptLanguage=ita

Agent
Opzionale: SI
Specifica l'identificativo del browser
ESEMPIO: Agent=Mozilla

SMSmax
Opzionale: SI
Versione: 1.01
Specifica il numero max di SMS per quel provider. Se SMSmax non e' definito (oppure e' uguale a 0) si intende il valore di default, cioe' 10 sms.

SMSinviati
Opzionale: SI
Versione:1.01
Specifica se gli SMS visualizzati nello STEP "CheckSMS" sono quelli inviati oppure quelli residui.
"SMSinviati" può assumere i valori 1 o 0. Di default, SMSinviati=0, cioe' si intende che gli SMS visualizzati sono quelli RESIDUI.

SMSoffset
Opzionale: SI
Versione:1.01
Specifica un eventuale scostamento tra gli sms visualizzati nel sito e gli sms effettivamente disponibili.
ES: se un sito segna 1 sms residuo, ma in realta' sono gia' esauriti, impostare SMSoffset=-1

EmailMode
Opzionale: SI
Versione:1.03
Puo' assumere i valori 1 o 0.
Se pari a 1, specifica che il provider prevede l'invio di sms via email.
ES: EmailMode=1

EmailDest
Opzionale: SI
Versione:1.03
Specifica l'indirizzo email a cui inviare il messaggio.
Utilizza la direttiva {DEST} (vedi piu' avanti). Questo sarà l'indirizzo a cui verrà inviato il messaggio.
ES: EmailDest={DEST}@mioprovider.com

GSMMode
Opzionale: SI
Versione:1.05
Puo' assumere i valori 1 o 0.
Se pari a 1, specifica che il provider prevede l'invio di sms via GSM Modem (normalmente un telefono o una PC Card GSM/GPRS/UMTS collegati al PC).
ES: GSMMode=1

SMSinterval
Opzionale: SI
Versione:1.06
E' il numero di secondi che trascorrono tra l'invio di un SMS e il successivo.
In caso non sia specificato, si intende l'intervallo minimo possibile (dipende dal software).
ES: Per specificare un intervallo di 5 secondi usare:
SMSinterval=5

StepInterval
Opzionale: SI
Versione:1.09
E' il numero di secondi che trascorrono tra uno Step e il successivo.
In caso non sia specificato, si intende l'intervallo minimo possibile (cioè 0).
ES: Per specificare un intervallo di 5 secondi usare:
StepInterval=5

ModelN
Opzionale: SI
Versione:1.08
N Puo' assumere un qualsiasi valore numerico
Specifica quale file Modello utilizzare quando ci sono N sms residui nell'account.
ES: Model8=miomod.txt significa che, a 8 sms residui, utilizzera' il file "miomod.txt" come testo da inviare.
NOTE:
- i file specificati vanno inseriti nella cartella \Modelli
- questa impostazione ha priorità su altre impostazioni sui modelli specificate dall'utente

DoubleDestN
Opzionale: SI
Versione:1.08
Se TRUE, a N sms residui, il destinatario viene "raddoppiato".
ES: Se il nostro destinatario e' 3481234567 e DoubleDest7=TRUE, quando ci saranno 7 sms residui nell'account, il destinatario diventera' 3481234567|3481234567




Variabili per le sezioni [Step]

URL
Opzionale: NO
Specifica l'indirizzo http da raggiungere.
ESEMPIO: URL=http://www.mioprovider.com/login.jsp

Method
Opzionale: NO
Specifica il metodo di accesso. Puo' assumere solo 2 valori: GET o POST
ESEMPIO: Method=GET

Referer
Opzionale: SI
Specifica l'URL di riferimento per la pagina corrente.
ESEMPIO: Referer=http://www.mioprovider.com/paginaprecedente.html

NParam
Opzionale: SI
Specifica il numero di parametri passati nella chiamata.
ESEMPIO: NParam=4

ParamX
Opzionale: SI
SpecificailparametroX-esimo,dove1<=X<=NParam. Di solito il valore e' nella forma "parametro=id", dove id e' il valore del parametro
ESEMPIO: Param2=login={USER}

PhraseOK
Opzionale: SI
Versione: 1.07
Specifica una o piu' frasi, contenute nel documento html caricato, per validare la pagina. E' possibile controllare questo valore via software per decidere se la pagina e' stata caricata con successo o c'e' qualche errore. Ogni frase va separata dal carattere |
ESEMPIO: PhraseOK=sms inviato correttamente|invio effettuato

PhraseKO
Opzionale: SI
Versione: 1.07
Specifica una o più frasi, contenute nel documento html caricato, per NON validare la pagina. Nel caso questa stringa venga trovata, significa che c'e' qualche errore. Ogni frase va separata dal carattere |
ESEMPIO: PhraseKO=utente non riconosciuto|login errato

PhraseSMS
Opzionale: -
E' obbligatorio e necessario solo nello STEP di controllo SMS.
Specifica l'insieme di caratteri, nell'HTML caricato, che precede il numero di SMS residui per l'account. Ad esempio, se l'html contiene la stringa:
..
var smsresidui = 8
..
sara' necessario specificare $var smsresidui = $ come valore di PhraseSMS. Sono nesessari due simboli qualsiasi (nell'esempio sono due dollari - $ - ) in apertura e chiusura. Attenzione agli spazi!
ESEMPIO: PhraseSMS=$var smsresidui = $

PhraseSMS1
Opzionale: SI
Puo' essere inserito solo nello STEP di controllo SMS. Serve ad indicare una stringa presente nel caso ci sia 1 solo SMS residuo. Utile con alcuni provider.
ESEMPIO: PhraseSMS1=$resta solo 1 sms$

PhraseSMS0
Opzionale: SI
Come il precedente, ma serve ad indicare una stringa presente nel caso ci siano 0 SMS residui (SMS esaurit). Utile con alcuni provider.
ESEMPIO: PhraseSMS0= $smsesauriti per oggi!$

ImageID
Opzionale: SI
Versione: 1.02
Specifica l'URL di una immagine JPG o GIF da mostrare all'utente per la richiesta di un codice. Normalmente l'immagine contiene un codice da digitare per poter proseguire con l'invio dell'SMS

NCookie
Opzionale: SI
Versione: 1.03
Specifica il numero di Cookie che si desidera utilizzare. Utile nel caso si vogliano utilizzare i valori dei cookie nell'URL. I cookie andranno specificati attraverso la direttiva {COOKIEx} (vedi sotto).
ES: NCookie=2

Cookiex
Opzionale: SI
Versione: 1.03
Specifica il nome del cookie che si vuole leggere.
ES: Cookie1=JSESSIONID specifica che il Cookie1 conterrà il valore del cookie "JSESSIONID"

CookieNamex,CookieValuex,CookieDomainx
Opzionale: SI
Versione: 1.10
Permettono di specificare dei cookie da aggiungere (o modificare) nella sessione corrente. X va da 1 a 10. Esempio:
CookieName1=login
CookieValue1=ABC123
CookieDomain1=mysite.it
Inserisce un cookie di nome "login" con valore "ABC123" nel dominio "mysite.it"

HTML1l , HTML1r, HTML12 , HTML2, rHTML3l , HTML3r
Opzionale: SI
Versione: 1.04
Servono a delimitare ed individuare una particolare stringa (HTML1) nel sorgente html di una pagina web.
HTML1l è pari alla stringa a sinistra di HTML1, mentre HTML1r + pari alla stringa a destra.
ES: supponiamo che l'html contenga questa frase:
<a href="#" title="Ritorna alla homepage" tabindex="1">
Per individura la frase "Ritorna alla homepage" dovremo porre, ad esempio:
HTML1l=href="#" title="
HTML1r="
In questo modo, in {HTML1} avremo la frase: Ritorna alla homepage
Attualmente è possibile individuare un massimo di 3 stringhe (HTML1, HTML2, HTML3), utilizzando i rispettivi comandi.




Direttive per le sezioni [Step]

Identificativi dell'utente:

{USER}
Username corrente

{PWD}
Password

{ID}
Identificativo aggiuntivo (es: se sono necessari piu' identificativi. Puo' essere, ad esempio, il numero di telefono dell'utente)

{ID1},{ID2},..,{ID5}
Identificativi aggiuntivi (fino a 5) divisi da simbolo "|" nella definizione dell'account utente. Esempio: se nel campo "ID Aggiuntivi" inserisco: "logs|12345" con {ID1}mi riferisco a "logs" e con {ID2} a "12345"

Gestione Testo del SMS:

{TXT}
Testo dell'sms

{ENCTXT}
Testo dell'sms, URL-Encoded

Gestione Destinatario:

{DEST}
Numero telefonico completo del destinatario dell'sms

{DESTPREFIX}
Prefisso telefonico del destinatario (solitamente le prime 3 cifre del numero)

{DESTNUMBER}
Numero telefonico del destinatario (senza prefisso!!!)

Gestione avanzata:

{IMAGEID}
Versione: 1.02
ImageID contiene il codice digitato dall'utente dopo aver visualizzato l'immagine il cui URL è contenuto in IMAGEID=...

{COOKIEx}
Versione: 1.03
COOKIEx contiene il valore dell'x-esimo Cookie specificato.
ES: {COOKIE1} contiene il valore del Cookie 1. Vedi anche le variabili NCookie e Cookiex.

{HTML1}, {HTML2}, {HTML3}
Versione: 1.04
{HTML1} contiene il valore della stringa HTML1, dedotta dal sorgente di una pagina tramite HTML1l e HTML1r. Vedere la sezione corrispondente per istruzioni su come acquisire la stringa. HTML2 e HTML3 sono analoghe a HTML1.
ES: URL = http://www.miosito.com/sms?ID={HTML2}

{RAND1}, {RAND4}, {RAND8}
Versione: 1.09
Permettono di generare una stringa random della lunghezza, rispettivamente, di 1,4,8 caratteri. Possono essere utilizzati in sequenza.
Ad esempio per generare una stringa random di lunghezza 5 caratteri:
ES: URL = http://miosito/image{RAND1}{RAND4}.jpg




CHANGELOG

v1.10 - 05-08-2010
Aggiunti:
CookieNamex,CookieValuex,CookieDomainx
{ID1},{ID2},..,{ID5}

v1.09
Aggiunti:
StepInterval
{RAND1},{RAND4},{RAND8}

v1.08
Aggiunti:
ModelN
DoubleDestN

v1.07
Modificati (ora sono multi-stringa)
PhraseOK
PhraseKO

v1.06
Aggiunti:
SMSinterval

v1.05
Aggiunti:
GSMMode

v1.04
Aggiunti:
HTML1l , HTML1r, HTML12 , HTML2, rHTML3l , HTML3r
{HTML1}, {HTML2}, {HTML3}

v1.03
Aggiunti:
EmailMode
EmailDest
NCookie
Cookiex
{COOKIEx}

v1.02
Aggiunti:
ImageID
{IMAGEID}

v1.01
Aggiunti:
SMSmax
SMSinviati
SMSoffset