4 See also :class:`iro.offer.provider.Provider`.

     4 See also class documentation :class:`iro.offer.provider.Provider`.

     5 

     6 A very simple provider 

     7 ----------------------

     8 

     9 For testing purpose it is nice to create a small provider.

    10 

    11 .. code-block:: python

    12     :linenos:

    13     

    14     from iro.offer import providers, Provider

    15 

    16     class TestProvider(Provider):

    17         def __init__(self,name):

    18             Provider.__init__(self, name, {"sms" : ["a",]})

    19     

    20     providers["myveryspecialProvider"] = TestProvider

    21     

    22 - *line 3* --  a Provider that supports message type **sms**, and has one route named **a**. 

    23 - *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"``::

    24 

    25    [blablub]

    26    #see line 5

    27    typ = myveryspecialProvider 

    28 

    29 

    30 Normally a new Provider wants to have extra options for configuration file:

    31 

    32 .. code-block:: python

    33     :linenos:

    34     

    35     from iro.offer import providers, Provider

    36     from iro.config import Option

    37 

    38     def validater(value, field):

    39         return value

    40 

    41     class TestProvider(Provider):

    42         def __init__(self,name):

    43             options =[("key", Option(validater,long="My Option explanation", must=True)),]

    44             Provider.__init__(self, name, {"sms" : ["a",]}, options)

    45     

    46     providers["myveryspecialProvider"] = TestProvider

    47  

    48 

    49 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::

    50 

    51    [balblub]

    52    typ = myveryspecialProvider

    53    #My Option explanation

    54    key = mykey

    55 

    56 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.

    57 

    58 Creating sipgate provider

    59 -------------------------

    60 

    61 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:

    62 

    63 .. code-block:: python

    64     :linenos:

    65 

    66     from iro.offer import providers, Provider

    67     from iro.config import Option

    68 

    69     class Sipgate(Provider):

    70         def __init__(self,name):

    71             options =[("username", Option(lambda x,y: x,long="Loginname for sipgate", must=True)),

    72                       ("password", Option(lambda x,y: x,long="Password for sipgate", must=True)),]

    73             Provider.__init__(self, name, {"sms" : [None], "fax":[None]}, options)

    74     

    75     providers["sipgate"] = Sipgate

    76  

    77 - *line 6/7* -- we don't have any ideas what is allowed as username/password, so we create a validator that accepts everything.

    78 - *line 8* -- sipgate supports fax and sms, but now diffrent routes, that's we use ``None``.

    79 

    80 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.

    81 

    82 The Twisted Way (recommended solution)

    83 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    84 

    85 First we start to implement the ``fax`` and ``sms`` methods:

    86 

    87 .. code-block:: python

    88     :linenos:

    89     

    90     def proxy(self):

    91         return Proxy("https://%s:%s@samurai.sipgate.net/RPC2"%(self.username, self.password))

    92 

    93     def sms(self, recipient, sms):

    94         args={

    95                 "TOS" : "text",

    96                 "Content" : sms.getContent(),

    97                 "RemoteUri" : "sip:%s%s@sipgate.net"%(recipient.land, recipient.number),

    98                 }

    99         return self.proxy().callRemote("samurai.SessionInitiate",args)

   100 

   101     def fax(self, recipient, fax):

   102         args={

   103             "TOS" : "fax",

   104             "Content" : xmlrpclib.Binary(fax.getAttachment(0)),

   105             "RemoteUri" : "sip:%s%s@sipgate.net"%(recipient.land, recipient.number),

   106             }

   107         return self.proxy().callRemote("samurai.SessionInitiate",args)

   108 

   109 The code is straight forward with the API documentation from sipgate. Now we have to implement the heat of the provider the ``send`` method:

   110 

   111 .. code-block:: python

   112     :linenos:

   113 

   114     def _status(self,value,typ):

   115         if typ not  in self.typs.keys():

   116             raise NoTyp(typ)

   117         return Status(self, None, Decimal("1.00"), 1, value["SessionID"])

   118 

   119     def send(self, typ, recipient, msg):

   120         if typ not  in self.typs.keys():

   121             raise NoTyp(typ)

   122         d = getattr(self,typ)(recipient, msg)

   123         d.addCallback(self._status, typ)

   124         return d

   125 

   126     def getSendFunc(self, typ, route):

   127         """returns :meth:`send` method, if typ and route is valid."""

   128 

   129         Provider.getSendFunc(self, typ, route)

   130         return partial(self.send, typ)

   131 

   132 Because sipgate doesn't support different routes, we implement a send function without route argument.

   133 That's why we have to rewrite the ``getSendFunc`` method. It now returns a partial function with only a binded ``typ``.

   134 

   135 The ``send`` method first test the for a valid typ (*line 7/8*), than it execute the ``sms`` or ``fax`` method.

   136 For a valid provider we have to return a :class:`~iro.model.status.Status` object.

   137 There for we add a callback that returns a :class:`~iro.model.status.Status` object (see ``_status`` method).

   138 

   139 Unfortunatelly sipgate doesn't support methods to get the price for one action.

   140 So we have to set set a fixed price here ``Decimal('1.00')``.

   141 In the wild we implement new configuration parameters for priceing.

   142 

   143 Now the provider is ready to use. For complete source of this tutorial see :class:`iro.offer.sipgate`.