Asterisk - The Open Source Telephony Project GIT-master-d856a3e
res_pjsip_outbound_publish.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2014, 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#ifndef _RES_PJSIP_OUTBOUND_PUBLISH_H
20#define _RES_PJSIP_OUTBOUND_PUBLISH_H
21
23
24/* Forward declarations */
25struct ast_datastore;
27
28/*!
29 * \brief Opaque structure representing outbound publish configuration
30 */
32
33/*!
34 * \brief Opaque structure representing an outbound publish client
35 */
37
38/*!
39 * \brief Callbacks that event publisher handlers will define
40 */
42 /*! \brief The name of the event this handler deals with */
43 const char *event_name;
44
45 /*!
46 * \brief Called when a publisher should start publishing.
47 *
48 * \param configuration The outbound publish configuration, event-specific configuration
49 * is accessible using extended sorcery fields
50 * \param client The publish client that can be used to send PUBLISH messages.
51 * \retval 0 success
52 * \retval -1 failure
53 */
54 int (*start_publishing)(struct ast_sip_outbound_publish *configuration,
55 struct ast_sip_outbound_publish_client *client);
56
57 /*!
58 * \brief Called when a publisher should stop publishing.
59 *
60 * \param client The publish client that was used to send PUBLISH messages.
61 * \retval 0 success
62 * \retval -1 failure
63 */
65
67};
68
69/*!
70 * \brief Register an event publisher handler
71 *
72 * \retval 0 Handler was registered successfully
73 * \retval non-zero Handler was not registered successfully
74 */
76
77/*!
78 * \brief Unregister a publish handler
79 */
81
82/*!
83 * \brief Find a publish client using its name
84 *
85 * \param name The name of the publish client
86 *
87 * \retval NULL failure
88 * \retval non-NULL success
89 *
90 * \note The publish client is returned with its reference count increased and must be released using
91 * ao2_cleanup.
92 */
94
95/*!
96 * \brief Get the From URI the client will use.
97 * \since 14.0.0
98 *
99 * \param client The publication client to get the From URI
100 *
101 * \retval From-uri on success
102 * \retval Empty-string on failure
103 */
105
106/*!
107 * \brief Get the From URI the client will use for a specific user.
108 * \since 14.0.0
109 *
110 * \param client The publication client to get the From URI of a user
111 * \param user The user to retrieve the From URI for
112 * \param uri A buffer to place the URI into
113 * \param size The size of the buffer
114 *
115 * \retval From-uri on success
116 * \retval Empty-string on failure
117 */
119 char *uri, size_t size);
120
121/*!
122 * \brief Get the To URI the client will use.
123 * \since 14.0.0
124 *
125 * \param client The publication client to get the To URI
126 *
127 * \retval From-uri on success
128 * \retval Empty-string on failure
129 */
131
132/*!
133 * \brief Get the To URI the client will use for a specific user.
134 * \since 14.0.0
135 *
136 * \param client The publication client to get the To URI of a user
137 * \param user The user to retrieve the To URI for
138 * \param uri A buffer to place the URI into
139 * \param size The size of the buffer
140 *
141 * \retval To-uri on success
142 * \retval Empty-string on failure
143 */
145 char *uri, size_t size);
146
147/*!
148 * \brief Alternative for ast_datastore_alloc()
149 *
150 * There are two major differences between this and ast_datastore_alloc()
151 * 1) This allocates a refcounted object
152 * 2) This will fill in a uid if one is not provided
153 *
154 * DO NOT call ast_datastore_free() on a datastore allocated in this
155 * way since that function will attempt to free the datastore rather
156 * than play nicely with its refcount.
157 *
158 * \param info Callbacks for datastore
159 * \param uid Identifier for datastore
160 * \retval NULL Failed to allocate datastore
161 * \retval non-NULL Newly allocated datastore
162 */
164
165/*!
166 * \brief Add a datastore to a SIP event publisher
167 *
168 * Note that SIP uses reference counted datastores. The datastore passed into this function
169 * must have been allocated using ao2_alloc() or there will be serious problems.
170 *
171 * \param client The publication client to add the datastore to
172 * \param datastore The datastore to be added to the subscription
173 * \retval 0 Success
174 * \retval -1 Failure
175 */
177 struct ast_datastore *datastore);
178
179/*!
180 * \brief Retrieve an event publisher datastore
181 *
182 * The datastore retrieved will have its reference count incremented. When the caller is done
183 * with the datastore, the reference counted needs to be decremented using ao2_ref().
184 *
185 * \param client The publication client from which to retrieve the datastore
186 * \param name The name of the datastore to retrieve
187 * \retval NULL Failed to find the specified datastore
188 * \retval non-NULL The specified datastore
189 */
191 const char *name);
192
193/*!
194 * \brief Remove a publication datastore from an event publisher
195 *
196 * This operation may cause the datastore's free() callback to be called if the reference
197 * count reaches zero.
198 *
199 * \param client The publication client to remove the datastore from
200 * \param name The name of the datastore to remove
201 */
203 const char *name);
204
205/*!
206 * \brief Send an outgoing PUBLISH message using a client
207 *
208 * \param client The publication client to send from
209 * \param body An optional body to add to the PUBLISH
210 *
211 * \retval -1 failure
212 * \retval 0 success
213 */
215 const struct ast_sip_body *body);
216
217/*!
218* \brief Send an outgoing PUBLISH message based on the user
219*
220* \param client The publication client to send from
221* \param user The user to send to
222* \param body An optional body to add to the PUBLISH
223*
224* \retval -1 failure
225* \retval 0 success
226*/
228 const char *user, const struct ast_sip_body *body);
229
230/*!
231* \brief Remove the user from the client (stopping it from publishing)
232*
233* \param client The publication client
234* \param user The user to remove
235*/
237 const char *user);
238
239#endif /* RES_PJSIP_OUTBOUND_PUBLISH_H */
static const char name[]
Definition: format_mp3.c:68
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
def info(msg)
int ast_sip_publish_client_add_datastore(struct ast_sip_outbound_publish_client *client, struct ast_datastore *datastore)
Add a datastore to a SIP event publisher.
const char * ast_sip_publish_client_get_user_to_uri(struct ast_sip_outbound_publish_client *client, const char *user, char *uri, size_t size)
Get the To URI the client will use for a specific user.
void ast_sip_publish_client_remove_datastore(struct ast_sip_outbound_publish_client *client, const char *name)
Remove a publication datastore from an event publisher.
const char * ast_sip_publish_client_get_user_from_uri(struct ast_sip_outbound_publish_client *client, const char *user, char *uri, size_t size)
Get the From URI the client will use for a specific user.
void ast_sip_unregister_event_publisher_handler(struct ast_sip_event_publisher_handler *handler)
Unregister a publish handler.
struct ast_datastore * ast_sip_publish_client_alloc_datastore(const struct ast_datastore_info *info, const char *uid)
Alternative for ast_datastore_alloc()
int ast_sip_publish_client_send(struct ast_sip_outbound_publish_client *client, const struct ast_sip_body *body)
Send an outgoing PUBLISH message using a client.
int ast_sip_register_event_publisher_handler(struct ast_sip_event_publisher_handler *handler)
Register an event publisher handler.
const char * ast_sip_publish_client_get_from_uri(struct ast_sip_outbound_publish_client *client)
Get the From URI the client will use.
void ast_sip_publish_client_remove(struct ast_sip_outbound_publish_client *client, const char *user)
Remove the user from the client (stopping it from publishing)
int ast_sip_publish_client_user_send(struct ast_sip_outbound_publish_client *client, const char *user, const struct ast_sip_body *body)
Send an outgoing PUBLISH message based on the user.
struct ast_sip_outbound_publish_client * ast_sip_publish_client_get(const char *name)
Find a publish client using its name.
const char * ast_sip_publish_client_get_to_uri(struct ast_sip_outbound_publish_client *client)
Get the To URI the client will use.
struct ast_datastore * ast_sip_publish_client_get_datastore(struct ast_sip_outbound_publish_client *client, const char *name)
Retrieve an event publisher datastore.
Structure for a data store type.
Definition: datastore.h:31
Structure for a data store object.
Definition: datastore.h:64
const char * uid
Definition: datastore.h:65
SIP body description.
Definition: res_pjsip.h:2325
Callbacks that event publisher handlers will define.
struct ast_sip_event_publisher_handler * next
int(* start_publishing)(struct ast_sip_outbound_publish *configuration, struct ast_sip_outbound_publish_client *client)
Called when a publisher should start publishing.
const char * event_name
The name of the event this handler deals with.
int(* stop_publishing)(struct ast_sip_outbound_publish_client *client)
Called when a publisher should stop publishing.
Outbound publish client state information (persists for lifetime of a publish)
Outbound publish information.
structure to hold users read from users.conf
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59