1# Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
2# Use of this source code is governed by a BSD-style license that can be
3# found in the LICENSE file.
4
5import dbus
6
7from autotest_lib.client.cros.cellular import mm1_constants
8
9class ModemSimple(dbus.service.Interface):
10    """
11    Python binding for the org.freedesktop.ModemManager1.Modem.Simple
12    interface. All subclasses of Modem must implement this interface.
13    The Simple interface allows controlling and querying the status of
14    modems.
15
16    """
17
18    # Remember to decorate your concrete implementation with
19    # @utils.log_dbus_method(return_cb_arg='return_cb', raise_cb_arg='raise_cb')
20    @dbus.service.method(mm1_constants.I_MODEM_SIMPLE,
21                         in_signature='a{sv}', out_signature='o',
22                         async_callbacks=('return_cb', 'raise_cb'))
23    def Connect(self, properties, return_cb, raise_cb):
24        """
25        Do everything needed to connect the modem using the given properties.
26
27        This method will attempt to find a matching packet data bearer and
28        activate it if necessary, returning the bearer's IP details. If no
29        matching bearer is found, a new bearer will be created and activated,
30        but this operation may fail if no resources are available to complete
31        this connection attempt (i.e., if a conflicting bearer is already
32        active).
33
34        This call may make a large number of changes to modem configuration
35        based on properties passed in. For example, given a PIN-locked,
36        disabled GSM/UMTS modem, this call may unlock the SIM PIN, alter the
37        access technology preference, wait for network registration (or force
38        registration to a specific provider), create a new packet data bearer
39        using the given "apn", and connect that bearer.
40
41        @param properties: See the ModemManager Reference Manual for the allowed
42                key/value pairs in properties.
43        @param return_cb: The callback to execute to send an asynchronous
44                response for the initial Connect request.
45        @param raise_cb: The callback to execute to send an asynchronous error
46                in response to the initial Connect request.
47        @returns: On successfult connect, returns the object path of the connected
48                packet data bearer used for the connection attempt. The value
49                is returned asynchronously via return_cb.
50
51        """
52        raise NotImplementedError()
53
54
55    # Remember to decorate your concrete implementation with
56    # @utils.log_dbus_method(return_cb_arg='return_cb', raise_cb_arg='raise_cb')
57    @dbus.service.method(mm1_constants.I_MODEM_SIMPLE, in_signature='o',
58                         async_callbacks=('return_cb', 'raise_cb'))
59    def Disconnect(self, bearer, return_cb, raise_cb, *return_cb_args):
60        """
61        Disconnect an active packet data connection.
62
63        @param bearer: The object path of the data bearer to disconnect. If the
64                path is "/" (i.e. no object given) this method will disconnect
65                all active packet data bearers.
66        @param return_cb: The callback to execute to send an asynchronous
67                response for the initial Disconnect request.
68        @param raise_cb: The callback to execute to send an asynchronous error
69                in response to the initial Disconnect request.
70        @param return_cb_args: Optional arguments which will be supplied to
71                return_cb. This allows control flow to be set when this method
72                is called from within the pseudo modem manager.
73
74        """
75        raise NotImplementedError()
76
77
78    # Remember to decorate your concrete implementation with
79    # @utils.log_dbus_method()
80    @dbus.service.method(mm1_constants.I_MODEM_SIMPLE, out_signature='a{sv}')
81    def GetStatus(self):
82        """
83        Gets the general modem status.
84
85        @returns: Dictionary of properties. See the ModemManager Reference Manual
86                for the predefined common properties.
87
88        """
89        raise NotImplementedError()
90