Guida utente di SMuW

Indice

Introduzione

Il progetto nasce per poter inviare SMS da riga di comando tramite piattaforme unix/linux.
SMuW (si veda capitolo *link*) è semplicemente un "interprete" che esegue alcune direttive poste sui plugin. Un plugin contiene tutte le informazioni necessarie per l'inoltro di un SMS (in quale pagina fare il login ecc, si veda capitolo *link*)

Prerequisiti

SMuW E' scritto principalmente in Perl e C, per poterlo utilizzare, sono richiesti i seguenti pacchetti:
perl - Necessario
XML::Simple - Opzionale - serve per la compatibilita con providers.xml
wget -Necessario - utilizzato per connettersi ai siti
gocr - Opzionale - serve al riconoscimento dei codici captcha
djpeg - Opzionale - serve al riconoscimento dei codici captcha
Gtk2::GladeXML - Opzionale - serve a far funzionare l'interfaccia grafica
Gtk2::TrayIcon - Opzionale - utilizzato per minimizzare l'interfaccia sulla traybar

ecco come come installarli su debian/ubuntu

sudo apt-get install libxml-simple-perl  libgtk2-gladexml-perl gocr  libgtk2-trayicon-perl 

In alternativa, li si possono installare con CPAN (compreso in ormai tutte le versione del perl)

perl -MCPAN -e 'force install XML::Simple'
perl -MCPAN -e 'force install Gtk2'
perl -MCPAN -e 'force install Gtk2::GladeXML'
perl -MCPAN -e 'force install Gtk2::TrayIcon'

Installazione

E' disponibile uno script autoinstallante:

wget http://csms.indivia.net/smw-autoinstall && sh smw-autoinstall

Il comando qua sopra scarica ed esegue l'installer, SMuW verra creata la cartella smuw/ , con i seguenti files:

codice/ - cartella del sorgente di pcodice, una piccola finestrella che permette l'inserimento manuale dei captcha
tools/ - contiene alcuni script utili a smuw
gui/ - contiene le immagini e le form dell'interfaccia grafica
siti/ - contiene i plugins per smw (ovvero le informazioni necessarie a smuw per utilizzare i vari siti quali 190.it, rossoalice ecc)
confs/ - cartella con i files di configurazione
smw - eseguibile della versione a riga di comando
smwgui - eseguibile dell'interfaccia grafica lite
smwgui3 - eseguibile della nuova interfaccia grafica
p.xml - XML di wwSMSClient


Verrà anche creata un icona sul desktop collegata all'interfaccia lite.

Utilizzo interfaccia grafica lite

Utilizzo

L'interfaccia grafica è una semplificazione di smw.
Anche se perde molte potenzialità del tool a riga di comando, guadagna rapidità e semplicità di utilizzo.
.
Il tool comprende un unica finestra, dalla quale è possibile gestire providers, plugins, gli accounts e la rubrica.

Ecco come si presenta la finestra al primo utilizzo:

Ci viene immediatamente data la possibilità di inviare un SMS con il sitoweb predefinito (in questo caso Enel.it)
Per cambiarlo, è sufficiente cliccarci sopra e sceglierne un altro dalla lista che comparirà.
I siti che cominciano con i duepunti sono quelli prelevati da wwSMSClient.

Sotto gli account è possibile gestire una rubrica rudimentale ma incredibilmente veloce e intuitiva, per inserire un nuovo contatto, digitarlo e cliccare sul bottone "Aggiungi". viceversa cliccare "Rimuovi per rimuoverlo".

Bugs

Durante l'invio di un SMS per ottenre un aggiornamento sul suo stato è necessario muovere il mouse sopra la finestra, se non viene fatto, l'SMS viene inviato comunque, ma l'interfaccia non si aggiorna correttamente.

Utilizzo nuova interfaccia grafica

Per eseguire la nuova interfaccia grafica, bisogna lanciare il file smwgui3:

cd smw
./smwgui3

Si presenterà la seguente finestra:

La navigazione e l'utilizzo delle varie sezioni è abbastanza intuitiva,

qui di seguito lascio qualche consiglio:
- Per creare un nuovo account:
Scriverne il nome nella casella Nome Account, selezionarne il sito, e inserire le credenziali, sucessivamente cliccare Salvab>
- Per modificare un account:
selezionare dalla casella nome account l'account in questione, al che compariranno tutte le sue informazioni, modificarle a vostro interesse e cliccare Salva
Di seguito sono da inserire le credenziali per accedere al sito in questione, e' possibile memorizzarle per i sucessivi utilizzi
- E' possibile reinviare e inoltrare gli SMS in coda cliccandoci sopra.
- E' possibile inviare più di un SMS contemporaneamente

Utilizzo riga di comando

Utilizzo

La riga di comando permette di fare tutto ciò che avreste potuto fare con l'interfaccia grafica, dato che alla base di queste c'è proprio il tool testuale.
l'eseguibile in questione si chiama smw ed è posto nella cartella smw/ eccone un esempio di utilizzo:

./smw file=190.it user=pippo pass=pluto to=340123456 'text=bonjour!'

penso che si spieghi da solo, un unica cosa: il parametro file e' il nome del plugin, in questo caso e' presente nella cartella siti/

per utilizzare un provider wwSMSClient la sintassi è file=nomefile.xml:NomeProvider, ad esempio per utilizzarne l'equivalente della vodafone: file=p.xml:Vodafone

I files

smuw come detto e' composto da piu files:
smw E' il cuore, l'interprete di tutti gli altri,decide dove e come instradare un sms
confs/smwgun.confs - configurazioni standard
confs/ka - contiene le informazioni per il keepalive
confs/azioni - contine le definizioni per alcune azioni utilizzate da smw
confs/rubrica - file standardp er i contatti della rubrica
confs/accounts - file standard contenente gli accounts

Le variabili

Le variabili utilizzate da smuw sono moltissime, queste possono essere usate e modificate tramite smwgun dai vari plugin per permettere il corretto invio di un sms, oppure essere modificate dall utente.
Alcune variabili vengono gia preimpostate dentro al sorgente di smw,
Altre vengono lette da smwgun.conf successivamente vengono lette quelle passate a riga di comando e quelle scritte nei vari plugin per poter deciedere il corretto instradamento di un SMS

Un esempio di variabile è il destinatario del SMS,
una simile variabile puo essere inserite in diversi momenti e in diversi luoghi: - da linea di comando
- sulla console di smw
- o sui file di configurazione confs/*
- o su un plugin (che poi è un file di configurazione)

le variabili usate dall utente (quindi da riga di comando) solitamente sono:

file - del file plugin da utilizzare
user - l'username col quale ci si e' registrati al sito con cui si vuole mandare il messaggio

pass - la relativa password
to - il numero del destinatario
text - testo del messaggio
from - un eventuale mittente ( solo pochi siti lo richiedono)
account - inserendo un account pre-registrato, verranno inseriti automaticamente anche lgi user e la password (vedi capitolo account)

modeè la modalità di invio:

login - effettua il solo login in quel sito
send - invia solo il messaggio ( si presume che prima sia stato fatto il login )
go - se non è gia stato eseguito effettua il login, se no solo il send
v - visualizza tutte le variabili impostate

.xxxx - le variabili che iniziano col punto per convenzione indicano un contatto della rubrica (vedi capitolo rubrica)

Invio di un SMS

Ecco come puo avvenire il semplice invio di un SMS

spocchio@geppetto:~/smw$ ./smw file=vodafoneit user=username pass=password to=340123456 'text=hey ciao come va?'
 # SmwGun [1.0b]
 # loading vodafone
 # mode =  stato = 
stato = ok
spocchio@geppetto:~/smw$

Notiamo che:

1. Sono state passate tuttele variabili necessarie all invio tramite liena di comando
2. Il testo è stato ragruppato tra apici perche contiene spazi.
3. stato = ok implica che tutto è andato abuon fine, se no avrebbe segnalato l'errore piu probabile

Ora, se reinviamo l'sms:

spocchio@geppetto:~/smw$ ./smw file=vodafoneit to=340123456 'text=si anche a me tutto ok dai'

 # SmwGun [1.0b]
 # loading vodafone
 # mode =  stato =
warning.campi = user
warning.campi = pass
stato = ok
spocchio@geppetto:~/smw$

Ecco cosa accade:

1. La seconda volta non e' stato chiesto ne user e password!
   
2. La seconda volta non è stato nemmeno richiesto il codice di conferma! (captcha)
   
3. Perche il login non viene riefettuato
   
4. Abbiamo ricevuto due semplici warning, perchè smw non sa se il login è gia stato fatto
   
   

Accounts

un account permette di memorizzare un insieme di variabili e di richiamarle tutte in un colpo.
ad esempio, potremmo creare l'account voda in modo che ogni volta, usi il file 190.it con i relativi username e password.

per far cio editiamo il file confs/accounts
Entrate nella cartella di smw e con il vostro editor preferito, ad esempio gedit confs/accounts
e aggiungete, in questo caso, le seguenti righe:

account.voda.file=190.it
account.voda.user=username
account.voda.pass=password

In questo file è possibile inserire quanti account si vogliono, ovviamente devono chiamarsi in modo diverso.
Dopo aver salvato e chiuso il file potrete richiamare un account impostando la variabile account:

spocchio@geppetto:~/smw$ ./smw account=voda to=340123456 'text=oh ma trallallero!'
 # SmwGun [1.0b]
 # loading vodafone
 # mode =  stato = 
stato = ok
spocchio@geppetto:~/smw$

Rubrica

La rubirca di default usa il file confs/rubrica, per ogni contatto viene impostata una variabile che per convenzione comincia con il punto. ad esempio, un classico file confs/rubrica potrebbe contenere:

.nome1 = 340123456
.pippo = +393489123
.clarabella = 33312123

Per richiamare quei valori in smw si può:

spocchio@geppetto:~/smw$ ./smw file=vodafoneit to=#.pippo 'text=si anche a me tutto ok dai'

bene per ora basta buona notte

Sessioni e keepalive

smuw termina dopo l'invio di un sms, però ne conserva i cookie in un file (solitamente .nomefile_username.cookie) e lancia uno script chiamato ./tools/timer che ogni 2 minuti, fa un refresh della connessione in modo ce il login non scada.

se si vuole cambiare il file della sessione si deve lanciare smw immettendo il nome del file sul parametro session, nel seguente modo:
./smw ...... session=un_altro_file
Di default il keepalive viene attivato automaticamente, perchè su smwgun.conf è presentela variabile ka = auto.
nel caso si voglia terminare il processo del keepalive ( che è indipendente da smw ) si puo eseguire smw con ka = ko, e nel caso sen e voglia forzare l'esecuzione impostando ka = ok

Tip'n'tricks

Impostare un proxy

per impostare un proxy è necessario impostare la variabile d'ambiente http_proxy,
le seguenti righe vanno scritte su ~/.bashrc o /etc/environment rispettivamente se sono da impostare per il singolo utente o per tutto il sistema.

export http_proxy=http://utente:password@indirizzoproxy:porta/

ad esempio:

export http_proxy=http://spocchio:123456@192.168.0.1:8080/

Per le impostazioni sottoriportate e' necessario modificare il file smw/confs/smwgun.conf. per aprirlo scrivete da console:

gedit /home/$USER/smw/confs/smwgun.conf

Impostare il riconoscimento automatico dei codici ottici (captcha)

Nel file smwgun.conf la riga

pickcode.default=readcode

con

pickcode.default=ocr

(reimpostatela al valore originale per ritornare al metodo classico)

impostare il valore di ocr.nretry con il numero di tentativi massimi da operare su un codice prima di passare all'inserimento manuale (infatti certi codici come quello vodafone non vengono riconosciuti al primo colpo)

Impostare il server SMTP

Nel file smwgun.conf impostate il valore di sys.smtpserver con il server smtp che più vi aggrada

Impostare un timeout HTTP

La durata massima di una richiesta HTTP prima che scada è impostata su 5 secondi, nel caso abbiate una connessione lenta potete aumentare questo timeout delle richieste HTTP, la variabile da impostare si chiama proprio timeout

Gestione delle sessioni

di norma, le sessioni (i cookie per un determinato sito/utente o account) vengono salvate come file nascosti sulla cartella smw con il seguente formato: .sito_nomeutente.cookie
e, le informazioni sull'ultimo utilizzo di una determinata combinazione sito/utente
.sito_nomeutente

Creare un Plugin

Materiale

Prerequisiti:

Un plugin non è altro che un file di testo contenente tutte le diretive necessarie per smw per l'inoltro di un SMS( pagine web su cui passare ecc), solitamente si divide in 5 punti:
main - Contiene le informazioni generali sul plugin
login - Diretive per l'accesso.
invio - Direttive per l'invio, è ovvio che una volta fatto il login non è necessario ripassare per la fase login nei sucessiv i invii.
logout - Direttive per un possibile logout.
refresh - Una qualsiasi pagina da far aggiornare ogni tot, per non far scadere la sessione e non dover rifare il login.

E' consigliato:
1. Conoscenze delle richieste HTTP (GET,POST,parametri etc..) ()
2. Conoscenze dell HTML
3. Uno sniffer di rete (o Live HTTP Header per mozilla-firefox e' ottimo)
4. Un editor di testo e un po di tempo:)

i plugin contengono una serie di "assegnazioni" di variabili, e,in base al loro nome smw capisce quando e come eseguirle.
la sintassi per settare una variabile in un plugin smwgun e'

sezione.nomevariabile=valore
Nel caso si voglia inserire il valore contenuto in un altra variabile è possibile interpolarlo nel seguente modo:
sezione.nomevariabile=valore #VariabileDaInterpolare altro valore
ad esempio:
main.nomeutente=sei entrato con il nomeutente #user

Ecco le variabili interpolate piu comuni:
user - il nome utente per il login del sito
pass - la relativa password
to - il numero del mittente
text - il destinatario
from - il mittente

per comprendere meglio, vi consiglio di tenere un qualsiasi plugin durante la lettura del manuale.

La testata

La testata contiene le informazioni essenziali sull utilizzo del plguin, ecco le variabili principali

main.name = www.nome del sito del plugin.it

main.desc = descrizione opzionale del plugin
main.comp = compagnie su cui si puo inoltrare l'sms, (es. "vodafone,tim")
main.aut = email dell autore
main.fields = i campi necessari (es. user,pass,to,text)
main.steps = numero passaggi totali, non piu utilizzato.
main.ricodice = intervallo dei passaggi utilizzati in caso ci sia un codice di controllo

main.version = versione
main.lastupdate = data ultimo aggiornamento
main.country = sigla delle nazionalità supportate dal sito
main.login = step utilizzati dal login
main.send = passaggi utilizzati per l'invio vero e prorpio
main.logout = passaggi utilizzati per il logout

hide.pass = implica di nascondere il campo password nella modalità console
maxsize.text = imposta un eventuale limite per un parametro (es, 160 il campo text puo avere max 160 caratteri)
main.needrandom = numero di campi casuali da utilizzare
main.kaurl = un eventuale url su cui are il refresh x mantenere la sessioen attiva

in verità è anche possibile "forzare" alcune variabili, ad esempio, se siamo sicuri che il codice captcha di questo sito sia "illeggibile in manuare automatica" possiamo aggiungere il valore: pickcode.default=readcode, oppure se il sito e' particolarmente lento si puo impostare il valore timeout=5 insomma e' possibile inserire qualsiasi configurazione, addirittura anche text=il testo del messaggio non viene piu preso dall'utente!

Le azioni

Le azioni dette step, sono numerate con un indice univoco, eccone un esempio:
step12.action=get www.boh.it?login=#user
un azione simile genererebbe una richiesta get al server www.boh.it

Ecco la lista delle azioni piu comuni:
get = http://url/?getparam1=val1&getparam2=val2 = su stepx.res viene restituito l'output del server>
post = http://url/?param1=val1&getparam2=val2 su stepx.res viene restituito l'output del server, per inserire i valori passati col metodo post bisogna aggiungere:

stepx.param.nomeparametro1=valore1
stepx.param.nomeparametro2=valore2
stepx.param.nomeparametro3=valore3
stepx.mail = da inserire anche:
stepx.mailfrom=mittente@aads
stepx.rcptto=dest@as
stepx.data=testo\ndel\nmessaggio.. = su stepx.res viene restituito l'output del server

systemv = comando da eseguire = su stepx.res viene restituito il valore tornato dal programma
system = comando da eseguire = su stepx.res viene restituito l'output del programma
print = ciao mondo = Output a schermo di una stringa ..inutile :)

sleep = numero secondi = il programma si ferma per n secondi
ask = parola variabiledest = fa output di parola su schermo e legge in input e salva su variabile dest
if = text testo stepx.res 4 5 = se la sringa text e contenuta su stepx.res salta allo step 4 se no allo step 5

number nomecampo = da fare con le variabili contenenti numeri di telefono (come to)
lo elabora e ne salva il prefisso su stepx.prefix il resto del numero su stepx.postfix e la nazionalita su stepx.country

pickcode variabile quest'istruzione prende il valore che c'è dentro a variabile (dev'essere un immagine) e la considera un codice ottico (captcha),
in base alle configurazioni verrà poi letta con gocr oppure visualizzata all'utente. ecco un tipico esempio d'utilizzo di pickcode:

step6.action=get http://www.xxx.it/xxx/fsms/generateimg.do viene prelevata la pagina generate.do, il risultato viene salvato su step6.res

step9.action=pickcode step6.res                            viene richiesto a smw di elaborare il captcha contenuto su step6.res, il risultato sarà salvato su step9.res

step11.action=post http://www.xxx.it/xxx/fsms/send.do
step11.param.pageTypeId=9604
step11.param.programId=10384
step11.param.channelId=-18126
step11.param.receiverNumber=#to
step11.param.message=#text
step11.param.verifyCode=#step9.res                        viene passato il valore del captcha al server web
step11.param.x=21
step11.param.y=16

Queste sono altre variabili che si possono aggiungere:
stepx.save=nomefile = salva il risultato dell operazione ovvero stepx.res su nomefile
stepx.thestring=ok,stringa = stringa DEVE essere presente su stepx.res se cosi non e guarda stepx.error
stepx.thestring=ko,stringa = stringa NON DEVE essere presente su stepx.res se cosi non e guarda stepx.error
stepx.error=tipoerrore,descrizione = errore puo essere:
login se gli user e/o la password sono invalidi
to se e sbagliato ildestinatario,
noservice se il sito ha problemi,
from se il mittente e' errato
text text se non e valido
nocredit se si sono esauriti i crediti nel sito
other se non lo si conosce o puo essere di piu tipi

stepx.middle=std|stl prende stepx.res e prende la stringa in mezzo a std ed stl,salva il risultato su stepx.resmiddle
ad es stepx.middle=< input type="hidden name="id" value="|"> se ad esempio volessimo il valore di ID in un html tipo:
..
testo html lalal
< input type="hidden name="id" value="valore">
lalal al al
..

Le Sostituzioni

Se vogliamo inviare ocme parametro una variabile o compunque utulizzarla..e' possibile interpolarma mettendoci il cancelletto alla sinistra.
una variabile viene interpoalta solo se esiste.

ad es step5.action=post http://dsafsfd/?id=3 user=#user&pass=#pass