Ignore:
Timestamp:
Jul 17, 2008 2:19:10 PM (14 years ago)
Author:
bennylp
Message:

Ticket #192: Add callback to notify application about incoming SUBSCRIBE request, and add subscription state and termination reason in buddy info

File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

    r2118 r2150  
    394394typedef int pjsua_conf_port_id; 
    395395 
     396/** Opaque declaration for server side presence subscription */ 
     397typedef struct pjsua_srv_pres pjsua_srv_pres; 
     398 
     399/** Forward declaration for pjsua_msg_data */ 
     400typedef struct pjsua_msg_data pjsua_msg_data; 
    396401 
    397402 
     
    792797     */ 
    793798    void (*on_reg_state)(pjsua_acc_id acc_id); 
     799 
     800    /** 
     801     * Notification when incoming SUBSCRIBE request is received. Application 
     802     * may use this callback to authorize the incoming subscribe request 
     803     * (e.g. ask user permission if the request should be granted). 
     804     * 
     805     * If this callback is not implemented, all incoming presence subscription 
     806     * requests will be accepted. 
     807     * 
     808     * If this callback is implemented, application has several choices on 
     809     * what to do with the incoming request: 
     810     *  - it may reject the request immediately by specifying non-200 class 
     811     *    final response in the \a code argument. 
     812     *  - it may immediately accept the request by specifying 200 as the 
     813     *    \a code argument. This is the default value if application doesn't 
     814     *    set any value to the \a code argument. In this case, the library 
     815     *    will automatically send NOTIFY request upon returning from this 
     816     *    callback. 
     817     *  - it may delay the processing of the request, for example to request 
     818     *    user permission whether to accept or reject the request. In this  
     819     *    case, the application MUST set the \a code argument to 202, and  
     820     *    later calls #pjsua_pres_notify() to accept or reject the  
     821     *    subscription request. 
     822     * 
     823     * Any \a code other than 200 and 202 will be treated as 200. 
     824     * 
     825     * Application MUST return from this callback immediately (e.g. it must 
     826     * not block in this callback while waiting for user confirmation). 
     827     * 
     828     * @param srv_pres      Server presence subscription instance. If 
     829     *                      application delays the acceptance of the request, 
     830     *                      it will need to specify this object when calling 
     831     *                      #pjsua_pres_notify(). 
     832     * @param acc_id        Account ID most appropriate for this request. 
     833     * @param buddy_id      ID of the buddy matching the sender of the 
     834     *                      request, if any, or PJSUA_INVALID_ID if no 
     835     *                      matching buddy is found. 
     836     * @param from          The From URI of the request. 
     837     * @param rdata         The incoming request. 
     838     * @param code          The status code to respond to the request. The 
     839     *                      default value is 200. Application may set this 
     840     *                      to other final status code to accept or reject 
     841     *                      the request. 
     842     * @param reason        The reason phrase to respond to the request. 
     843     * @param msg_data      If the application wants to send additional 
     844     *                      headers in the response, it can put it in this 
     845     *                      parameter. 
     846     */ 
     847    void (*on_incoming_subscribe)(pjsua_acc_id acc_id, 
     848                                  pjsua_srv_pres *srv_pres, 
     849                                  pjsua_buddy_id buddy_id, 
     850                                  const pj_str_t *from, 
     851                                  pjsip_rx_data *rdata, 
     852                                  pjsip_status_code *code, 
     853                                  pj_str_t *reason, 
     854                                  pjsua_msg_data *msg_data); 
     855 
     856    /** 
     857     * Notification when server side subscription state has changed. 
     858     * This callback is optional as application normally does not need 
     859     * to do anything to maintain server side presence subscription. 
     860     * 
     861     * @param acc_id        The account ID. 
     862     * @param srv_pres      Server presence subscription object. 
     863     * @param remote_uri    Remote URI string. 
     864     * @param state         New subscription state. 
     865     * @param event         PJSIP event that triggers the state change. 
     866     */ 
     867    void (*on_srv_subscribe_state)(pjsua_acc_id acc_id, 
     868                                   pjsua_srv_pres *srv_pres, 
     869                                   const pj_str_t *remote_uri, 
     870                                   pjsip_evsub_state state, 
     871                                   pjsip_event *event); 
    794872 
    795873    /** 
     
    11941272 * \endcode 
    11951273 */ 
    1196 typedef struct pjsua_msg_data 
     1274struct pjsua_msg_data 
    11971275{ 
    11981276    /** 
     
    12221300    pj_str_t    msg_body; 
    12231301 
    1224 } pjsua_msg_data; 
     1302}; 
    12251303 
    12261304 
     
    24122490PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id,  
    24132491                                                pj_bool_t renew); 
    2414  
    24152492 
    24162493/** 
     
    33533430 
    33543431    /** 
     3432     * If \a monitor_pres is enabled, this specifies the last state of the 
     3433     * presence subscription. If presence subscription session is currently 
     3434     * active, the value will be PJSIP_EVSUB_STATE_ACTIVE. If presence 
     3435     * subscription request has been rejected, the value will be 
     3436     * PJSIP_EVSUB_STATE_TERMINATED, and the termination reason will be 
     3437     * specified in \a sub_term_reason. 
     3438     */ 
     3439    pjsip_evsub_state   sub_state; 
     3440 
     3441    /** 
     3442     * Specifies the last presence subscription terminatino reason. If  
     3443     * presence subscription is currently active, the value will be empty. 
     3444     */ 
     3445    pj_str_t            sub_term_reason; 
     3446 
     3447    /** 
    33553448     * Extended RPID information about the person. 
    33563449     */ 
     
    35203613PJ_DECL(pj_status_t) pjsua_buddy_update_pres(pjsua_buddy_id buddy_id); 
    35213614 
     3615 
     3616/** 
     3617 * Send NOTIFY to inform account presence status or to terminate server 
     3618 * side presence subscription. If application wants to reject the incoming 
     3619 * request, it should set the \a state to PJSIP_EVSUB_STATE_TERMINATED. 
     3620 * 
     3621 * @param acc_id        Account ID. 
     3622 * @param srv_pres      Server presence subscription instance. 
     3623 * @param state         New state to set. 
     3624 * @param state_str     Optionally specify the state string name, if state 
     3625 *                      is not "active", "pending", or "terminated". 
     3626 * @param reason        If the new state is PJSIP_EVSUB_STATE_TERMINATED, 
     3627 *                      optionally specify the termination reason.  
     3628 * @param with_body     If the new state is PJSIP_EVSUB_STATE_TERMINATED, 
     3629 *                      this specifies whether the NOTIFY request should 
     3630 *                      contain message body containing account's presence 
     3631 *                      information. 
     3632 * @param msg_data      Optional list of headers to be sent with the NOTIFY 
     3633 *                      request. 
     3634 * 
     3635 * @return              PJ_SUCCESS on success. 
     3636 */ 
     3637PJ_DECL(pj_status_t) pjsua_pres_notify(pjsua_acc_id acc_id, 
     3638                                       pjsua_srv_pres *srv_pres, 
     3639                                       pjsip_evsub_state state, 
     3640                                       const pj_str_t *state_str, 
     3641                                       const pj_str_t *reason, 
     3642                                       pj_bool_t with_body, 
     3643                                       const pjsua_msg_data *msg_data); 
    35223644 
    35233645/** 
Note: See TracChangeset for help on using the changeset viewer.