event.h 8.81 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/*
linphone
Copyright (C) 2000 - 2010 Simon MORLAT (simon.morlat@linphone.org)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
18 19
*/

20 21
#ifndef LINPHONE_EVENT_H_
#define LINPHONE_EVENT_H_
22

23
#include "linphone/callbacks.h"
24
#include "linphone/types.h"
25

Ghislain MARY's avatar
Ghislain MARY committed
26 27 28 29
#ifdef __cplusplus
extern "C" {
#endif

30
/**
31 32
 * @addtogroup event_api
 * @{
33 34
**/

35 36
/**
 * Send a subscription previously created by linphone_core_create_subscribe().
37
 * @param ev the #LinphoneEvent
38 39 40
 * @param body optional content to attach with the subscription.
 * @return 0 if successful, -1 otherwise.
**/
41
LINPHONE_PUBLIC LinphoneStatus linphone_event_send_subscribe(LinphoneEvent *ev, const LinphoneContent *body);
42 43

/**
44
 * Update (refresh) an outgoing subscription, changing the body.
45
 * @param lev a #LinphoneEvent
46 47
 * @param body an optional body to include in the subscription update, may be NULL.
**/
48
LINPHONE_PUBLIC LinphoneStatus linphone_event_update_subscribe(LinphoneEvent *lev, const LinphoneContent *body);
49

50 51
/**
 * Refresh an outgoing subscription keeping the same body.
52
 * @param lev #LinphoneEvent object.
53 54
 * @return 0 if successful, -1 otherwise.
 */
55
LINPHONE_PUBLIC LinphoneStatus linphone_event_refresh_subscribe(LinphoneEvent *lev);
56

57 58 59 60

/**
 * Accept an incoming subcription.
**/
61
LINPHONE_PUBLIC LinphoneStatus linphone_event_accept_subscription(LinphoneEvent *lev);
62

63 64 65
/**
 * Deny an incoming subscription with given reason.
**/
66
LINPHONE_PUBLIC LinphoneStatus linphone_event_deny_subscription(LinphoneEvent *lev, LinphoneReason reason);
67

68 69 70 71
/**
 * Send a notification.
 * @param lev a #LinphoneEvent corresponding to an incoming subscription previously received and accepted.
 * @param body an optional body containing the actual notification data.
72
 * @return 0 if successful, -1 otherwise.
73
 **/
74
LINPHONE_PUBLIC LinphoneStatus linphone_event_notify(LinphoneEvent *lev, const LinphoneContent *body);
75

76 77 78 79 80
/**
 * Send a publish created by linphone_core_create_publish().
 * @param lev the #LinphoneEvent
 * @param body the new data to be published
**/
81
LINPHONE_PUBLIC LinphoneStatus linphone_event_send_publish(LinphoneEvent *lev, const LinphoneContent *body);
82 83 84

/**
 * Update (refresh) a publish.
85 86 87
 * @param lev the #LinphoneEvent
 * @param body the new data to be published
**/
88
LINPHONE_PUBLIC LinphoneStatus linphone_event_update_publish(LinphoneEvent *lev, const LinphoneContent *body);
89

90 91
/**
 * Refresh an outgoing publish keeping the same body.
92
 * @param lev #LinphoneEvent object.
93 94
 * @return 0 if successful, -1 otherwise.
 */
95
LINPHONE_PUBLIC LinphoneStatus linphone_event_refresh_publish(LinphoneEvent *lev);
96 97

/**
98
 * Prevent an event from refreshing its publish.
99 100 101
 * This is useful to let registrations to expire naturally (or) when the application wants to keep control on when
 * refreshes are sent.
 * The refreshing operations can be resumed with linphone_proxy_config_refresh_register().
102
 * @param[in] lev #LinphoneEvent object.
103 104
 **/
LINPHONE_PUBLIC void linphone_event_pause_publish(LinphoneEvent *lev);
105 106 107 108

/**
 * Return reason code (in case of error state reached).
**/
Ghislain MARY's avatar
Ghislain MARY committed
109
LINPHONE_PUBLIC LinphoneReason linphone_event_get_reason(const LinphoneEvent *lev);
110

111 112 113
/**
 * Get full details about an error occured.
**/
114
LINPHONE_PUBLIC const LinphoneErrorInfo *linphone_event_get_error_info(const LinphoneEvent *lev);
115

116 117 118
/**
 * Get subscription state. If the event object was not created by a subscription mechanism, #LinphoneSubscriptionNone is returned.
**/
Ghislain MARY's avatar
Ghislain MARY committed
119
LINPHONE_PUBLIC LinphoneSubscriptionState linphone_event_get_subscription_state(const LinphoneEvent *lev);
120

121 122 123 124 125
/**
 * Get publish state. If the event object was not created by a publish mechanism, #LinphonePublishNone is returned.
**/
LINPHONE_PUBLIC LinphonePublishState linphone_event_get_publish_state(const LinphoneEvent *lev);

126 127
/**
 * Get subscription direction.
128
 * If the object wasn't created by a subscription mechanism, #LinphoneSubscriptionInvalidDir is returned.
129
**/
Ghislain MARY's avatar
Ghislain MARY committed
130
LINPHONE_PUBLIC LinphoneSubscriptionDir linphone_event_get_subscription_dir(LinphoneEvent *lev);
131 132 133 134

/**
 * Set a user (application) pointer.
**/
Ghislain MARY's avatar
Ghislain MARY committed
135
LINPHONE_PUBLIC void linphone_event_set_user_data(LinphoneEvent *ev, void *up);
136 137 138 139

/**
 * Retrieve user pointer.
**/
Ghislain MARY's avatar
Ghislain MARY committed
140
LINPHONE_PUBLIC void *linphone_event_get_user_data(const LinphoneEvent *ev);
141

142 143
/**
 * Add a custom header to an outgoing susbscription or publish.
144
 * @param ev the #LinphoneEvent
145 146 147 148 149 150 151
 * @param name header's name
 * @param value the header's value.
**/
LINPHONE_PUBLIC void linphone_event_add_custom_header(LinphoneEvent *ev, const char *name, const char *value);

/**
 * Obtain the value of a given header for an incoming subscription.
152
 * @param ev the #LinphoneEvent
153 154 155 156 157
 * @param name header's name
 * @return the header's value or NULL if such header doesn't exist.
**/
LINPHONE_PUBLIC const char *linphone_event_get_custom_header(LinphoneEvent *ev, const char *name);

158 159
/**
 * Terminate an incoming or outgoing subscription that was previously acccepted, or a previous publication.
160
 * The #LinphoneEvent shall not be used anymore after this operation, unless the application explicitely took a reference on the object with
161
 * linphone_event_ref().
162
**/
Ghislain MARY's avatar
Ghislain MARY committed
163
LINPHONE_PUBLIC void linphone_event_terminate(LinphoneEvent *lev);
164

165
/**
166
 * Increase reference count of LinphoneEvent.
167
 * By default #LinphoneEvents created by the core are owned by the core only.
168 169
 * An application that wishes to retain a reference to it must call linphone_event_ref().
 * When this reference is no longer needed, linphone_event_unref() must be called.
170
 *
171
**/
Ghislain MARY's avatar
Ghislain MARY committed
172
LINPHONE_PUBLIC LinphoneEvent *linphone_event_ref(LinphoneEvent *lev);
173 174 175

/**
 * Decrease reference count.
176
 * @see linphone_event_ref()
177
**/
Ghislain MARY's avatar
Ghislain MARY committed
178
LINPHONE_PUBLIC void linphone_event_unref(LinphoneEvent *lev);
179 180 181 182

/**
 * Get the name of the event as specified in the event package RFC.
**/
Ghislain MARY's avatar
Ghislain MARY committed
183
LINPHONE_PUBLIC const char *linphone_event_get_name(const LinphoneEvent *lev);
184

185 186 187
/**
 * Get the "from" address of the subscription.
**/
Ghislain MARY's avatar
Ghislain MARY committed
188
LINPHONE_PUBLIC const LinphoneAddress *linphone_event_get_from(const LinphoneEvent *lev);
189 190 191 192

/**
 * Get the resource address of the subscription or publish.
**/
Ghislain MARY's avatar
Ghislain MARY committed
193
LINPHONE_PUBLIC const LinphoneAddress *linphone_event_get_resource(const LinphoneEvent *lev);
194

195 196
/**
 * Get the "contact" address of the subscription.
197
 * @param[in] lev #LinphoneEvent object
198 199 200 201
 * @return The "contact" address of the subscription
 */
LINPHONE_PUBLIC const LinphoneAddress *linphone_event_get_remote_contact (const LinphoneEvent *lev);

202
/**
203
 * Returns back pointer to the #LinphoneCore that created this #LinphoneEvent
204 205 206
**/
LINPHONE_PUBLIC LinphoneCore *linphone_event_get_core(const LinphoneEvent *lev);

207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
/**
 * Get the LinphoneEventCbs object associated with a LinphoneEvent.
 * @param[in] ev LinphoneEvent object
 * @return The LinphoneEventCbs object associated with the LinphoneEvent.
**/

LINPHONE_PUBLIC LinphoneEventCbs *linphone_event_get_callbacks(const LinphoneEvent *ev);

/**
 * Acquire a reference to a LinphoneEventCbs object.
 * @param[in] cbs LinphoneEventCbs object.
 * @return The same LinphoneEventCbs object.
**/
LINPHONE_PUBLIC LinphoneEventCbs *linphone_event_cbs_ref(LinphoneEventCbs *cbs);

/**
 * Release a reference to a LinphoneEventCbs object.
 * @param[in] cbs LinphoneEventCbs object.
**/
LINPHONE_PUBLIC void linphone_event_cbs_unref(LinphoneEventCbs *cbs);

/**
 * Retrieve the user pointer associated with a LinphoneEventCbs object.
 * @param[in] cbs LinphoneEventCbs object.
 * @return The user pointer associated with the LinphoneEventCbs object.
**/
LINPHONE_PUBLIC void *linphone_event_cbs_get_user_data(const LinphoneEventCbs *cbs);

/**
 * Assign a user pointer to a LinphoneEventCbs object.
 * @param[in] cbs LinphoneEventCbs object.
 * @param[in] ud The user pointer to associate with the LinphoneEventCbs object.
**/
LINPHONE_PUBLIC void linphone_event_cbs_set_user_data(LinphoneEventCbs *cbs, void *ud);

/**
 * Get the notify response callback.
 * @param[in] cbs LinphoneEventCbs object.
 * @return The current notify response callback.
**/
LINPHONE_PUBLIC LinphoneEventCbsNotifyResponseCb linphone_event_cbs_get_notify_response(const LinphoneEventCbs *cbs);

/**
 * Set the notify response callback.
 * @param[in] cbs LinphoneEventCbs object.
 * @param[in] cb The notify response callback to be used.
**/
LINPHONE_PUBLIC void linphone_event_cbs_set_notify_response(LinphoneEventCbs *cbs, LinphoneEventCbsNotifyResponseCb cb);

256 257 258 259
/**
 * @}
**/

Ghislain MARY's avatar
Ghislain MARY committed
260 261 262 263
#ifdef __cplusplus
}
#endif

264

265
#endif /* LINPHONE_EVENT_H_ */