Changeset 2940 for pjproject/trunk/pjsip/include/pjsip-simple/publish.h

Timestamp:

Oct 12, 2009 7:44:14 AM (15 years ago)

Author:

bennylp

Message:

Ticket #411: Cannot update account presence's status while previous PUBLISH is in progress (thanks Olivier Beytrison for the report)

• enable request queueing. If PUBLISH is to be sent while another one is still in progress, queue the request and send it later when the ongoing request completes
• this behavior is controlled by new pjsip_publishc_opt structure to control session's options
• default behavior is to queue the request

File:

• pjproject/trunk/pjsip/include/pjsip-simple/publish.h (modified) (5 diffs)

pjproject/trunk/pjsip/include/pjsip-simple/publish.h

@@ -65 +65 @@
 typedef struct pjsip_publishc pjsip_publishc;
 
+
+/**
+ * Client publication options. Application should initialize this structure
+ * with its default values by calling #pjsip_publishc_opt_default()
+ */
+typedef struct pjsip_publishc_opt
+{
+    /**
+     * Specify whether the client publication session should queue the
+     * PUBLISH request should there be another PUBLISH transaction still
+     * pending. If this is set to false, the client will return error
+     * on the PUBLISH request if there is another PUBLISH transaction still
+     * in progress.
+     *
+     * Default: PJSIP_PUBLISHC_QUEUE_REQUEST
+     */
+    pj_bool_t   queue_request;
+
+} pjsip_publishc_opt;
 
 
@@ -90 +109 @@
 
 /**
+ * Initialize client publication session option with default values.
+ *
+ * @param opt       The option.
+ */
+PJ_DECL(void) pjsip_publishc_opt_default(pjsip_publishc_opt *opt);
+
+
+/**
  * Initialize client publication module.
  *
@@ -99 +126 @@
 
 
-
 /**
  * Create client publication structure.
  *
  * @param endpt     Endpoint, used to allocate pool from.
- * @param options   Option flags.
+ * @param opt       Options, or NULL to specify default options.
  * @param token     Opaque data to be associated with the client publication.
  * @param cb        Pointer to callback function to receive publication status.
@@ -112 +138 @@
  */
 PJ_DECL(pj_status_t) pjsip_publishc_create( pjsip_endpoint *endpt, 
-                                            unsigned options,
+                                            const pjsip_publishc_opt *opt,
                                             void *token,
                                             pjsip_publishc_cb *cb, 
@@ -270 +296 @@
  * completes.
  *
+ * If the session has another PUBLISH request outstanding, the behavior
+ * depends on whether request queueing is enabled in the session (this was
+ * set by setting \a queue_request field of #pjsip_publishc_opt to true
+ * when calling #pjsip_publishc_create(). Default is true). If request
+ * queueing is enabled, the request will be queued and the function will 
+ * return PJ_EPENDING. One the outstanding request is complete, the queued
+ * request will be sent automatically. If request queueing is disabled, the
+ * function will reject the request and return PJ_EBUSY.
+ *
  * @param pubc      The client publication structure.
  * @param tdata     Transmit data.
  *
- * @return          PJ_SUCCESS on success.
+ * @return          - PJ_SUCCESS on success, or 
+ *                  - PJ_EPENDING if request is queued, or
+ *                  - PJ_EBUSY if request is rejected because another PUBLISH
+ *                    request is in progress, or
+ *                  - other status code to indicate the error.
  */
 PJ_DECL(pj_status_t) pjsip_publishc_send(pjsip_publishc *pubc,