Changeset 3196 for pjproject/trunk/pjsip/include/pjsip/sip_dialog.h

Timestamp:

Jun 3, 2010 10:41:32 AM (14 years ago)

Author:

nanang

Message:

Re #1089:

• Added a feature in dialog to store and retrieve remote capabilities dug from the remote messages.
• Added few APIs in dialog to query and update remote capabilities, also added an API in pjsua_call to query whether a capability is supported by remote.

File:

• pjproject/trunk/pjsip/include/pjsip/sip_dialog.h (modified) (3 diffs)

pjproject/trunk/pjsip/include/pjsip/sip_dialog.h

@@ -91 +91 @@
 
 /**
+ * Dialog capability status.
+ */
+typedef enum pjsip_dialog_cap_status
+{
+    /** Capability is unsupported. */
+    PJSIP_DIALOG_CAP_UNSUPPORTED    = 0,
+
+    /** Capability is supported */
+    PJSIP_DIALOG_CAP_SUPPORTED      = 1,
+
+    /** 
+     *  Unknown capability status. This is usually because we lack the 
+     *  capability info which is retrieved from capability header specified
+     *  in the dialog messages.
+     */
+    PJSIP_DIALOG_CAP_UNKNOWN        = 2
+} pjsip_dialog_cap_status;
+
+
+/**
  * This structure describes the dialog structure. Application MUST NOT
  * try to SET the values here directly, but instead it MUST use the
@@ -128 +148 @@
     pjsip_dlg_party     local;      /**< Local party info.                  */
     pjsip_dlg_party     remote;     /**< Remote party info.                 */
+    pjsip_hdr           rem_cap_hdr;/**< List of remote capability header.  */
     pjsip_role_e        role;       /**< Initial role.                      */
     pj_bool_t           uac_has_2xx;/**< UAC has received 2xx response?     */
@@ -613 +634 @@
 
 /**
+ * Check if remote peer have the specified capability as published
+ * in the dialog messages from remote peer.
+ *
+ * Notes:
+ * - The capability \a token lookup will apply exact match, but not 
+ *   case-sensitive, for example: <tt>"text/html"</tt> will not match 
+ *   <tt>"text / html"</tt> (notice the spaces).
+ *
+ * @param dlg       The dialog.
+ * @param htype     The header type to be checked, which value may be:
+ *                  - PJSIP_H_ACCEPT
+ *                  - PJSIP_H_ALLOW
+ *                  - PJSIP_H_SUPPORTED
+ * @param hname     If htype specifies PJSIP_H_OTHER, then the header name
+ *                  must be supplied in this argument. Otherwise the value
+ *                  must be set to NULL.
+ * @param token     The capability token to check. For example, if \a htype
+ *                  is PJSIP_H_ALLOW, then \a token specifies the method
+ *                  names; if \a htype is PJSIP_H_SUPPORTED, then \a token
+ *                  specifies the extension names such as "100rel".
+ *
+ * @return          PJSIP_DIALOG_CAP_SUPPORTED if the specified capability
+ *                  is explicitly supported, see @pjsip_dialog_cap_status
+ *                  for more info.
+ */
+PJ_DECL(pjsip_dialog_cap_status) pjsip_dlg_remote_has_cap(
+                                                    pjsip_dialog *dlg,
+                                                    int htype,
+                                                    const pj_str_t *hname,
+                                                    const pj_str_t *token);
+
+/**
+ * Get the specified capability header from the remote capability headers
+ * stored in the dialog.
+ *
+ * @param dlg       The dialog.
+ * @param htype     The header type to be retrieved, which value may be:
+ *                  - PJSIP_H_ACCEPT
+ *                  - PJSIP_H_ALLOW
+ *                  - PJSIP_H_SUPPORTED
+ * @param hname     If htype specifies PJSIP_H_OTHER, then the header name
+ *                  must be supplied in this argument. Otherwise the value
+ *                  must be set to NULL.
+ *
+ * @return          The appropriate header, or NULL if the header is not
+ *                  available.
+ */
+PJ_DECL(const pjsip_hdr*) pjsip_dlg_get_remote_cap_hdr(pjsip_dialog *dlg,
+                                                       int htype,
+                                                       const pj_str_t *hname);
+
+/**
+ * Set remote capability from a SIP header containing array of capability 
+ * tags/values.
+ *
+ * @param dlg       The dialog.
+ * @param cap_hdr   The SIP header.
+ *
+ * @return          PJ_SUCCESS when successful, otherwise the appropriate
+ *                  error code will be returned.
+ */
+PJ_DECL(pj_status_t) pjsip_dlg_set_remote_cap_hdr(
+                                    pjsip_dialog *dlg,
+                                    const pjsip_generic_array_hdr *cap_hdr);
+
+/**
+ * Remove a remote capability header.
+ *
+ * @param dlg       The dialog.
+ * @param htype     The header type to be removed, which value may be:
+ *                  - PJSIP_H_ACCEPT
+ *                  - PJSIP_H_ALLOW
+ *                  - PJSIP_H_SUPPORTED
+ * @param hname     If htype specifies PJSIP_H_OTHER, then the header name
+ *                  must be supplied in this argument. Otherwise the value
+ *                  must be set to NULL.
+ *
+ * @return          PJ_SUCCESS when successful, otherwise the appropriate
+ *                  error code will be returned.
+ */
+PJ_DECL(pj_status_t) pjsip_dlg_remove_remote_cap_hdr(pjsip_dialog *dlg,
+                                                     int htype,
+                                                     const pj_str_t *hname);
+
+/**
+ * Update remote capabilities from a received message. The header types
+ * to be updated from the message will only be \a PJSIP_H_ACCEPT, 
+ * \a PJSIP_H_ALLOW, and \a PJSIP_H_SUPPORTED.
+ *
+ * @param dlg       The dialog.
+ * @param msg       The received message.
+ * @param strict    If this is set to PJ_TRUE, any header types missing
+ *                  from the message will cause removal of existing
+ *                  header types in the capability list. Otherwise, the 
+ *                  capability list will not be modified when any header
+ *                  type is missing.
+ *
+ * @return          PJ_SUCCESS when successful, otherwise the appropriate
+ *                  error code will be returned.
+ */
+PJ_DECL(pj_status_t) pjsip_dlg_update_remote_cap(pjsip_dialog *dlg,
+                                                 const pjsip_msg *msg,
+                                                 pj_bool_t strict);
+
+
+
+/**
  * @}
  */