diff -r 170dfb782231 -r 1653470ccaff doc/provider.rst --- 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`.