ARI: Fix endpoint/channel subscription issues; allow for subscriptions to tech
[asterisk/asterisk.git] / include / asterisk / xmpp.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief XMPP Interface
21  * \author Joshua Colp <jcolp@digium.com>
22  * IKSEMEL http://iksemel.jabberstudio.org
23  */
24
25 #ifndef _ASTERISK_XMPP_H
26 #define _ASTERISK_XMPP_H
27
28 #ifdef HAVE_OPENSSL
29
30 #include <openssl/ssl.h>
31 #include <openssl/err.h>
32 #define TRY_SECURE 2
33 #define SECURE 4
34
35 #endif /* HAVE_OPENSSL */
36
37 /* file is read by blocks with this size */
38 #define NET_IO_BUF_SIZE 16384
39
40 /* Return value for timeout connection expiration */
41 #define IKS_NET_EXPIRED 12
42
43 #include <iksemel.h>
44
45 #include "asterisk/utils.h"
46 #include "asterisk/astobj2.h"
47 #include "asterisk/linkedlists.h"
48 #include "asterisk/stringfields.h"
49 #include "asterisk/pbx.h"
50 #include "asterisk/stasis.h"
51
52 /*
53  * As per RFC 3920 - section 3.1, the maximum length for a full Jabber ID
54  * is 3071 bytes.
55  * The ABNF syntax for jid :
56  * jid = [node "@" ] domain [ "/" resource ]
57  * Each allowable portion of a JID (node identifier, domain identifier,
58  * and resource identifier) MUST NOT be more than 1023 bytes in length,
59  * resulting in a maximum total size (including the '@' and '/' separators)
60  * of 3071 bytes.
61  */
62 #define XMPP_MAX_JIDLEN 3071
63
64 /*! \brief Maximum size of a resource JID */
65 #define XMPP_MAX_RESJIDLEN 1023
66
67 /*! \brief Maximum size of an attribute */
68 #define XMPP_MAX_ATTRLEN   256
69
70 /*! \brief Client connection states */
71 enum xmpp_state {
72         XMPP_STATE_DISCONNECTING,   /*!< Client is disconnecting */
73         XMPP_STATE_DISCONNECTED,    /*!< Client is disconnected */
74         XMPP_STATE_CONNECTING,      /*!< Client is connecting */
75         XMPP_STATE_REQUEST_TLS,     /*!< Client should request TLS */
76         XMPP_STATE_REQUESTED_TLS,   /*!< Client has requested TLS */
77         XMPP_STATE_AUTHENTICATE,    /*!< Client needs to authenticate */
78         XMPP_STATE_AUTHENTICATING,  /*!< Client is authenticating */
79         XMPP_STATE_ROSTER,          /*!< Client is currently getting the roster */
80         XMPP_STATE_CONNECTED,       /*!< Client is fully connected */
81 };
82
83 /*! \brief Resource capabilities */
84 struct ast_xmpp_capabilities {
85         char node[200];        /*!< Node string from the capabilities stanza in presence notification */
86         char version[50];      /*!< Version string from the capabilities stanza in presence notification */
87         unsigned int jingle:1; /*!< Set if the resource supports Jingle */
88         unsigned int google:1; /*!< Set if the resource supports Google Talk */
89 };
90
91 /*! \brief XMPP Resource */
92 struct ast_xmpp_resource {
93         char resource[XMPP_MAX_RESJIDLEN]; /*!< JID of the resource */
94         int status;                        /*!< Current status of the resource */
95         char *description;                 /*!< Description of the resource */
96         int priority;                      /*!< Priority, used for deciding what resource to use */
97         struct ast_xmpp_capabilities caps; /*!< Capabilities of the resource */
98 };
99
100 /*! \brief XMPP Message */
101 struct ast_xmpp_message {
102         char *from;                            /*!< Who the message is from */
103         char *message;                         /*!< Message contents */
104         char id[25];                           /*!< Identifier for the message */
105         struct timeval arrived;                /*!< When the message arrived */
106         AST_LIST_ENTRY(ast_xmpp_message) list; /*!< Linked list information */
107 };
108
109 struct ast_endpoint;
110
111 /*! \brief XMPP Buddy */
112 struct ast_xmpp_buddy {
113         char id[XMPP_MAX_JIDLEN];        /*!< JID of the buddy */
114         struct ao2_container *resources; /*!< Resources for the buddy */
115         unsigned int subscribe:1;        /*!< Need to subscribe to get their status */
116 };
117
118 /*! \brief XMPP Client Connection */
119 struct ast_xmpp_client {
120         AST_DECLARE_STRING_FIELDS(
121                 /*! Name of the client configuration */
122                 AST_STRING_FIELD(name);
123                 );
124         /*! Message ID */
125         char mid[6];
126         iksid *jid;
127         iksparser *parser;
128         iksfilter *filter;
129         ikstack *stack;
130 #ifdef HAVE_OPENSSL
131         SSL_CTX *ssl_context;
132         SSL *ssl_session;
133         const SSL_METHOD *ssl_method;
134         unsigned int stream_flags;
135 #endif /* HAVE_OPENSSL */
136         enum xmpp_state state;
137         struct ao2_container *buddies;
138         AST_LIST_HEAD(, ast_xmpp_message) messages;
139         pthread_t thread;
140         int timeout;
141         /*! Reconnect this client */
142         unsigned int reconnect:1;
143         /*! If distributing event information the MWI subscription */
144         struct stasis_subscription *mwi_sub;
145         /*! If distributing event information the device state subscription */
146         struct stasis_subscription *device_state_sub;
147         /*! The endpoint associated with this client */
148         struct ast_endpoint *endpoint;
149 };
150
151 /*!
152  * \brief Find an XMPP client connection using a given name
153  *
154  * \param name Name of the client connection
155  *
156  * \retval non-NULL on success
157  * \retval NULL on failure
158  *
159  * \note This will return the client connection with the reference count incremented by one.
160  */
161 struct ast_xmpp_client *ast_xmpp_client_find(const char *name);
162
163 /*!
164  * \brief Disconnect an XMPP client connection
165  *
166  * \param client Pointer to the client
167  *
168  * \retval 0 on success
169  * \retval -1 on failure
170  */
171 int ast_xmpp_client_disconnect(struct ast_xmpp_client *client);
172
173 /*!
174  * \brief Release XMPP client connection reference
175  *
176  * \param client Pointer to the client
177  */
178 void ast_xmpp_client_unref(struct ast_xmpp_client *client);
179
180 /*!
181  * \brief Lock an XMPP client connection
182  *
183  * \param client Pointer to the client
184  */
185 void ast_xmpp_client_lock(struct ast_xmpp_client *client);
186
187 /*!
188  * \brief Unlock an XMPP client connection
189  *
190  * \param client Pointer to the client
191  */
192 void ast_xmpp_client_unlock(struct ast_xmpp_client *client);
193
194 /*!
195  * \brief Send an XML stanza out using an established XMPP client connection
196  *
197  * \param client Pointer to the client
198  * \param stanza Pointer to the Iksemel stanza
199  *
200  * \retval 0 on success
201  * \retval -1 on failure
202  */
203 int ast_xmpp_client_send(struct ast_xmpp_client *client, iks *stanza);
204
205 /*!
206  * \brief Send a message to a given user using an established XMPP client connection
207  *
208  * \param client Pointer to the client
209  * \param user User the message should be sent to
210  * \param message The message to send
211  *
212  * \retval 0 on success
213  * \retval -1 on failure
214  */
215 int ast_xmpp_client_send_message(struct ast_xmpp_client *client, const char *user, const char *message);
216
217 /*!
218  * \brief Invite a user to an XMPP multi-user chatroom
219  *
220  * \param client Pointer to the client
221  * \param user JID of the user
222  * \param room Name of the chatroom
223  * \param message Message to send with the invitation
224  *
225  * \retval 0 on success
226  * \retval -1 on failure
227  */
228 int ast_xmpp_chatroom_invite(struct ast_xmpp_client *client, const char *user, const char *room, const char *message);
229
230 /*!
231  * \brief Join an XMPP multi-user chatroom
232  *
233  * \param client Pointer to the client
234  * \param room Name of the chatroom
235  * \param nickname Nickname to use
236  *
237  * \retval 0 on success
238  * \retval -1 on failure
239  */
240 int ast_xmpp_chatroom_join(struct ast_xmpp_client *client, const char *room, const char *nickname);
241
242 /*!
243  * \brief Send a message to an XMPP multi-user chatroom
244  *
245  * \param client Pointer to the client
246  * \param nickname Nickname to use
247  * \param address Address of the room
248  * \param message Message itself
249  *
250  * \retval 0 on success
251  * \retval -1 on failure
252  */
253 int ast_xmpp_chatroom_send(struct ast_xmpp_client *client, const char *nickname, const char *address, const char *message);
254
255 /*!
256  * \brief Leave an XMPP multi-user chatroom
257  *
258  * \param client Pointer to the client
259  * \param room Name of the chatroom
260  * \param nickname Nickname being used
261  *
262  * \retval 0 on success
263  * \retval -1 on failure
264  */
265 int ast_xmpp_chatroom_leave(struct ast_xmpp_client *client, const char *room, const char *nickname);
266
267 /*!
268  * \brief Helper function which increments the message identifier
269  *
270  * \param mid Pointer to a string containing the message identifier
271  */
272 void ast_xmpp_increment_mid(char *mid);
273
274 #endif