coherence.upnp.core.service (module) — Cohen3 0.8.0 documentation

# coherence.upnp.core.service (module)

## Services

This module contains several classes related to services:

### `Service`

Object representing a device’s service.

### `ServiceServer`

A Service’s server.

### `scpdXML`

A twisted.web.resource.Resource representing xml’s data for SCPD.

Note

SCPD is a Service Control Point Definition, for defining the actions offered by the various services in a UPnP’s network.

### `ServiceControl`

Object to control service’s SOAP actions.

`subscribe`(service)

`unsubscribe`(service)

class `Service`(service_type, service_id, location, control_url, event_sub_url, presentation_url, scpd_url, device)

  Bases: `eventdispatcher.eventdispatcher.EventDispatcher`, `coherence.log.LogAble`

  This class represents a Device’s service. Emits events which will be received by class `Device`.

  Changed in version 0.9.0:

  - Migrated from louie/dispatcher to EventDispatcher

  - The emitted events changed:

    > - Coherence.UPnP.Service.detection_completed => service_detection_completed
    > - Coherence.UPnP.Service.detection_failed => service_detection_failed
    > - Coherence.UPnP.DeviceClient.Service.Event.processed => service_event_processed
    > - Coherence.UPnP.DeviceClient.Service.notified => service_notified

  - changed class variable `detection_completed` to benefit from the EventDispatcher’s properties

  Note

  This class initializes some events outside this class. This is done this way to make easier to make connections between this service and the module `dbus_service`, which uses some events triggered by `StateVariable`. The mentioned events are (old => new):

  > - Coherence.UPnP.StateVariable.changed => state_variable_changed
  > - Coherence.UPnP.StateVariable.{var name}.changed => state_variable_{var name}_changed

  Warning

  This class is special regarding EventDispatcher, because some events are initialized outside this class by the class `StateVariable`.

  `logCategory` = 'service_client'
  `detection_completed`

    To know whenever the service detection has completed. Defaults to False and it will be set automatically to True by the class method `parse_actions()`.

  `as_tuples`()
  `as_dict`()
  `_get_client`(name)
  `remove`()
  `get_device`()
  `get_type`()
  `set_timeout`(timeout)
  `get_timeout`()
  `get_id`()
  `get_sid`()
  `set_sid`(sid)
  `get_actions`()
  `get_scpdXML`()
  `get_action`(name)
  `get_state_variables`(instance)
  `get_state_variable`(name, instance=0)
  `get_control_url`()
  `get_event_sub_url`()
  `get_presentation_url`()
  `get_scpd_url`()
  `get_base_url`()
  `subscribe`()
  `unsubscribe`()
  `subscribe_for_variable`(var_name, instance=0, callback=None, signal=False)
  `renew_subscription`()
  `process_event`(event)
  `parse_actions`()

class `ServiceServer`(id, version, backend)

  Bases: `coherence.log.LogAble`

  `logCategory` = 'service_server'
  `_release`()
  `get_action`(action_name)
  `get_actions`()
  `get_variables`()
  `get_subscribers`()
  `rm_notification`(result, d)
  `new_subscriber`(subscriber)
  `get_id`()
  `get_type`()
  `create_new_instance`(instance)
  `remove_instance`(instance)
  `set_variable`(instance, variable_name, value, default=False)
  `get_variable`(variable_name, instance=0)
  `build_single_notification`(instance, variable_name, value)
  `build_last_change_event`(instance=0, force=False)
  `propagate_notification`(notify)
  `check_subscribers`()
  `check_moderated_variables`()
  `is_variable_moderated`(name)
  `simulate_notification`()
  `get_scpdXML`()
  `register_vendor_variable`(name, implementation='optional', instance=0, evented='no', data_type='string', dependant_variable=None, default_value=None, allowed_values=None, has_vendor_values=False, allowed_value_range=None, moderated=False)

    Enables a backend to add an own, vendor defined, `coherence.upnp.core.variable.StateVariable` to the service.

    Parameters: | name (str) – the name of the new StateVariable implementation (str) – either ‘optional’ or ‘required’ instance – the instance number of the service that variable should be assigned to, usually ‘0’ evented (str) – boolean as string ‘yes’ ‘no’ or the special keyword ‘never’ if the variable doesn’t show up in a LastChange event too data_type (str) – string, boolean, bin.base64 or various number formats dependant_variable (object) – the name of another StateVariable that depends on this one default_value (object) – the value this StateVariable should have by default when created for another instance of in the service allowed_values (list) – a list of values this StateVariable can have has_vendor_values (bool) – if there are values outside the allowed_values list too allowed_value_range (dict) – a dict of ‘minimum’,’maximum’ and ‘step’ values moderated (bool) – True if this StateVariable should only be emitted via a LastChange event
    Returns: | A new variable of class `coherence.upnp.core.variable.StateVariable`

  `register_vendor_action`(name, implementation, arguments=None, needs_callback=True)

    Enables a backend to add an own, vendor defined, Action to the service.

    Parameters: | name (str) – the name of the new Action implementation (str) – either ‘optional’ or ‘required’ arguments (list) – a C{list} if argument C{tuples}, like (name,direction,relatedStateVariable) needs_callback (bool) – this Action needs a method in the backend or service class
    Returns: | An action of class `coherence.upnp.core.action.Action`

  `init_var_and_actions`()

class `scpdXML`(server, control=None)

  Bases: `twisted.web.static.Data`, `coherence.log.LogAble`

  `logCategory` = 'service_scpdxml'
  `render`(request)

    Render a given resource. See L{IResource}’s render method.

    I delegate to methods of self with the form ‘render_METHOD’ where METHOD is the HTTP that was used to make the request. Examples: render_GET, render_HEAD, render_POST, and so on. Generally you should implement those methods instead of overriding this one.

    render_METHOD methods are expected to return a byte string which will be the rendered page, unless the return value is C{server.NOT_DONE_YET}, in which case it is this class’s responsibility to write the results using C{request.write(data)} and then call C{request.finish()}.

    Old code that overrides render() directly is likewise expected to return a byte string or NOT_DONE_YET.

    @see: L{IResource.render}

  `build_xml`()

class `ServiceControl`

  Bases: `coherence.log.LogAble`

  `get_action_results`(result, action, instance)

    check for out arguments if yes:

    > - check if there are related ones to StateVariables with non A_ARG_TYPE_ prefix:

    >   > if yes:

    >   > > - check if there is a call plugin method for this action:

    >   > >   > - if yes: update StateVariable values with call result
    >   > >   > - if no: get StateVariable values and add them to result dict

    Parameters: | result (object) – The result from an action action (object) – An instance of class `coherence.upnp.core.action.Action` instance (object) – An instance of `coherence.upnp.core.variable.StateVariable`
    Returns: | An OrderedDict.

  `soap__generic`(*args, **kwargs)

    Generic UPnP service control method, which will be used if no soap_ACTIONNAME method in the server service control class can be found