presence.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414
  1. /*
  2. * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
  3. * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
  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 2 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, write to the Free Software
  17. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18. */
  19. #ifndef __PJSIP_SIMPLE_PRESENCE_H__
  20. #define __PJSIP_SIMPLE_PRESENCE_H__
  21. /**
  22. * @file presence.h
  23. * @brief SIP Extension for Presence (RFC 3856)
  24. */
  25. #include <pjsip-simple/evsub.h>
  26. #include <pjsip-simple/pidf.h>
  27. #include <pjsip-simple/xpidf.h>
  28. #include <pjsip-simple/rpid.h>
  29. PJ_BEGIN_DECL
  30. /**
  31. * @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856)
  32. * @ingroup PJSIP_SIMPLE
  33. * @brief Support for SIP Extension for Presence (RFC 3856)
  34. * @{
  35. *
  36. * This module contains the implementation of SIP Presence Extension as
  37. * described in RFC 3856. It uses the SIP Event Notification framework
  38. * (evsub.h) and extends the framework by implementing "presence"
  39. * event package.
  40. */
  41. /**
  42. * Initialize the presence module and register it as endpoint module and
  43. * package to the event subscription module.
  44. *
  45. * @param endpt The endpoint instance.
  46. * @param mod_evsub The event subscription module instance.
  47. *
  48. * @return PJ_SUCCESS if the module is successfully
  49. * initialized and registered to both endpoint
  50. * and the event subscription module.
  51. */
  52. PJ_DECL(pj_status_t) pjsip_pres_init_module(pjsip_endpoint *endpt,
  53. pjsip_module *mod_evsub);
  54. /**
  55. * Get the presence module instance.
  56. *
  57. * @return The presence module instance.
  58. */
  59. PJ_DECL(pjsip_module*) pjsip_pres_instance(void);
  60. /**
  61. * Maximum presence status info.
  62. */
  63. #define PJSIP_PRES_STATUS_MAX_INFO 8
  64. /**
  65. * This structure describes presence status of a presentity.
  66. */
  67. struct pjsip_pres_status
  68. {
  69. unsigned info_cnt; /**< Number of info in the status. */
  70. struct {
  71. pj_bool_t basic_open; /**< Basic status/availability. */
  72. pjrpid_element rpid; /**< Optional RPID info. */
  73. pj_str_t id; /**< Tuple id. */
  74. pj_str_t contact; /**< Optional contact address. */
  75. pj_xml_node *tuple_node; /**< Pointer to tuple XML node of
  76. parsed PIDF body received from
  77. remote agent. Only valid for
  78. client subscription. If the
  79. last received NOTIFY request
  80. does not contain any PIDF body,
  81. this valud will be set to NULL */
  82. } info[PJSIP_PRES_STATUS_MAX_INFO]; /**< Array of info. */
  83. };
  84. /**
  85. * @see pjsip_pres_status
  86. */
  87. typedef struct pjsip_pres_status pjsip_pres_status;
  88. /**
  89. * Create presence client subscription session.
  90. *
  91. * @param dlg The underlying dialog to use.
  92. * @param user_cb Pointer to callbacks to receive presence subscription
  93. * events.
  94. * @param options Option flags. Currently only PJSIP_EVSUB_NO_EVENT_ID
  95. * is recognized.
  96. * @param p_evsub Pointer to receive the presence subscription
  97. * session.
  98. *
  99. * @return PJ_SUCCESS on success.
  100. */
  101. PJ_DECL(pj_status_t) pjsip_pres_create_uac( pjsip_dialog *dlg,
  102. const pjsip_evsub_user *user_cb,
  103. unsigned options,
  104. pjsip_evsub **p_evsub );
  105. /**
  106. * Create presence server subscription session.
  107. *
  108. * @param dlg The underlying dialog to use.
  109. * @param user_cb Pointer to callbacks to receive presence subscription
  110. * events.
  111. * @param rdata The incoming SUBSCRIBE request that creates the event
  112. * subscription.
  113. * @param p_evsub Pointer to receive the presence subscription
  114. * session.
  115. *
  116. * @return PJ_SUCCESS on success.
  117. */
  118. PJ_DECL(pj_status_t) pjsip_pres_create_uas( pjsip_dialog *dlg,
  119. const pjsip_evsub_user *user_cb,
  120. pjsip_rx_data *rdata,
  121. pjsip_evsub **p_evsub );
  122. /**
  123. * Forcefully destroy the presence subscription. This function should only
  124. * be called on special condition, such as when the subscription
  125. * initialization has failed. For other conditions, application MUST terminate
  126. * the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY.
  127. *
  128. * @param sub The presence subscription.
  129. * @param notify Specify whether the state notification callback
  130. * should be called.
  131. *
  132. * @return PJ_SUCCESS if subscription session has been destroyed.
  133. */
  134. PJ_DECL(pj_status_t) pjsip_pres_terminate( pjsip_evsub *sub,
  135. pj_bool_t notify );
  136. /**
  137. * Call this function to create request to initiate presence subscription, to
  138. * refresh subcription, or to request subscription termination.
  139. *
  140. * @param sub Client subscription instance.
  141. * @param expires Subscription expiration. If the value is set to zero,
  142. * this will request unsubscription. If the value is
  143. * PJSIP_EXPIRES_NOT_SPECIFIED, default expiration
  144. * as defined by the package will be used.
  145. * @param p_tdata Pointer to receive the request.
  146. *
  147. * @return PJ_SUCCESS on success.
  148. */
  149. PJ_DECL(pj_status_t) pjsip_pres_initiate( pjsip_evsub *sub,
  150. pj_uint32_t expires,
  151. pjsip_tx_data **p_tdata);
  152. /**
  153. * Add a list of headers to the subscription instance. The list of headers
  154. * will be added to outgoing presence subscription requests.
  155. *
  156. * @param sub Subscription instance.
  157. * @param hdr_list List of headers to be added.
  158. *
  159. * @return PJ_SUCCESS on success.
  160. */
  161. PJ_DECL(pj_status_t) pjsip_pres_add_header( pjsip_evsub *sub,
  162. const pjsip_hdr *hdr_list );
  163. /**
  164. * Accept the incoming subscription request by sending 2xx response to
  165. * incoming SUBSCRIBE request.
  166. *
  167. * @param sub Server subscription instance.
  168. * @param rdata The incoming subscription request message.
  169. * @param st_code Status code, which MUST be final response.
  170. * @param hdr_list Optional list of headers to be added in the response.
  171. *
  172. * @return PJ_SUCCESS on success.
  173. */
  174. PJ_DECL(pj_status_t) pjsip_pres_accept( pjsip_evsub *sub,
  175. pjsip_rx_data *rdata,
  176. int st_code,
  177. const pjsip_hdr *hdr_list );
  178. /**
  179. * For notifier, create NOTIFY request to subscriber, and set the state
  180. * of the subscription. Application MUST set the presence status to the
  181. * appropriate state (by calling #pjsip_pres_set_status()) before calling
  182. * this function.
  183. *
  184. * @param sub The server subscription (notifier) instance.
  185. * @param state New state to set.
  186. * @param state_str The state string name, if state contains value other
  187. * than active, pending, or terminated. Otherwise this
  188. * argument is ignored.
  189. * @param reason Specify reason if new state is terminated, otherwise
  190. * put NULL.
  191. * @param p_tdata Pointer to receive the request.
  192. *
  193. * @return PJ_SUCCESS on success.
  194. */
  195. PJ_DECL(pj_status_t) pjsip_pres_notify( pjsip_evsub *sub,
  196. pjsip_evsub_state state,
  197. const pj_str_t *state_str,
  198. const pj_str_t *reason,
  199. pjsip_tx_data **p_tdata);
  200. /**
  201. * Create NOTIFY request to reflect current subscription status.
  202. *
  203. * @param sub Server subscription object.
  204. * @param p_tdata Pointer to receive request.
  205. *
  206. * @return PJ_SUCCESS on success.
  207. */
  208. PJ_DECL(pj_status_t) pjsip_pres_current_notify( pjsip_evsub *sub,
  209. pjsip_tx_data **p_tdata );
  210. /**
  211. * Send request message that was previously created with initiate(), notify(),
  212. * or current_notify(). Application may also send request created with other
  213. * functions, e.g. authentication. But the request MUST be either request
  214. * that creates/refresh subscription or NOTIFY request.
  215. *
  216. * @param sub The subscription object.
  217. * @param tdata Request message to be sent.
  218. *
  219. * @return PJ_SUCCESS on success.
  220. */
  221. PJ_DECL(pj_status_t) pjsip_pres_send_request( pjsip_evsub *sub,
  222. pjsip_tx_data *tdata );
  223. /**
  224. * Get the presence status. Client normally would call this function
  225. * after receiving NOTIFY request from server.
  226. *
  227. * @param sub The client or server subscription.
  228. * @param status The structure to receive presence status.
  229. *
  230. * @return PJ_SUCCESS on success.
  231. */
  232. PJ_DECL(pj_status_t) pjsip_pres_get_status( pjsip_evsub *sub,
  233. pjsip_pres_status *status );
  234. /**
  235. * Set the presence status. This operation is only valid for server
  236. * subscription. After calling this function, application would need to
  237. * send NOTIFY request to client.
  238. *
  239. * @param sub The server subscription.
  240. * @param status Status to be set.
  241. *
  242. * @return PJ_SUCCESS on success.
  243. */
  244. PJ_DECL(pj_status_t) pjsip_pres_set_status( pjsip_evsub *sub,
  245. const pjsip_pres_status *status );
  246. /**
  247. * This is a utility function to create PIDF message body from PJSIP
  248. * presence status (pjsip_pres_status).
  249. *
  250. * @param pool The pool to allocate memory for the message body.
  251. * @param status Presence status to be converted into PIDF message
  252. * body.
  253. * @param entity The entity ID, which normally is equal to the
  254. * presentity ID publishing this presence info.
  255. * @param p_body Pointer to receive the SIP message body.
  256. *
  257. * @return PJ_SUCCESS on success.
  258. */
  259. PJ_DECL(pj_status_t) pjsip_pres_create_pidf( pj_pool_t *pool,
  260. const pjsip_pres_status *status,
  261. const pj_str_t *entity,
  262. pjsip_msg_body **p_body );
  263. /**
  264. * This is a utility function to create X-PIDF message body from PJSIP
  265. * presence status (pjsip_pres_status).
  266. *
  267. * @param pool The pool to allocate memory for the message body.
  268. * @param status Presence status to be converted into X-PIDF message
  269. * body.
  270. * @param entity The entity ID, which normally is equal to the
  271. * presentity ID publishing this presence info.
  272. * @param p_body Pointer to receive the SIP message body.
  273. *
  274. * @return PJ_SUCCESS on success.
  275. */
  276. PJ_DECL(pj_status_t) pjsip_pres_create_xpidf(pj_pool_t *pool,
  277. const pjsip_pres_status *status,
  278. const pj_str_t *entity,
  279. pjsip_msg_body **p_body );
  280. /**
  281. * This is a utility function to parse PIDF body into PJSIP presence status.
  282. *
  283. * @param rdata The incoming SIP message containing the PIDF body.
  284. * @param pool Pool to allocate memory to copy the strings into
  285. * the presence status structure.
  286. * @param status The presence status to be initialized.
  287. *
  288. * @return PJ_SUCCESS on success.
  289. *
  290. * @see pjsip_pres_parse_pidf2()
  291. */
  292. PJ_DECL(pj_status_t) pjsip_pres_parse_pidf(pjsip_rx_data *rdata,
  293. pj_pool_t *pool,
  294. pjsip_pres_status *status);
  295. /**
  296. * This is a utility function to parse PIDF body into PJSIP presence status.
  297. *
  298. * @param body Text body, with one extra space at the end to place
  299. * NULL character temporarily during parsing.
  300. * @param body_len Length of the body, not including the NULL termination
  301. * character.
  302. * @param pool Pool to allocate memory to copy the strings into
  303. * the presence status structure.
  304. * @param status The presence status to be initialized.
  305. *
  306. * @return PJ_SUCCESS on success.
  307. *
  308. * @see pjsip_pres_parse_pidf()
  309. */
  310. PJ_DECL(pj_status_t) pjsip_pres_parse_pidf2(char *body, unsigned body_len,
  311. pj_pool_t *pool,
  312. pjsip_pres_status *status);
  313. /**
  314. * This is a utility function to parse X-PIDF body into PJSIP presence status.
  315. *
  316. * @param rdata The incoming SIP message containing the X-PIDF body.
  317. * @param pool Pool to allocate memory to copy the strings into
  318. * the presence status structure.
  319. * @param status The presence status to be initialized.
  320. *
  321. * @return PJ_SUCCESS on success.
  322. *
  323. * @see pjsip_pres_parse_xpidf2()
  324. */
  325. PJ_DECL(pj_status_t) pjsip_pres_parse_xpidf(pjsip_rx_data *rdata,
  326. pj_pool_t *pool,
  327. pjsip_pres_status *status);
  328. /**
  329. * This is a utility function to parse X-PIDF body into PJSIP presence status.
  330. *
  331. * @param body Text body, with one extra space at the end to place
  332. * NULL character temporarily during parsing.
  333. * @param body_len Length of the body, not including the NULL termination
  334. * character.
  335. * @param pool Pool to allocate memory to copy the strings into
  336. * the presence status structure.
  337. * @param status The presence status to be initialized.
  338. *
  339. * @return PJ_SUCCESS on success.
  340. *
  341. * @see pjsip_pres_parse_xpidf()
  342. */
  343. PJ_DECL(pj_status_t) pjsip_pres_parse_xpidf2(char *body, unsigned body_len,
  344. pj_pool_t *pool,
  345. pjsip_pres_status *status);
  346. /**
  347. * @}
  348. */
  349. PJ_END_DECL
  350. #endif /* __PJSIP_SIMPLE_PRESENCE_H__ */