Trying to init events server raises when given port is not free.
[leap_pycommon.git] / src / leap / common / events / __init__.py
1 # -*- coding: utf-8 -*-
2 # __init__.py
3 # Copyright (C) 2013 LEAP
4 #
5 # This program is free software: you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation, either version 3 of the License, or
8 # (at your option) any later version.
9 #
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with this program. If not, see <http://www.gnu.org/licenses/>.
17
18 """
19 An events mechanism that allows for signaling of events between clients.
20 """
21
22 import logging
23 import socket
24
25
26 from leap.common.events import (
27     events_pb2 as proto,
28     server,
29     client,
30     daemon,
31 )
32
33
34 logger = logging.getLogger(__name__)
35
36
37 def register(signal, callback, uid=None, replace=False, reqcbk=None,
38              timeout=1000):
39     """
40     Register a callback to be called when the given signal is received.
41
42     Will timeout after timeout ms if response has not been received. The
43     timeout arg is only used for asynch requests. If a reqcbk callback has
44     been supplied the timeout arg is not used. The response value will be
45     returned for a synch request but nothing will be returned for an asynch
46     request.
47
48     :param signal: the signal that causes the callback to be launched
49     :type signal: int (see the `events.proto` file)
50     :param callback: the callback to be called when the signal is received
51     :type callback: function
52     :param uid: a unique id for the callback
53     :type uid: int
54     :param replace: should an existent callback with same uid be replaced?
55     :type replace: bool
56     :param reqcbk: a callback to be called when a response from server is
57         received
58     :type reqcbk: function
59         callback(leap.common.events.events_pb2.EventResponse)
60     :param timeout: the timeout for synch calls
61     :type timeout: int
62
63     :return: the response from server for synch calls or nothing for asynch
64         calls.
65     :rtype: leap.common.events.events_pb2.EventsResponse or None
66     """
67     return client.register(signal, callback, uid, replace, reqcbk, timeout)
68
69
70 def unregister(signal, uid=None, reqcbk=None, timeout=1000):
71     """
72     Unregister a callback.
73
74     If C{uid} is specified, unregisters only the callback identified by that
75     unique id. Otherwise, unregisters all callbacks registered for C{signal}.
76
77     :param signal: the signal that causes the callback to be launched
78     :type signal: int (see the `events.proto` file)
79     :param uid: a unique id for the callback
80     :type uid: int
81     :param reqcbk: a callback to be called when a response from server is
82         received
83     :type reqcbk: function
84         callback(leap.common.events.events_pb2.EventResponse)
85     :param timeout: the timeout for synch calls
86     :type timeout: int
87
88     :return: the response from server for synch calls or nothing for asynch
89         calls.
90     :rtype: leap.common.events.events_pb2.EventsResponse or None
91     """
92     return client.unregister(signal, uid, reqcbk, timeout)
93
94
95 def signal(signal, content="", mac_method="", mac="", reqcbk=None,
96            timeout=1000):
97     """
98     Send `signal` event to events server.
99
100     Will timeout after timeout ms if response has not been received. The
101     timeout arg is only used for asynch requests.  If a reqcbk callback has
102     been supplied the timeout arg is not used. The response value will be
103     returned for a synch request but nothing will be returned for an asynch
104     request.
105
106     :param signal: the signal that causes the callback to be launched
107     :type signal: int (see the `events.proto` file)
108     :param content: the contents of the event signal
109     :type content: str
110     :param mac_method: the method used to auth mac
111     :type mac_method: str
112     :param mac: the content of the auth mac
113     :type mac: str
114     :param reqcbk: a callback to be called when a response from server is
115         received
116     :type reqcbk: function
117         callback(leap.common.events.events_pb2.EventResponse)
118     :param timeout: the timeout for synch calls
119     :type timeout: int
120
121     :return: the response from server for synch calls or nothing for asynch
122         calls.
123     :rtype: leap.common.events.events_pb2.EventsResponse or None
124     """
125     return client.signal(signal, content, mac_method, mac, reqcbk, timeout)
126
127 def ping_client(port, reqcbk=None, timeout=1000):
128     """
129     Ping a client running in C{port}.
130
131     :param port: the port in which the client should be listening
132     :type port: int
133     :param reqcbk: a callback to be called when a response from client is
134         received
135     :type reqcbk: function
136         callback(leap.common.events.events_pb2.EventResponse)
137     :param timeout: the timeout for synch calls
138     :type timeout: int
139     """
140     return client.ping(port, reqcbk=reqcbk, timeout=timeout)
141
142
143 def ping_server(port=server.SERVER_PORT, reqcbk=None, timeout=1000):
144     """
145     Ping the server.
146
147     :param port: the port in which server should be listening
148     :type port: int
149     :param reqcbk: a callback to be called when a response from server is
150         received
151     :type reqcbk: function
152         callback(leap.common.events.events_pb2.EventResponse)
153     :param timeout: the timeout for synch calls
154     :type timeout: int
155     """
156     return server.ping(port, reqcbk=reqcbk, timeout=timeout)