diff options
author | Benny Prijono <bennylp@teluu.com> | 2008-07-17 14:19:10 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2008-07-17 14:19:10 +0000 |
commit | 85a2dd3b4a8aff9faf95415c8e8384ee2999cd04 (patch) | |
tree | c8e1d31762c36f65b7b539e4c417b6cc7d678f08 /pjsip/include | |
parent | d6f361a21e8709fe8b18d8a3bd673f830f3920e9 (diff) |
Ticket #192: Add callback to notify application about incoming SUBSCRIBE request, and add subscription state and termination reason in buddy info
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2150 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include')
-rw-r--r-- | pjsip/include/pjsua-lib/pjsua.h | 128 | ||||
-rw-r--r-- | pjsip/include/pjsua-lib/pjsua_internal.h | 15 |
2 files changed, 136 insertions, 7 deletions
diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index cbda0587..326f5306 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -393,6 +393,11 @@ typedef int pjsua_recorder_id; /** Conference port identification */ typedef int pjsua_conf_port_id; +/** Opaque declaration for server side presence subscription */ +typedef struct pjsua_srv_pres pjsua_srv_pres; + +/** Forward declaration for pjsua_msg_data */ +typedef struct pjsua_msg_data pjsua_msg_data; /** @@ -793,6 +798,79 @@ typedef struct pjsua_callback void (*on_reg_state)(pjsua_acc_id acc_id); /** + * Notification when incoming SUBSCRIBE request is received. Application + * may use this callback to authorize the incoming subscribe request + * (e.g. ask user permission if the request should be granted). + * + * If this callback is not implemented, all incoming presence subscription + * requests will be accepted. + * + * If this callback is implemented, application has several choices on + * what to do with the incoming request: + * - it may reject the request immediately by specifying non-200 class + * final response in the \a code argument. + * - it may immediately accept the request by specifying 200 as the + * \a code argument. This is the default value if application doesn't + * set any value to the \a code argument. In this case, the library + * will automatically send NOTIFY request upon returning from this + * callback. + * - it may delay the processing of the request, for example to request + * user permission whether to accept or reject the request. In this + * case, the application MUST set the \a code argument to 202, and + * later calls #pjsua_pres_notify() to accept or reject the + * subscription request. + * + * Any \a code other than 200 and 202 will be treated as 200. + * + * Application MUST return from this callback immediately (e.g. it must + * not block in this callback while waiting for user confirmation). + * + * @param srv_pres Server presence subscription instance. If + * application delays the acceptance of the request, + * it will need to specify this object when calling + * #pjsua_pres_notify(). + * @param acc_id Account ID most appropriate for this request. + * @param buddy_id ID of the buddy matching the sender of the + * request, if any, or PJSUA_INVALID_ID if no + * matching buddy is found. + * @param from The From URI of the request. + * @param rdata The incoming request. + * @param code The status code to respond to the request. The + * default value is 200. Application may set this + * to other final status code to accept or reject + * the request. + * @param reason The reason phrase to respond to the request. + * @param msg_data If the application wants to send additional + * headers in the response, it can put it in this + * parameter. + */ + void (*on_incoming_subscribe)(pjsua_acc_id acc_id, + pjsua_srv_pres *srv_pres, + pjsua_buddy_id buddy_id, + const pj_str_t *from, + pjsip_rx_data *rdata, + pjsip_status_code *code, + pj_str_t *reason, + pjsua_msg_data *msg_data); + + /** + * Notification when server side subscription state has changed. + * This callback is optional as application normally does not need + * to do anything to maintain server side presence subscription. + * + * @param acc_id The account ID. + * @param srv_pres Server presence subscription object. + * @param remote_uri Remote URI string. + * @param state New subscription state. + * @param event PJSIP event that triggers the state change. + */ + void (*on_srv_subscribe_state)(pjsua_acc_id acc_id, + pjsua_srv_pres *srv_pres, + const pj_str_t *remote_uri, + pjsip_evsub_state state, + pjsip_event *event); + + /** * Notify application when the buddy state has changed. * Application may then query the buddy into to get the details. * @@ -1193,7 +1271,7 @@ PJ_DECL(void) pjsua_config_dup(pj_pool_t *pool, msg_data = py_pjsua.msg_data_init() * \endcode */ -typedef struct pjsua_msg_data +struct pjsua_msg_data { /** * Additional message headers as linked list. Application can add @@ -1221,7 +1299,7 @@ typedef struct pjsua_msg_data */ pj_str_t msg_body; -} pjsua_msg_data; +}; /** @@ -2412,7 +2490,6 @@ PJ_DECL(pj_status_t) pjsua_acc_set_online_status2(pjsua_acc_id acc_id, PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, pj_bool_t renew); - /** * Get information about the specified account. * @@ -3352,6 +3429,22 @@ typedef struct pjsua_buddy_info pj_bool_t monitor_pres; /** + * If \a monitor_pres is enabled, this specifies the last state of the + * presence subscription. If presence subscription session is currently + * active, the value will be PJSIP_EVSUB_STATE_ACTIVE. If presence + * subscription request has been rejected, the value will be + * PJSIP_EVSUB_STATE_TERMINATED, and the termination reason will be + * specified in \a sub_term_reason. + */ + pjsip_evsub_state sub_state; + + /** + * Specifies the last presence subscription terminatino reason. If + * presence subscription is currently active, the value will be empty. + */ + pj_str_t sub_term_reason; + + /** * Extended RPID information about the person. */ pjrpid_element rpid; @@ -3521,6 +3614,35 @@ PJ_DECL(pj_status_t) pjsua_buddy_update_pres(pjsua_buddy_id buddy_id); /** + * Send NOTIFY to inform account presence status or to terminate server + * side presence subscription. If application wants to reject the incoming + * request, it should set the \a state to PJSIP_EVSUB_STATE_TERMINATED. + * + * @param acc_id Account ID. + * @param srv_pres Server presence subscription instance. + * @param state New state to set. + * @param state_str Optionally specify the state string name, if state + * is not "active", "pending", or "terminated". + * @param reason If the new state is PJSIP_EVSUB_STATE_TERMINATED, + * optionally specify the termination reason. + * @param with_body If the new state is PJSIP_EVSUB_STATE_TERMINATED, + * this specifies whether the NOTIFY request should + * contain message body containing account's presence + * information. + * @param msg_data Optional list of headers to be sent with the NOTIFY + * request. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pjsua_pres_notify(pjsua_acc_id acc_id, + pjsua_srv_pres *srv_pres, + pjsip_evsub_state state, + const pj_str_t *state_str, + const pj_str_t *reason, + pj_bool_t with_body, + const pjsua_msg_data *msg_data); + +/** * Dump presence subscriptions to log. * * @param verbose Yes or no. diff --git a/pjsip/include/pjsua-lib/pjsua_internal.h b/pjsip/include/pjsua-lib/pjsua_internal.h index 3660540f..7245469c 100644 --- a/pjsip/include/pjsua-lib/pjsua_internal.h +++ b/pjsip/include/pjsua-lib/pjsua_internal.h @@ -85,12 +85,15 @@ typedef struct pjsua_call /** * Server presence subscription list head. */ -typedef struct pjsua_srv_pres +struct pjsua_srv_pres { PJ_DECL_LIST_MEMBER(struct pjsua_srv_pres); - pjsip_evsub *sub; - char *remote; -} pjsua_srv_pres; + pjsip_evsub *sub; /**< The evsub. */ + char *remote; /**< Remote URI. */ + int acc_id; /**< Account ID. */ + pjsip_dialog *dlg; /**< Dialog. */ + int expires; /**< "expires" value in the request. */ +}; /** @@ -151,6 +154,9 @@ typedef struct pjsua_transport_data } pjsua_transport_data; +/** Maximum length of subscription termination reason. */ +#define PJSUA_BUDDY_SUB_TERM_REASON_LEN 32 + /** * Buddy data. */ @@ -167,6 +173,7 @@ typedef struct pjsua_buddy pj_bool_t monitor; /**< Should we monitor? */ pjsip_dialog *dlg; /**< The underlying dialog. */ pjsip_evsub *sub; /**< Buddy presence subscription */ + pj_str_t term_reason;/**< Subscription termination reason */ pjsip_pres_status status; /**< Buddy presence status. */ } pjsua_buddy; |