!"#$ & '() *+,-).! "/01.

,2 #)3
$)2456) 7,8)2 9:+;<
WrlLLen by: 8obby Allen (ballen[zpanelcp.com)
8evlslon: 1.0.2
LasL updaLed: 23Lh lebruary 2012
!"#$%#$&
WhaL ls xMWS ....................................................................................................................................... 1
1he requesL Lags explalned .................................................................................................................... 1
aplkey ................................................................................................................................................ 1
requesL ............................................................................................................................................... 2
auLhuser ............................................................................................................................................. 2
auLhpass ............................................................................................................................................ 2
conLenL .............................................................................................................................................. 2
1he response Lags .................................................................................................................................. 2
response ............................................................................................................................................ 2
conLenL .............................................................................................................................................. 3
An example requesL ............................................................................................................................... 3
Lxample of an lmage upload uslng username and password auLhenLlcaLlon. ...................................... 4
uslng xMWS .......................................................................................................................................... 4

()*$ +& ,-(.
xMWS ls deslgned by 8obby Allen and ls an xML based web servlce framework LhaL enables Zanelx
module developers Lo add Lhelr own web servlce meLhods qulckly and securely wlLhln Lhelr Zanel
modules. 1he xMWS xML Schema ls deslgned Lo be kepL slmple and easy Lo undersLand by all.
/)% 0%12%&$ $*3& %456*+#%7
*5+8%9
1hls Lag should conLaln Lhe Zanel server's Al key as found ln Lhe Zanel daLabase, Lhls ls a random
sLrlng LhaL provldes a 'hand-shake' Lype of auLhorlsaLlon before Lhe Zanel server wlll process any
requesLs.
0%12%&$
1hls Lag conLalns Lhe name of Lhe meLhod LhaL exlsLs ln Lhe modules Al class whlch exlsLs ln Lhe
modules !"#$%&$'($)*+!$,$-.,/0/ flle.
*2$)2&%0
lf Lhe module developer seL ln Lhe webservlce.exL.php LhaL Lhe requesL should be an auLhenLlcaLed
requesL (have added $this->RequireUserAuth(); Lo Lhe class) Lhen Lhls ls where Lhe username of
Lhe Zanel username should be provlded.
!"#$ #$ &' ()*#('&+ *&, &'- ('+. '//- *( 0/ $/'* 12 *"/ 3/0 $/45#6/ 7/*"(- 4/89#4/$ &9*"/'*#6&*#(':
*2$)5*&&
1hls ls where Lhe Zanel password should be supplled for Lhe requesL lf user auLhenLlcaLlon ls
requlred. 1hls ls senL ln plaln LexL so SSL ls recommended.
1hls ls an opLlonal Lag and only need Lo be senL ll Lhe web servlce meLhod requlres auLhenLlcaLlon!
:"#$%#$
1hls provldes a 'free LexL' Lag for daLa Lo be senL back and forLh from Lhe Zx module Lhe daLa senL
ln Lhls fleld ls consldered '8AW' daLa so would need Lo be handled by Lhe module developer buL a
slmple LexL sLrlng ls a good example of a slmple way of uslng Lhls fleld Lo dlsplay a user frlendly
response or a comma separaLed llsL could Lhen be Lurned lnLo an array by Lhe module developer.
1hls fleld ls noL llmlLed ln lengLh so could even be used Lo send blnary daLa over Lhe lnLerneL Loo
such as uploadlng a flle (slmply flll Lhe fleld wlLh Lhe blnary daLa lnsLead).
/)% 0%&5"#&% $*3&
0%&5"#&%
AfLer a requesL ls processed Lhe xMWS class wlll reLurn a response, Lhls wlll conLaln one of Lhe
followlng response codes:-
1101 8equesL successful.
1102 8equesL noL found (class does noL exlsL).
1103 Server Al key valldaLlon falled.
1104 user auLhenLlcaLlon requlred and noL speclfled.
1103 username and password valldaLlon falled.
1106 8equesL noL valld (requlred Lags noL supplled) no posL daLa eLc.
1107 Modular web servlce noL found (eg. no flle ln Lhe module named
'webservlce.exL.php')

1he user also has Lhe ablllLy Lo use a cusLom response code on a successful requesL lf Lhe module
developer wlshes Lhls slmply adds more flexlblllLy. 1hls means LhaL Lhe module developer can
overrlde Lhe defaulL 1101 response lf he or she expllclLly seLs Lhls ln Lhe correspondlng requesL class.
:"#$%#$
ln Lhe response message Lhe ;6('*/'*< Lag can be used Lo send back a user frlendly message sLrlng
or conLaln an array of daLa Lo be used aL Lhe cllenL end or any klnd of daLa for LhaL maLLer, Lhls ls a
declslon LhaL ls Lo be made by Lhe module developer.
;# %4*<56% 0%12%&$
lor a slmple example of a requesL, here ls how a Lyplcal xMWS xML requesL would look llke:-
<?xml version="1.0" encoding="UTF-8"?>
<xmws>
<apikey>a4ffrdj374ks93jdwwe</apikey>
<request>AllZPanelSystemOptions</request>
<authuser></authuser>
<authpass></authpass>
<content></content>
</xmws>
1he requesL would be senL Lo Lhe server uslng a CS1 requesL uslng Lhe followlng u8L formaL:-
0../1%%!"2.)"3,4"5)($)*$),!"6%7/+%(4(.$68"/.+"2(%
1he above u8L ls Lelllng Lhe Zanel framework Lo look ln Lhe module called 'sysLem_opLlons' folder
sLrucLure for lLs web servlce exLenslon class (Lhls ls ln Lhe flle named '!"#$%&$'($)*+!$,$-.,/0/' ln
Lhe module folder '(4(.$68"/.+"2(', Lhe class meLhod Lo execuLe ls glven ln Lhe ;4/89/$*< Lag wlLhln
Lhe xML CS1 daLa.
1he above example requesL ls slmply requesLlng Lo reLurn every sysLem opLlon ln Lhe =>$/**#',$
Lable ln Lhe daLabase.
As you can see from Lhe above requesL xML Lhe <auLhuser>, <auLhpass> and <conLenL> are lefL
blank as Lhese are noL requlred for Lhls slmple requesL.
now, as long as Lhe ;&)#?/.< Lag maLches Lhe one on Lhe Zanel server Lhen Lhe xMWS class wlll
now go and run Lhe meLhod named :33;<72$3=4(.$6>/.+"2( whlch can ln Lurn perform operaLlons
ln Lhe module's 6('*4(++/4@/=*@)") flle and can call all Lhe core framework uLlllLy classes and
meLhods. 1he nexL Lhlng LhaL wlll happen ls Lhe exLernal appllcaLlon or webslLe wlll Lhen requesL Lo
read Lhe response, Lhe response wlll look as follows:-
<?xml version="1.0" encoding="UTF-8"?>
<xmws>
<response>1101</response>
<content>
[TO BE UPDATED WITH NEW XML VERSION]
</ content>
</xmws>
1he ouLpuL of Lhe daLa lnLo Lhe ;6('*/'*< Lag ls down Lo Lhe developer so lL ls noL llmlLed Lo whaL
you can and can'L puL lnLo Lhls fleld lL ls deslgned Lo allow module developers Lo do whaLever Lhey
need Lo ln Lhls secLlon.
=4*<56% "> *# +<*3% 256"*7 2&+#3 2&%0#*<% *#7 5*&&?"07
*2$)%#$+:*$+"#@
An example of uploadlng an lmage Lo a module could look llke Lhls:
<?xml version="1.0" encoding="UTF-8"?>
<xmws>
<apikey>a4ffrdj374ks93jdwwe</apikey>
<request>UploadPhotoToWebGallery</request>
<authuser>ballen</authuser>
<authpass>my_password_here</authpass>
<content>
<mymod_gallery>specific_gallery_name</mymod_gallery>
<mymod_ imagedata>{RAW_DATA_HERE}</mymod_imagedata>
</content>
</xmws>
1he above example shows how an example web gallery module could requesL LhaL a user needs Lo
auLhenLlcaLe Lo upload an lmage.
1hls also demonsLraLes how Lhe module developer could use xML Lags wlLhln Lhe ;6('*/'*<
(recommended) Lags Lo speclfy a gallery Lo upload Lhe lmage Lo and Lhen anoLher Lag Lo send Lhe
raw blnary daLa whlch wlll Lhen be converLed aL Lhe Zanel server.
A&+#3 ,-(.
1hls documenL explalns Lhe Lechnlcal aspecLs of Lhe requesL and response daLa as well as how Lhls
works wlLh Lhe Zanel framework.
We sLrongly encourage LhaL Lhlrd-parLy developers LhaL wanL Lo lnLegraLe Lhelr sofLware wlLh Zanel
uslng xMWS LhaL Lhey use one of Lhe offlclal Al cllenLs.
uslng an Al cllenL means LhaL you do noL need Lo manually lnLerrogaLe Lhe xML response daLa nor
do you have Lo manually bulld your requesL message, Lhe offlclal Zanel xMWS P Al CllenL ls a
greaL sLarLlng place Lo learn how Lo use a slmple Al cllenL Lo requesL and handle response daLa
slmply.
?ou can download and flnd example code from Lhe ClLhub pro[ecL found here:-
hLLps://glLhub.com/bobsLa63/xMWS-P-Al-CllenL