Mercurial > libervia-backend

comparison sat/plugins/plugin_xep_0166/models.py @ 4044:3900626bc100

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
plugin XEP-0166: refactoring, and various improvments: - add models for transport and applications handlers and linked data - split models into separate file - some type hints - some documentation comments - add actions to prepare confirmation, useful to do initial parsing of all contents - application arg/kwargs and some transport data can be initialised during Jingle `initiate` call, this is notably useful when a call is made with transport data (this is the call for A/V calls where codecs and ICE candidate can be specified when starting a call) - session data can be specified during Jingle `initiate` call - new `store_in_session` argument in `_parse_elements`, which can be used to avoid race-condition when a context element (<decription> or <transport>) is being parsed for an action while an other action happens (like `transport-info`) - don't sed `sid` in `transport_elt` during a `transport-info` action anymore in `build_action`: this is specific to Jingle File Transfer and has been moved there rel 419
author Goffi <goffi@goffi.org>
date Mon, 15 May 2023 16:23:11 +0200
parents
children 2ced30f6d5de
comparison
equal deleted inserted replaced
4043:9641ce286e07 4044:3900626bc100
1 #!/usr/bin/env python3
2
3 # Libervia plugin for Jingle (XEP-0166)
4 # Copyright (C) 2009-2021 Jérôme Poisson (goffi@goffi.org)
5
6 # This program is free software: you can redistribute it and/or modify
7 # it under the terms of the GNU Affero General Public License as published by
8 # the Free Software Foundation, either version 3 of the License, or
9 # (at your option) any later version.
10
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU Affero General Public License for more details.
15
16 # You should have received a copy of the GNU Affero General Public License
17 # along with this program. If not, see <http://www.gnu.org/licenses/>.
18
19
20 import abc
21 from dataclasses import dataclass
22 from typing import Awaitable, Callable, Union
23
24 from twisted.internet import defer
25 from twisted.words.xish import domish
26
27 from sat.core.core_types import SatXMPPEntity
28 from sat.core.i18n import _
29
30
31 class BaseApplicationHandler(abc.ABC):
32
33 @abc.abstractmethod
34 def jingle_request_confirmation(
35 self,
36 client: SatXMPPEntity,
37 action: str,
38 session: dict,
39 content_name: str,
40 desc_elt: domish.Element,
41 ) -> Union[
42 Callable[..., Union[bool, defer.Deferred]],
43 Callable[..., Awaitable[bool]]
44 ]:
45 """
46 If present, it is called on when session must be accepted.
47 If not present, a generic accept dialog will be used.
48
49 @param session: Jingle Session
50 @param desc_elt: <description> element
51 @return: True if the session is accepted.
52 A Deferred can be returned.
53 """
54 pass
55
56 @abc.abstractmethod
57 def jingle_session_init(
58 self,
59 client: SatXMPPEntity,
60 session: dict,
61 content_name: str,
62 *args, **kwargs
63 ) -> Union[
64 Callable[..., domish.Element],
65 Callable[..., Awaitable[domish.Element]]
66 ]:
67 """
68 Must return the domish.Element used for initial content.
69
70 @param client: SatXMPPEntity instance
71 @param session: Jingle Session
72 @param content_name: Name of the content
73 @return: The domish.Element used for initial content
74 """
75 pass
76
77 @abc.abstractmethod
78 def jingle_handler(
79 self,
80 client: SatXMPPEntity,
81 action: str,
82 session: dict,
83 content_name: str,
84 transport_elt: domish.Element
85 ) -> Union[
86 Callable[..., None],
87 Callable[..., Awaitable[None]]
88 ]:
89 """
90 Called on several actions to negotiate the application or transport.
91
92 @param client: SatXMPPEntity instance
93 @param action: Jingle action
94 @param session: Jingle Session
95 @param content_name: Name of the content
96 @param transport_elt: Transport element
97 """
98 pass
99
100 @abc.abstractmethod
101 def jingle_terminate(
102 self,
103 reason_elt: domish.Element
104 ) -> Union[
105 Callable[..., None],
106 Callable[..., Awaitable[None]]
107 ]:
108 """
109 Called on session terminate, with reason_elt.
110 May be used to clean session.
111
112 @param reason_elt: Reason element
113 """
114 pass
115
116
117 class BaseTransportHandler(abc.ABC):
118
119 @abc.abstractmethod
120 def jingle_session_init(
121 self,
122 client: SatXMPPEntity,
123 session: dict,
124 content_name: str,
125 *args, **kwargs
126 ) -> Union[
127 Callable[..., domish.Element],
128 Callable[..., Awaitable[domish.Element]]
129 ]:
130 """
131 Must return the domish.Element used for initial content.
132
133 @param client: SatXMPPEntity instance
134 @param session: Jingle Session
135 @param content_name: Name of the content
136 @return: The domish.Element used for initial content
137 """
138 pass
139
140 @abc.abstractmethod
141 def jingle_handler(
142 self,
143 client: SatXMPPEntity,
144 action: str,
145 session: dict,
146 content_name: str,
147 transport_elt: domish.Element
148 ) -> Union[
149 Callable[..., None],
150 Callable[..., Awaitable[None]]
151 ]:
152 """
153 Called on several actions to negotiate the application or transport.
154
155 @param client: SatXMPPEntity instance
156 @param action: Jingle action
157 @param session: Jingle Session
158 @param content_name: Name of the content
159 @param transport_elt: Transport element
160 """
161 pass
162
163
164 @dataclass(frozen=True)
165 class ApplicationData:
166 namespace: str
167 handler: BaseApplicationHandler
168
169
170 @dataclass(frozen=True)
171 class TransportData:
172 namespace: str
173 handler: BaseTransportHandler
174 priority: int
175
176
177 @dataclass(frozen=True)
178 class ContentData:
179 application: ApplicationData
180 app_args: list
181 app_kwargs: dict
182 transport_data: dict
183 content_name: str