RE: [RFC] new module : SOAP.

It appears to me like a great work!! Oded rules ;-)

I am sorry but currently none of our providers have XML interfaces, so I
can't help in testing and debugging.

Anyway, keep the good work.

Angel Fradejas
Mediafusión España, S.A.
[email protected]
www.mediafusion.es
Tel. +34 91 252 32 00
Fax +34 91 572 27 08




-----Mensaje original-----
De: [email protected] [mailto:[email protected]]En
nombre de Oded Arbel
Enviado el: jueves 8 de agosto de 2002 09:56
Para: Kannel-devel (E-mail)
Asunto: [RFC] new module : SOAP.


Hi list.

Created a new SMSC module for Kannel for use with connection
to some proprietary gateway systems some of our providers use
(we currently use this module for 3 different providers). I
call this SOAP, after the Microsoft "standard" as it seems to
me to be the same thing though none of our providers call it
like this in their specs. In actuality, simple XML over HTTP,
storing a provider specific XML format in a POST variable.

I tried to make this module as general as possible, but as
each provider uses different semantics and different XML
formats and even different data formats inside the XML for
the same message elements, it's harder then it seems at
first. The approach I've taken so far is to use some
configuration variables (added to cfg.def - patch attached),
file templates for creating the text buffers Kannel sends,
"spec" files for parsing the XML buffers Kannel receives, and
some hard coded "keywords" inside the template parser to
generate some weird data representations that some of our
providers like to use.

The module's HTTP server (for calls from the SOAP server to
Kannel for MO and DLR) exposes two "calls" :
http://<ip>:<port>/mo for MO delivery and
http://<ip>:<port>/dlr for DLR delivery. the server expects a
singe CGI post parameter whose name doesn't matter (it is
discarded) and then reads and attempts to parse the XML using
the relevant "spec" file. the syntax to the spec file is very
simple: it's a tab separated list where each record (line)
contains 2 or 3 elements -
1) identification of element we wish to extract. sorry to
point you to the code, but these keywords must conform to
hard coded values found in the code itself. I tried to
conform to the SMS message structure defined in Kannel's
msg-decl where possible
2) path in the XML hierarchy to the element
3) if the required data is not the content of the XML element
but one of its attributes, then this will contain the
required attribute's name

The XML template parser understand various "tokens" that can
be embeded in the templates to provide the actuall run-time
content. you can either use the format %token_name or %{token
name} . if you are not using the curly braced version then
the token name must start with a letter and continue only
with letters. numers and under-scores. if the token is
encapsulated is culry braces it can contain anything (except
and ending curly brace), but it of course wouldn't make much
sense unless it conforms to the same format as the former
version as they both match against the same keywords. any
member name of the SMS message structure can be used, and
also some special "data formats" are recognized - look in the
soap_parse_token() function's code.

Sorry for no documentation yet, I will get down to it (of
course - I will be much more motivated to provide
documentation if people will show interest in the module ;-),
in the mean time you can always read the source.

I had to add several new functions to the Kannel
infrastructures (patches attached), and here they are described :
* date.[ch]:
int date_parse_iso (struct universaltime *ut, Octstr *os) -
attempts to parse an ISO-8601 date representation,
substituting missing fields with the base values (0 or 1),
returning 0 on success and -1 on failure. the time is read
from the Octstr os and returned in the universal time structure ut.
Octstr* date_create_iso(time_t unixtime) - creates an
ISO-8601 formatted date string from a unix epoch time stamp.
* charset.[ch]:
int charset_convert(Octstr* string, char* charset_from, char*
charset_to) - converts a string buffer between arbitary
character sets using the standard glibc library iconv
(Hopefully it is present in other OSs). I had to add this
utility as the libxml encoding conversions do not cover
nearly as many character sets as I need to support (strangely
enough - some providers use XML and not utf-8).
* configure.in config.h.in
checking for iconv to support charset_convert() in charset.[ch]
* msg-decl.h, msg.[ch]
Changed the msg id used in sms and ack types to 64 bit
integer. I know this will probably be very controversial and
is the number one compatibility breaker here, but _all_ of
the providers we're dealing with here use 64bit integers for
their message IDs and I have to correlate to that, otherwise
I can lose synchronization between messages and acks. it
probably has something to do with java and it's 64 bit native
integers - apparently all of our providers use Java as their
programming language for the XML interfaces.
The most important lesson - after applying this patch your
store files will no longer work and cause bearerbox to crash
- so make sure to delete the store files before running a
modified bearerbox. this change would probably turn-off most
of the people that would have otherwise tested this module,
but I do hope that you will take a look at it anyway. I do
think that changing the message IDs to 64 bit is something we
should have done much earlier.
* utils.[ch]
unsigned long long decode_network_int64(unsigned char *data)
, void encode_network_int64(unsigned char *data, unsigned
long long value) - support for 64 bit integers
unsigned long long gw_generate_id() - can be used to generate
pseudo-unique 64 bit integers for id purposes

notes:
- HTTPS calls are handled using the normal Kannel HTTP
infrastructure, so HTTPS calls that require client
certificates and the HTTPS server using the new
receive-port-ssl config parameter use the core configuration
definitions ssl-client-certkey-file, ssl-server-cert-file and
ssl-server-key-file.
- in the XML examples you'll notice a "billing" paremeter, as
this conforms with the billing patch I submitted to the list
a while ago. if the "tariff" patch is accepted then the fix
would be simply to change the text in the file from "billing"
to "tariff"


Cheers

--
Oded Arbel
m-Wise mobile solutions
[email protected]

+972-9-9581711 (116)
+972-67-340014

::..
Time is an illusion. Lunchtime doubly so.
  --Ford Prefect