--- a/doc/provider.rst Wed Apr 25 00:03:09 2012 +0200
+++ b/doc/provider.rst Wed Apr 25 00:04:47 2012 +0200
@@ -1,4 +1,143 @@
Creating a new Providerbackend for Iro
======================================
-See also :class:`iro.offer.provider.Provider`.
+See also class documentation :class:`iro.offer.provider.Provider`.
+
+A very simple provider
+----------------------
+
+For testing purpose it is nice to create a small provider.
+
+.. code-block:: python
+ :linenos:
+
+ from iro.offer import providers, Provider
+
+ class TestProvider(Provider):
+ def __init__(self,name):
+ Provider.__init__(self, name, {"sms" : ["a",]})
+
+ providers["myveryspecialProvider"] = TestProvider
+
+- *line 3* -- a Provider that supports message type **sms**, and has one route named **a**.
+- *line 5* -- register the provider type **TestProvider** in the global **providers** dict. Following section in configuraton file will create a new TestProvider object, with ``name="blablub"``::
+
+ [blablub]
+ #see line 5
+ typ = myveryspecialProvider
+
+
+Normally a new Provider wants to have extra options for configuration file:
+
+.. code-block:: python
+ :linenos:
+
+ from iro.offer import providers, Provider
+ from iro.config import Option
+
+ def validater(value, field):
+ return value
+
+ class TestProvider(Provider):
+ def __init__(self,name):
+ options =[("key", Option(validater,long="My Option explanation", must=True)),]
+ Provider.__init__(self, name, {"sms" : ["a",]}, options)
+
+ providers["myveryspecialProvider"] = TestProvider
+
+
+in *line 9* we create a item list ( ``[(name,Option),...]`` -- more information about :class:`iro.config.Option`). **validater** have to be a function that returns value, if the value is valid. With this following section in configuration file is possible::
+
+ [balblub]
+ typ = myveryspecialProvider
+ #My Option explanation
+ key = mykey
+
+Ok, now we know to get settings into the provider. But we have to do anything, when user want to send anything. So we have to create a send function.
+
+Creating sipgate provider
+-------------------------
+
+Sipgate supports sending sms and faxes via XML-RPC. so it is easy to create a new providerbackend for iro via sipgate. First we get the XML-RPC Api documention for sipgate (http://www.sipgate.de/beta/public/static/downloads/basic/api/sipgate_api_documentation.pdf). Sipgate uses HTTP Basic Authentification, that's we he create to options for our sipgate provider:
+
+.. code-block:: python
+ :linenos:
+
+ from iro.offer import providers, Provider
+ from iro.config import Option
+
+ class Sipgate(Provider):
+ def __init__(self,name):
+ options =[("username", Option(lambda x,y: x,long="Loginname for sipgate", must=True)),
+ ("password", Option(lambda x,y: x,long="Password for sipgate", must=True)),]
+ Provider.__init__(self, name, {"sms" : [None], "fax":[None]}, options)
+
+ providers["sipgate"] = Sipgate
+
+- *line 6/7* -- we don't have any ideas what is allowed as username/password, so we create a validator that accepts everything.
+- *line 8* -- sipgate supports fax and sms, but now diffrent routes, that's we use ``None``.
+
+Now we have to possible options to implement the send function. either we implement a blocking interface or use the recommended solution: twisted non blocking solution. We show here the recommended version.
+
+The Twisted Way (recommended solution)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First we start to implement the ``fax`` and ``sms`` methods:
+
+.. code-block:: python
+ :linenos:
+
+ def proxy(self):
+ return Proxy("https://%s:%s@samurai.sipgate.net/RPC2"%(self.username, self.password))
+
+ def sms(self, recipient, sms):
+ args={
+ "TOS" : "text",
+ "Content" : sms.getContent(),
+ "RemoteUri" : "sip:%s%s@sipgate.net"%(recipient.land, recipient.number),
+ }
+ return self.proxy().callRemote("samurai.SessionInitiate",args)
+
+ def fax(self, recipient, fax):
+ args={
+ "TOS" : "fax",
+ "Content" : xmlrpclib.Binary(fax.getAttachment(0)),
+ "RemoteUri" : "sip:%s%s@sipgate.net"%(recipient.land, recipient.number),
+ }
+ return self.proxy().callRemote("samurai.SessionInitiate",args)
+
+The code is straight forward with the API documentation from sipgate. Now we have to implement the heat of the provider the ``send`` method:
+
+.. code-block:: python
+ :linenos:
+
+ def _status(self,value,typ):
+ if typ not in self.typs.keys():
+ raise NoTyp(typ)
+ return Status(self, None, Decimal("1.00"), 1, value["SessionID"])
+
+ def send(self, typ, recipient, msg):
+ if typ not in self.typs.keys():
+ raise NoTyp(typ)
+ d = getattr(self,typ)(recipient, msg)
+ d.addCallback(self._status, typ)
+ return d
+
+ def getSendFunc(self, typ, route):
+ """returns :meth:`send` method, if typ and route is valid."""
+
+ Provider.getSendFunc(self, typ, route)
+ return partial(self.send, typ)
+
+Because sipgate doesn't support different routes, we implement a send function without route argument.
+That's why we have to rewrite the ``getSendFunc`` method. It now returns a partial function with only a binded ``typ``.
+
+The ``send`` method first test the for a valid typ (*line 7/8*), than it execute the ``sms`` or ``fax`` method.
+For a valid provider we have to return a :class:`~iro.model.status.Status` object.
+There for we add a callback that returns a :class:`~iro.model.status.Status` object (see ``_status`` method).
+
+Unfortunatelly sipgate doesn't support methods to get the price for one action.
+So we have to set set a fixed price here ``Decimal('1.00')``.
+In the wild we implement new configuration parameters for priceing.
+
+Now the provider is ready to use. For complete source of this tutorial see :class:`iro.offer.sipgate`.