Re #2063: Add more doc in other parts of the library

git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@5697 74dad513-b988-da41-8d7b-12977e46ad98

pjlib-util/include/pjlib-util/cli.h

@@ -400,12 +400,14 @@ PJ_DECL(void) pj_cli_register_front_end(pj_cli_t *cli,
  * Create a new complete command specification from an XML node text and
  * register it to the CLI application.
  *
+ * Note that the input string MUST be NULL terminated.
+ *
  * @param cli		The CLI application.
  * @param group		Optional group to which this command will be added
  * 			to, or specify NULL if this command is a root
  * 			command.
  * @param xml		Input string containing XML node text for the
- * 			command.
+ * 			command, MUST be NULL terminated.
  * @param handler	Function handler for the command. This must be NULL
  * 			if the command specifies a command group.
  * @param p_cmd		Optional pointer to store the newly created

pjlib-util/include/pjlib-util/xml.h

@@ -73,9 +73,12 @@ struct pj_xml_node
  * XML comments ("<!--"), however such constructs will be ignored and will not 
  * be included in the resulted XML node tree.
  *
+ * Note that the XML message input buffer MUST be NULL terminated and have
+ * length at least len+1 (len MUST NOT include the NULL terminator).
+ *
  * @param pool	    Pool to allocate memory from.
- * @param msg	    The XML message to parse.
- * @param len	    The length of the message.
+ * @param msg	    The XML message to parse, MUST be NULL terminated.
+ * @param len	    The length of the message, not including NULL terminator.
  *
  * @return	    XML root node, or NULL if the XML document can not be parsed.
  */

pjlib-util/src/pjlib-util/cli.c

@@ -694,6 +694,9 @@ static pj_status_t add_cmd_node(pj_cli_t *cli,
 
             PJ_USE_EXCEPTION;
 
+	    /* The buffer passed to the scanner is not NULL terminated,
+	     * but should be safe. See ticket #2063.
+	     */
             pj_scan_init(&scanner, attr->value.ptr, attr->value.slen,
                          PJ_SCAN_AUTOSKIP_WS, &on_syntax_error);
 
@@ -722,7 +725,9 @@ static pj_status_t add_cmd_node(pj_cli_t *cli,
                 return (PJ_GET_EXCEPTION());
             }
             PJ_END;
-            
+
+            pj_scan_fini(&scanner);
+
         } else if (!pj_stricmp2(&attr->name, "desc")) {
             pj_strdup(cli->pool, &cmd->desc, &attr->value);
         }
@@ -860,7 +865,9 @@ PJ_DEF(pj_status_t) pj_cli_sess_parse(pj_cli_sess *sess,
     str.slen = 0;
     pj_cli_exec_info_default(info);
 
-    /* Set the parse mode based on the latest char. */
+    /* Set the parse mode based on the latest char.
+     * And NULL terminate the buffer for the scanner.
+     */
     len = pj_ansi_strlen(cmdline);
     if (len > 0 && ((cmdline[len - 1] == '\r')||(cmdline[len - 1] == '\n'))) {
         cmdline[--len] = 0;
@@ -930,6 +937,8 @@ PJ_DEF(pj_status_t) pj_cli_sess_parse(pj_cli_sess *sess,
 	    return PJ_GET_EXCEPTION();
 	}
 	PJ_END;
+	
+	pj_scan_fini(&scanner);
     } 
     
     if ((parse_mode == PARSE_NEXT_AVAIL) || (parse_mode == PARSE_EXEC)) {

pjlib-util/src/pjlib-util/cli_telnet.c

@@ -971,6 +971,8 @@ static pj_status_t get_last_token(pj_str_t *cmd, pj_str_t *str)
 	return PJ_GET_EXCEPTION();
     }
     PJ_END;
+    
+    pj_scan_fini(&scanner);
     return PJ_SUCCESS;
 }
 
@@ -1332,6 +1334,7 @@ static pj_status_t telnet_sess_send_with_format(cli_telnet_sess *sess,
     }
     PJ_END;
 
+    pj_scan_fini(&scanner);
     return PJ_SUCCESS;
 }
 

pjlib-util/src/pjlib-util/scanner.c

@@ -127,11 +127,6 @@ PJ_DEF(void) pj_scan_init( pj_scanner *scanner, char *bufstart,
     scanner->callback = callback;
     scanner->skip_ws = options;
 
-    /* Buffer validation. Must be NULL terminated.
-     * See ticket #2063.
-     */
-    // pj_assert(*(scanner->end) == 0);
-
     if (scanner->skip_ws) 
 	pj_scan_skip_whitespace(scanner);
 }

pjmedia/include/pjmedia/sdp.h

@@ -645,9 +645,12 @@ typedef struct pjmedia_sdp_session pjmedia_sdp_session;
 /**
  * Parse SDP message.
  *
+ * Note that the input message buffer MUST be NULL terminated and have
+ * length at least len+1 (len MUST NOT include the NULL terminator).
+ *
  * @param pool	    The pool to allocate SDP session description.
- * @param buf	    The message buffer.
- * @param len	    The length of the message.
+ * @param buf	    The message buffer, MUST be NULL terminated.
+ * @param len	    The length of the message, excluding NULL terminator.
  * @param p_sdp	    Pointer to receive the SDP session descriptor.
  *
  * @return	    PJ_SUCCESS if message was successfully parsed into

pjmedia/src/pjmedia/sdp.c

@@ -275,6 +275,9 @@ PJ_DEF(pj_status_t) pjmedia_sdp_attr_get_rtpmap( const pjmedia_sdp_attr *attr,
 	attr->value.ptr[attr->value.slen] = '\0';
     }
 
+    /* The buffer passed to the scanner is not guaranteed to be NULL
+     * terminated, but should be safe. See ticket #2063.
+     */    
     pj_scan_init(&scanner, (char*)attr->value.ptr, attr->value.slen,
 		 PJ_SCAN_AUTOSKIP_WS, &on_scanner_error);
 
@@ -385,6 +388,9 @@ PJ_DEF(pj_status_t) pjmedia_sdp_attr_get_rtcp(const pjmedia_sdp_attr *attr,
      *	a=rtcp:<port> [nettype addrtype address]
      */
 
+    /* The buffer passed to the scanner is not guaranteed to be NULL
+     * terminated, but should be safe. See ticket #2063.
+     */
     pj_scan_init(&scanner, (char*)attr->value.ptr, attr->value.slen,
 		 PJ_SCAN_AUTOSKIP_WS, &on_scanner_error);
 

pjsip/include/pjsip-simple/iscomposing.h

@@ -104,9 +104,12 @@ PJ_DECL(pjsip_msg_body*) pjsip_iscomposing_create_body( pj_pool_t *pool,
  * Parse the buffer and return message composition indication in the 
  * message.
  *
+ * Note that the input string buffer MUST be NULL terminated and have
+ * length at least len+1 (len MUST NOT include the NULL terminator).
+ *
  * @param pool		    Pool to allocate memory for the parsing process.
- * @param msg		    The message to be parsed.
- * @param len		    Length of the message.
+ * @param msg		    The message to be parsed, MUST be NULL terminated.
+ * @param len		    Length of the message, excluding NULL terminator.
  * @param p_is_composing    Optional pointer to receive iscomposing status.
  * @param p_last_active	    Optional pointer to receive last active attribute.
  * @param p_content_type    Optional pointer to receive content type attribute.

pjsip/include/pjsip-simple/xpidf.h

@@ -60,9 +60,12 @@ PJ_DECL(pjxpidf_pres*) pjxpidf_create(pj_pool_t *pool, const pj_str_t *uri);
 /**
  * Parse XPIDF document.
  *
+ * Note that the input text buffer MUST be NULL terminated and have
+ * length at least len+1 (len MUST NOT include the NULL terminator).
+ *
  * @param pool	    Pool.
- * @param text	    Input text.
- * @param len	    Length of input text.
+ * @param text	    Input text, MUST be NULL terminated.
+ * @param len	    Length of input text, NOT including the NULL terminator.
  *
  * @return	    XPIDF document.
  */

pjsip/include/pjsip/sip_parser.h

@@ -279,10 +279,11 @@ PJ_DECL(pjsip_msg *) pjsip_parse_rdata( char *buf, pj_size_t size,
 /**
  * Check incoming packet to see if a (probably) valid SIP message has been 
  * received.
- * Note that the input string buffer MUST be NULL terminated.
+ * Note that the input string buffer MUST be NULL terminated and have
+ * length at least size+1 (size MUST NOT include the NULL terminator).
  *
  * @param buf		The input buffer, which must be NULL terminated.
- * @param size		The buffer size.
+ * @param size		The length of the string (not counting NULL terminator).
  * @param is_datagram	Put non-zero if transport is datagram oriented.
  * @param msg_size	[out] If message is valid, this parameter will contain
  *			the size of the SIP message (including body, if any).

pjsip/src/pjsip/sip_parser.c

@@ -877,6 +877,9 @@ PJ_DEF(pj_status_t) pjsip_find_msg( const char *buf, pj_size_t size,
 	    pj_scanner scanner;
 	    PJ_USE_EXCEPTION;
 
+	    /* The buffer passed to the scanner is not NULL terminated,
+             * but should be safe. See ticket #2063.
+	     */ 
 	    pj_scan_init(&scanner, (char*)line, hdr_end-line, 
 			 PJ_SCAN_AUTOSKIP_WS_HEADER, &on_syntax_error);