Ignore:
Timestamp:
Feb 19, 2006 1:38:06 AM (18 years ago)
Author:
bennylp
Message:

Initial SIMPLE implementation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjsip/include/pjsip-simple/presence.h

    • Property svn:keywords set to id
    r65 r197  
    2424 * @brief SIP Extension for Presence (RFC 3856) 
    2525 */ 
    26 #include <pjsip_simple/event_notify.h> 
    27 #include <pjsip_simple/pidf.h> 
    28 #include <pjsip_simple/xpidf.h> 
     26#include <pjsip-simple/evsub.h> 
     27#include <pjsip-simple/pidf.h> 
     28#include <pjsip-simple/xpidf.h> 
    2929 
    3030 
    … …  
    3939 * This module contains the implementation of SIP Presence Extension as  
    4040 * described in RFC 3856. It uses the SIP Event Notification framework 
    41  * (event_notify.h) and extends the framework by implementing "presence" 
     41 * (evsub.h) and extends the framework by implementing "presence" 
    4242 * event package. 
    4343 */ 
    4444 
    45 /** 
    46  * Presence message body type. 
    47  */ 
    48 typedef enum pjsip_pres_type 
     45 
     46 
     47/** 
     48 * Initialize the presence module and register it as endpoint module and 
     49 * package to the event subscription module. 
     50 * 
     51 * @param endpt         The endpoint instance. 
     52 * @param mod_evsub     The event subscription module instance. 
     53 * 
     54 * @return              PJ_SUCCESS if the module is successfully  
     55 *                      initialized and registered to both endpoint 
     56 *                      and the event subscription module. 
     57 */ 
     58PJ_DECL(pj_status_t) pjsip_pres_init_module(pjsip_endpoint *endpt, 
     59                                            pjsip_module *mod_evsub); 
     60 
     61 
     62/** 
     63 * Get the presence module instance. 
     64 * 
     65 * @return              The presence module instance. 
     66 */ 
     67PJ_DECL(pjsip_module*) pjsip_pres_instance(void); 
     68 
     69 
     70#define PJSIP_PRES_STATUS_MAX_INFO  8 
     71 
     72/** 
     73 * This structure describes presence status of a presentity. 
     74 */ 
     75struct pjsip_pres_status 
    4976{ 
    50     PJSIP_PRES_TYPE_PIDF, 
    51     PJSIP_PRES_TYPE_XPIDF, 
    52 } pjsip_pres_type; 
    53  
    54 /** 
    55  * This structure describe a presentity, for both subscriber and notifier. 
    56  */ 
    57 typedef struct pjsip_presentity 
    58 { 
    59     pjsip_event_sub *sub;           /**< Event subscribtion record.     */ 
    60     pjsip_pres_type  pres_type;     /**< Presentity type.               */ 
    61     pjsip_msg_body  *uas_body;      /**< Message body (UAS only).       */ 
    62     union { 
    63         pjpidf_pres *pidf; 
    64         pjxpidf_pres *xpidf; 
    65     }                uas_data;      /**< UAS data.                      */ 
    66     pj_str_t         timestamp;     /**< Time of last update.           */ 
    67     void            *user_data;     /**< Application data.              */ 
    68 } pjsip_presentity; 
    69  
    70  
    71 /** 
    72  * This structure describe callback that is registered to receive notification 
    73  * from the presence module. 
    74  */ 
    75 typedef struct pjsip_presence_cb 
    76 { 
    77     /** 
    78      * This callback is first called when the module receives incoming  
    79      * SUBSCRIBE request to determine whether application wants to accept 
    80      * the request. If it does, then on_presence_request will be called. 
    81      * 
    82      * @param rdata     The received message. 
    83      * @return          Application should return 2xx to accept the request, 
    84      *                  or failure status (>=300) to reject the request. 
    85      */ 
    86     void (*accept_presence)(pjsip_rx_data *rdata, int *status); 
    87  
    88     /** 
    89      * This callback is called when the module receive the first presence 
    90      * subscription request. 
    91      * 
    92      * @param pres      The presence descriptor. 
    93      * @param rdata     The incoming request. 
    94      * @param timeout   Timeout to be set for incoming request. Otherwise 
    95      *                  app can just leave this and accept the default. 
    96      */ 
    97     void (*on_received_request)(pjsip_presentity *pres, pjsip_rx_data *rdata, 
    98                                 int *timeout); 
    99  
    100     /** 
    101      * This callback is called when the module received subscription refresh 
    102      * request. 
    103      * 
    104      * @param pres      The presence descriptor. 
    105      * @param rdata     The incoming request. 
    106      */ 
    107     void (*on_received_refresh)(pjsip_presentity *pres, pjsip_rx_data *rdata); 
    108  
    109     /** 
    110      * This callback is called when the module receives incoming NOTIFY 
    111      * request. 
    112      * 
    113      * @param pres      The presence descriptor. 
    114      * @param open      The latest status of the presentity. 
    115      */ 
    116     void (*on_received_update)(pjsip_presentity *pres, pj_bool_t open); 
    117  
    118     /** 
    119      * This callback is called when the subscription has terminated. 
    120      * 
    121      * @param sub       The subscription instance. 
    122      * @param reason    The termination reason. 
    123      */ 
    124     void (*on_terminated)(pjsip_presentity *pres, const pj_str_t *reason); 
    125  
    126 } pjsip_presence_cb; 
    127  
    128  
    129 /** 
    130  * Initialize the presence module and register callback. 
    131  * 
    132  * @param cb            Callback structure. 
    133  */ 
    134 PJ_DECL(void) pjsip_presence_init(const pjsip_presence_cb *cb); 
    135  
    136  
    137 /** 
    138  * Create to presence subscription of a presentity URL. 
    139  * 
    140  * @param endpt         Endpoint instance. 
    141  * @param local_url     Local URL. 
    142  * @param remote_url    Remote URL which the presence is being subscribed. 
    143  * @param expires       The expiration. 
    144  * @param user_data     User data to attach to presence subscription. 
    145  * 
    146  * @return              The presence structure if successfull, or NULL if 
    147  *                      failed. 
    148  */ 
    149 PJ_DECL(pjsip_presentity*) pjsip_presence_create( pjsip_endpoint *endpt, 
    150                                                   const pj_str_t *local_url, 
    151                                                   const pj_str_t *remote_url, 
    152                                                   int expires, 
    153                                                   void *user_data ); 
    154  
    155 /** 
    156  * Set credentials to be used by this presentity for outgoing requests. 
    157  * 
    158  * @param pres          Presentity instance. 
    159  * @param count         Number of credentials in the array. 
    160  * @param cred          Array of credentials. 
    161  * 
    162  * @return              Zero on success. 
    163  */ 
    164 PJ_DECL(pj_status_t) pjsip_presence_set_credentials( pjsip_presentity *pres, 
    165                                                      int count, 
    166                                                      const pjsip_cred_info cred[]); 
    167  
    168 /** 
    169  * Set route set for outgoing requests. 
    170  * 
    171  * @param pres          Presentity instance. 
    172  * @param route_set     List of route headers. 
    173  * 
    174  * @return              Zero on success. 
    175  */ 
    176 PJ_DECL(pj_status_t) pjsip_presence_set_route_set( pjsip_presentity *pres, 
    177                                                    const pjsip_route_hdr *hdr ); 
    178  
    179 /** 
    180  * Send SUBSCRIBE request for the specified presentity. 
    181  * 
    182  * @param pres          The presentity instance. 
    183  * 
    184  * @return              Zero on success. 
    185  */ 
    186 PJ_DECL(pj_status_t) pjsip_presence_subscribe( pjsip_presentity *pres ); 
    187  
    188 /** 
    189  * Ceased the presence subscription. 
    190  * 
    191  * @param pres          The presence structure. 
    192  *  
    193  * @return              Zero on success. 
    194  */ 
    195 PJ_DECL(pj_status_t) pjsip_presence_unsubscribe( pjsip_presentity *pres ); 
    196  
    197 /** 
    198  * Notify subscriber about change in local status. 
    199  * 
    200  * @param pres          The presence structure. 
    201  * @param state         Set the state of the subscription. 
    202  * @param open          Set the presence status (open or closed). 
    203  * 
    204  * @return              Zero if a NOTIFY request can be sent. 
    205  */ 
    206 PJ_DECL(pj_status_t) pjsip_presence_notify( pjsip_presentity *pres, 
    207                                             pjsip_event_sub_state state, 
    208                                             pj_bool_t open ); 
    209  
    210 /** 
    211  * Destroy presence structure and the underlying subscription. 
    212  * 
    213  * @param pres          The presence structure. 
    214  * 
    215  * @return              Zero if the subscription was destroyed, or one if 
    216  *                      the subscription can not be destroyed immediately 
    217  *                      and will be destroyed later, or -1 if failed. 
    218  */ 
    219 PJ_DECL(pj_status_t) pjsip_presence_destroy( pjsip_presentity *pres ); 
     77    unsigned            info_cnt;       /**< Number of info in the status.  */ 
     78    struct { 
     79 
     80        pj_bool_t       basic_open;     /**< Basic status/availability.     */ 
     81        pj_str_t        id;             /**< Tuple id.                      */ 
     82        pj_str_t        contact;        /**< Optional contact address.      */ 
     83 
     84    } info[PJSIP_PRES_STATUS_MAX_INFO]; /**< Array of info.                 */ 
     85 
     86    pj_bool_t           _is_valid;      /**< Internal flag.                 */ 
     87}; 
     88 
     89 
     90/** 
     91 * @see pjsip_pres_status 
     92 */ 
     93typedef struct pjsip_pres_status pjsip_pres_status; 
     94 
     95 
     96/** 
     97 * Create presence client subscription session. 
     98 * 
     99 * @param dlg           The underlying dialog to use. 
     100 * @param user_cb       Pointer to callbacks to receive presence subscription 
     101 *                      events. 
     102 * @param p_evsub       Pointer to receive the presence subscription 
     103 *                      session. 
     104 * 
     105 * @return              PJ_SUCCESS on success. 
     106 */ 
     107PJ_DECL(pj_status_t) pjsip_pres_create_uac( pjsip_dialog *dlg, 
     108                                            const pjsip_evsub_user *user_cb, 
     109                                            pjsip_evsub **p_evsub ); 
     110 
     111 
     112/** 
     113 * Create presence server subscription session. 
     114 * 
     115 * @param dlg           The underlying dialog to use. 
     116 * @param user_cb       Pointer to callbacks to receive presence subscription 
     117 *                      events. 
     118 * @param rdata         The incoming SUBSCRIBE request that creates the event  
     119 *                      subscription. 
     120 * @param p_evsub       Pointer to receive the presence subscription 
     121 *                      session. 
     122 * 
     123 * @return              PJ_SUCCESS on success. 
     124 */ 
     125PJ_DECL(pj_status_t) pjsip_pres_create_uas( pjsip_dialog *dlg, 
     126                                            const pjsip_evsub_user *user_cb, 
     127                                            pjsip_rx_data *rdata, 
     128                                            pjsip_evsub **p_evsub ); 
     129 
     130 
     131/** 
     132 * Call this function to create request to initiate presence subscription, to  
     133 * refresh subcription, or to request subscription termination. 
     134 * 
     135 * @param sub           Client subscription instance. 
     136 * @param expires       Subscription expiration. If the value is set to zero, 
     137 *                      this will request unsubscription. 
     138 * @param p_tdata       Pointer to receive the request. 
     139 * 
     140 * @return              PJ_SUCCESS on success. 
     141 */ 
     142PJ_DECL(pj_status_t) pjsip_pres_initiate( pjsip_evsub *sub, 
     143                                          pj_int32_t expires, 
     144                                          pjsip_tx_data **p_tdata); 
     145 
     146 
     147 
     148/** 
     149 * Accept the incoming subscription request by sending 2xx response to 
     150 * incoming SUBSCRIBE request. 
     151 * 
     152 * @param sub           Server subscription instance. 
     153 * @param rdata         The incoming subscription request message. 
     154 * @param st_code       Status code, which MUST be final response. 
     155 * @param hdr_list      Optional list of headers to be added in the response. 
     156 * 
     157 * @return              PJ_SUCCESS on success. 
     158 */ 
     159PJ_DECL(pj_status_t) pjsip_pres_accept( pjsip_evsub *sub, 
     160                                        pjsip_rx_data *rdata, 
     161                                        int st_code, 
     162                                        const pjsip_hdr *hdr_list ); 
     163 
     164 
     165 
     166 
     167/** 
     168 * For notifier, create NOTIFY request to subscriber, and set the state  
     169 * of the subscription. Application MUST set the presence status to the 
     170 * appropriate state (by calling #pjsip_pres_set_status()) before calling 
     171 * this function. 
     172 * 
     173 * @param sub           The server subscription (notifier) instance. 
     174 * @param state         New state to set. 
     175 * @param state_str     The state string name, if state contains value other 
     176 *                      than active, pending, or terminated. Otherwise this 
     177 *                      argument is ignored. 
     178 * @param reason        Specify reason if new state is terminated, otherwise 
     179 *                      put NULL. 
     180 * @param p_tdata       Pointer to receive the request. 
     181 * 
     182 * @return              PJ_SUCCESS on success. 
     183 */ 
     184PJ_DECL(pj_status_t) pjsip_pres_notify( pjsip_evsub *sub, 
     185                                        pjsip_evsub_state state, 
     186                                        const pj_str_t *state_str, 
     187                                        const pj_str_t *reason, 
     188                                        pjsip_tx_data **p_tdata); 
     189 
     190 
     191/** 
     192 * Create NOTIFY request to reflect current subscription status. 
     193 * 
     194 * @param sub           Server subscription object. 
     195 * @param p_tdata       Pointer to receive request. 
     196 * 
     197 * @return              PJ_SUCCESS on success. 
     198 */ 
     199PJ_DECL(pj_status_t) pjsip_pres_current_notify( pjsip_evsub *sub, 
     200                                                pjsip_tx_data **p_tdata ); 
     201 
     202 
     203 
     204/** 
     205 * Send request. 
     206 * 
     207 * @param sub           The subscription object. 
     208 * @param tdata         Request message to be sent. 
     209 * 
     210 * @return              PJ_SUCCESS on success. 
     211 */ 
     212PJ_DECL(pj_status_t) pjsip_pres_send_request( pjsip_evsub *sub, 
     213                                              pjsip_tx_data *tdata ); 
     214 
     215 
     216/** 
     217 * Get the presence status. Client normally would call this function 
     218 * after receiving NOTIFY request from server. 
     219 * 
     220 * @param sub           The client or server subscription. 
     221 * @param status        The structure to receive presence status. 
     222 * 
     223 * @return              PJ_SUCCESS on success. 
     224 */ 
     225PJ_DECL(pj_status_t) pjsip_pres_get_status( pjsip_evsub *sub, 
     226                                            pjsip_pres_status *status ); 
     227 
     228 
     229/** 
     230 * Set the presence status. This operation is only valid for server 
     231 * subscription. After calling this function, application would need to 
     232 * send NOTIFY request to client. 
     233 * 
     234 * @param sub           The server subscription. 
     235 * @param status        Status to be set. 
     236 * 
     237 * @return              PJ_SUCCESS on success. 
     238 */ 
     239PJ_DECL(pj_status_t) pjsip_pres_set_status( pjsip_evsub *sub, 
     240                                            const pjsip_pres_status *status ); 
    220241 
    221242 
Note: See TracChangeset for help on using the changeset viewer.