userguide.xml

The Kannel Open Source WAP and SMS gateway works as both an SMS gateway, for implementing keyword b

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"
     [
<!ENTITY figtype "#FIGTYPE#">
<!ENTITY timestamp "#DATE#">
<!ENTITY version "#VERSION#">
<!ENTITY % draft "#DRAFTS#">
]>

<!-- Embbeb your block with these to set it to "draft"
<![%draft;[ <your block> ]]>
-->

<book>

<bookinfo>
	<title>Kannel &version; User's Guide</title>
	<subtitle>Open Source WAP and SMS gateway</subtitle>

<authorgroup>
	<author>
		<firstname>Andreas</firstname>
		<surname>Fink</surname>
		<affiliation>
			<jobtitle>Chairman &amp; CTO</jobtitle>
			<orgname>Global Networks Inc.</orgname>
			<address> <email>[e-mail]</email>
				<otheraddr>http://www.smsrelay.com</otheraddr>
				<otheraddr>http://www.gni.ch</otheraddr>
			</address>
		</affiliation>
	</author>
	<author>
		<firstname>Bruno</firstname>
		<surname>Rodrigues</surname>
		<affiliation>
			<address> 
				<email>[e-mail]</email>
				<otheraddr>http://litux.org/bruno</otheraddr>
			</address>
		</affiliation>
	</author>
	<author>
		<firstname>Stipe</firstname>
		<surname>Tolj</surname>
		<affiliation>
			<jobtitle>Chief Technology Scientist</jobtitle>
			<orgname>Wapme Systems AG</orgname>
			<address> 
				<email>[e-mail]</email>
				<otheraddr>http://www.wapme.de</otheraddr>
			</address>
		</affiliation>
	</author>
	<author>
		<firstname>Aarno</firstname>
		<surname>Syv鋘en</surname>
		<affiliation>
			<jobtitle>Chief MMS Developer</jobtitle>
			<orgname>Global Networks Inc.</orgname>
			<address> 
				<email>[e-mail]</email>
				<otheraddr>http://www.gni.ch</otheraddr>
			</address>
		</affiliation>
	</author>
	<author>
		<firstname>Alexander</firstname>
		<surname>Malysh</surname>
		<affiliation>
			<!-- <jobtitle>Chief Kannel Developer</jobtitle>
			<orgname>Centrium GmbH</orgname> -->
			<address> 
				<email>amalysh at kannel.org</email>
				<!-- <otheraddr>http://www.centrium.de</otheraddr> -->
			</address>
		</affiliation>
	</author>
	<author>
		<firstname>Lars</firstname>
		<surname>Wirzenius</surname>
		<affiliation>
			<jobtitle>Gateway architect</jobtitle>
			<orgname>former Wapit Ltd</orgname>
			<!--<address> <email>[e-mail]</email>
			<otheraddr>http://www.wapit.com</otheraddr>
			</address>-->
		</affiliation>
	</author>
	<author>
		<firstname>Kalle</firstname>
		<surname>Marjola</surname>
		<affiliation>
			<jobtitle>Manager</jobtitle>
			<orgname>former Wapit Ltd</orgname>
			<!--<address> <email>[e-mail]</email>
			<otheraddr>http://www.wapit.com</otheraddr>
			</address>-->
		</affiliation>
	</author>

</authorgroup>

	<abstract>
		<title>Abstract</title> 
		<para>
		This document describes how
		to install and use Kannel, the Open Source WAP and SMS Gateway
		originally developed by Wapit Ltd (now out of business) and now
		being developed further by the open source community, namely the 
		Kannel Group.
		</para>
	</abstract>

  <revhistory>
    <revision>
      <revnumber>&version;</revnumber>
      <date>&timestamp;</date>
    </revision>
  </revhistory>

</bookinfo>


<chapter>
<title>Introduction</title>

	<highlights>
	<para>This chapter introduces WAP and SMS in general terms, and explains the
	role of the gateway in WAP and SMS, outlining their duties and features. It
	also explains why the Kannel project was started in the first place,
	and why it is open source.</para>
	</highlights>
	
	<para>With hundreds of millions of mobile phones in use all over the
	world, the market for services targeted at mobile users
	is mind-bogglingly immense.  Even simple services find plenty of users,
	as long as they're useful or fun. Being able to get news, send e-mail
	or just be entertained wherever you are is extremely attractive to
	many.</para>

	<para>The hottest technology for implementing mobile services is WAP,
	short for Wireless Application Protocol. It lets the phone act
	as a simple web browser, but optimizes the markup language,
	scripting language, and the transmission protocols for wireless
	use. The optimized protocols are translated to plain old HTTP by
	a <emphasis>WAP gateway</emphasis>.</para>

	<para>Kannel is an open source WAP gateway. It attempts to
	provide this essential part of the WAP infrastructure freely
	to everyone so that the market potential for WAP services,
	both from wireless operators and specialized service providers,
	will be realized as efficiently as possible.</para>

	<para>Kannel also works as an SMS gateway for GSM networks. Almost
	all GSM phones can send and receive SMS messages, so this is
	a way to serve many more clients than just those using a new
	WAP phone.</para>

        <para>In addition, Kannel operates as <emphasis>Push Proxy Gateway 
        </emphasis>, or <emphasis>PPG</emphasis>, making possible for content 
        servers to send data to the phones. This is a new type of WAP service,
        and have many interesting applications. Usually servers know whether
        some data is new, not the users. </para>

	<para>Kannel's quality has been recognized on March 7, 2001 when it
	was <ulink url="http://www.kannel.org/oldnews.shtml#wapcert">certified</ulink> 
	by <ulink url="http://www.wapforum.org">Wap Forum</ulink>
	as the first WAP 1.1 gateway in the world.</para>

	<para>Greater quality recognition are the quantity of companies 
	using Kannel to successful connect to a variety of SMSC protocols 
	in lots of countries.</para>

	<para><ulink url="http://www.opensource.org">Open Source</ulink>
	is a way to formalize the principle of openness by placing the
	source code of a product under a Open Source compliant software
	license. The BSD license was chosen over other Open Source
	licenses by the merit of placing the least amount of limitations
	on what a third party is able to do with the source code. In
	practice this means that Kannel is going to be a fully-featured
	WAP implementation and compatible with the maximum number of
	bearers with special emphasis on SMSC compatibility.
	The Kannel project was founded by Wapit Ltd in June, 1999.</para>
	
	
<sect1>
<title>Overview of WAP</title>

	<para>WAP, short for Wireless Application Protocol, is a
	collection of various languages and tools and an infrastructure for
	implementing services for mobile phones. Traditionally such
	services have worked via normal phone calls or short textual
	messages (e.g., SMS messages in GSM networks). Neither are very
	efficient to use, nor very user friendly.  WAP makes it possible
	to implement services similar to the World Wide Web.</para>
	
	<para>Unlike marketers claim, WAP does not bring the existing
	content of the Internet directly to the phone. There are too many
	technical and other problems for this to ever work properly. The
	main problem is that Internet content is mainly in the form of
	HTML pages, and they are written in such way that they require
	fast connections, fast processors, large memories, big screens,
	audio output and often also fairly efficient input mechanisms.
	That's OK, since they hopefully work better for traditional
	computers and networks that way. However, portable phones have
	very slow processors, very little memory, abysmal and intermittent
	bandwidth, and extremely awkward input mechanisms. Most existing
	HTML pages do not work on mobiles phones, and never will.</para>
	
	<para>WAP defines a completely new markup language, the Wireless
	Markup Language (WML), which is simpler and much more strictly
	defined than HTML.  It also defines a scripting language,
	WMLScript, which all browsers are required to support. To make
	things even simpler for the phones, it even defines its own
	bitmap format (Wireless Bitmap, or WBMP).</para>
	
	<para>HTTP is also too inefficient for wireless use. However, by using
	a semantically similar binary and compressed format it
	is possible to reduce the protocol overhead to a few bytes per
	request, instead of the usual hundreds of bytes. Thus, WAP defines a
	new protocol stack to be used. However, to make things simpler
	also for the people actually implementing the services, WAP
	introduces a gateway between the phones and the servers providing
	content to the phones.</para>

        <figure>
        <title>Logical position of WAP gateway (and PPG)between a phone and a 
        content server.</title>
        <graphic fileref="wap-gateway&figtype;"></graphic>
        </figure>

	<para>The WAP gateway talks to the phone using the WAP protocol
	stack, and translates the requests it receives to normal
	HTTP. Thus content providers can use any HTTP servers and
	utilize existing know-how about HTTP service implementation
	and administration.</para>
	
	<para>In addition to protocol translations, the gateway
	also compresses the WML pages into a more compact form, to
	save on-the-air bandwidth and to further reduce the phone's
	processing requirements. It also compiles WMLScript programs
	into a byte-code format. Latest WAP specifications defines some 
	additional conversions that Kannel is starting to implement, like
	multipart/form-data, multipart/mixed or MMS content conversion.</para>
	
	<para>Kannel is not just a WAP gateway. It also works as an
	SMS gateway.  Although WAP is the hot and technically superior
	technology, SMS phones exist in huge numbers and SMS services are
	thus quite useful. Therefore, Kannel functions simultaneously
	as both a WAP and an SMS gateway.</para>

</sect1>

<sect1>
<title>Overview of WAP Push</title>
       <para>Previous chapter explained pull mode of operation: the phone
       initiates the transaction. There is, however, situations when the
       server (called in this context a push initiator) should be the 
       initiator, for instance, when it must send a mail notification or a
       stock quote. For this purpose WAP Forum defined WAP Push.</para>

       <para>Push is an application level service, sitting on the top of
       existing WAP stack. It defines two protocols, OTA and PAP. OTA is
       a ligthweigth protocol speaking with WAP stack (to be more specific,
       with WSP), PAP speaks with the push initiator. It defines three kind
       of XML documents, one for the push data itself and another for 
       protocol purposes (these are called pap document or push control 
       documents). </para>

       <para>The server does not simply send push content to the phone, the
       user would surely not accept, for instance, interrupting of a voice 
       call. Instead it sends a specific XML document, either Service 
       Indication or Service Loading. These inform the user about the content 
       become available, and it is displayed only when it is not interrupting 
       anything. It contains an URL specifying the service and a text for user 
       describing the content. Then the user can decide does he accept push or not.
       </para>

       <para>The push content is send ed to the phones over SMS, but the 
       content is fetched by the phone over IP bearer, for instance CSD
       or GPRS. Because Push Proxy Gateway tokenises SI and SL documents, it 
       may fit one SMS message (if not, it is segmented for transfer). </para>

       <para>Using two bearers seems to be an unnecessary complication. But
       quite simply, phones currently operate this way. Push over GPRS can 
       only simplify matters.</para>
</sect1>
	
<sect1>
<title>Overview of SMS</title>

      <para>SMS, short messaging service, is a way to send short (160
      character) messages from one GSM phone to another. It can also
      be used to send regular text as well as advanced content like 
      operator logos, ringing tones, business cards
      and phone configurations.</para>

      <para><emphasis>SMS services</emphasis> are content services
      initiated by SMS message to certain (usually short) phone
      number, which then answers with requested content, if available.</para>

      <para>When SMS services are used, the client (mobile terminal) 
      sends an SMS
      message to certain number, usually a very short specialized
      number, which points to specific SMS center responsible
      for that number (plus possibly many others). This SMS center
      then sends the message onward to specified receiver in intra- or
      Internet, using an SMS center specific protocol. For example, a
      Nokia SMS center uses CIMD protocol.</para>

      <para>As practically every different kind of SMS center uses different
      protocol, an <emphasis>SMS gateway</emphasis> is used to handle
      connections with SMS centers and to relay them onward in an
      unified form. Kannel's biggest feature is to abstract each SMSC protocol
      to a well-known HTTP protocol, simplifying services deployment.</para>

        <figure>
        <title>Logical position of SMS gateway between a phone and a content server.</title>
        <graphic fileref="sms-gateway&figtype;"></graphic>
        </figure>

      <para>An SMS gateway can also be used to relay SMS messages from
      one GSM network to another, if the networks do not roam messages
      normally.</para>

      <para>Kannel works as an SMS gateway, talking with many
      different kind of SMS centers, and relaying the messages onward
      to content providers, as HTTP queries. Content providers then
      answer to this HTTP query and the answer is sent back to mobile
      terminal, with appropriate SMS center connection using SMS center
      specific protocol.</para>

      <para>In addition to serving mobile originated (MO) SMS messages
      Kannel also works as an SMS push gateway - content providers can
      request Kannel to send SMS messages to terminals. Kannel then
      determines the correct SMS center to relay the SMS message and
      sends the SMS message to that SMS center, again using SMS center
      specific protocol. This way the content provider does not need
      to know any SMS center specific protocol, just unified Kannel
      SMS sending interface.</para>

</sect1>

	
<sect1>
<title>Features</title>

	<sect2>
	<title>WAP</title>
		<para>
			<itemizedlist>