X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=src%2Fscpi%2Fscpi.c;h=0f767f2a2de1c6862b61620d6e2dc0b9178c2f7d;hb=9417f26fd47556c4b4f6ecaa08a2860672664eb9;hp=9fa4ac03605392245ca0077f468cd006bb99f235;hpb=2dddd5bd5edc3282df09d6d251b9754d3418c233;p=libsigrok.git

diff --git a/src/scpi/scpi.c b/src/scpi/scpi.c
index 9fa4ac03..0f767f2a 100644
--- a/src/scpi/scpi.c
+++ b/src/scpi/scpi.c
@@ -410,9 +410,11 @@ SR_PRIV int sr_scpi_open(struct sr_scpi_dev_inst *scpi)
 /**
  * Get the connection ID of the SCPI device.
  *
- * @param scpi Previously initialized SCPI device structure.
- * @param connection_id Pointer where to store the connection ID. The caller
- *        is responsible for g_free()ing the string when it is no longer needed.
+ * Callers must free the allocated memory regardless of the routine's
+ * return code. See @ref g_free().
+ *
+ * @param[in] scpi Previously initialized SCPI device structure.
+ * @param[out] connection_id Pointer where to store the connection ID.
  *
  * @return SR_OK on success, SR_ERR on failure.
  */
@@ -610,9 +612,12 @@ SR_PRIV void sr_scpi_free(struct sr_scpi_dev_inst *scpi)
 /**
  * Send a SCPI command, receive the reply and store the reply in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the SCPI response.
+ * Callers must free the allocated memory regardless of the routine's
+ * return code. See @ref g_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the SCPI response.
  *
  * @return SR_OK on success, SR_ERR* on failure.
  */
@@ -620,8 +625,10 @@ SR_PRIV int sr_scpi_get_string(struct sr_scpi_dev_inst *scpi,
 			       const char *command, char **scpi_response)
 {
 	GString *response;
-	response = g_string_sized_new(1024);
 
+	*scpi_response = NULL;
+
+	response = g_string_sized_new(1024);
 	if (sr_scpi_get_data(scpi, command, &response) != SR_OK) {
 		if (response)
 			g_string_free(response, TRUE);
@@ -839,14 +846,15 @@ SR_PRIV int sr_scpi_get_opc(struct sr_scpi_dev_inst *scpi)
  * Send a SCPI command, read the reply, parse it as comma separated list of
  * floats and store the as an result in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the parsed result.
+ * Callers must free the allocated memory (unless it's NULL) regardless of
+ * the routine's return code. See @ref g_array_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the parsed result.
  *
  * @return SR_OK upon successfully parsing all values, SR_ERR* upon a parsing
- *         error or upon no response. The allocated response must be freed by
- *         the caller in the case of an SR_OK as well as in the case of
- *         parsing error.
+ *         error or upon no response.
  */
 SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
 			       const char *command, GArray **scpi_response)
@@ -857,6 +865,7 @@ SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
 	gchar **ptr, **tokens;
 	GArray *response_array;
 
+	*scpi_response = NULL;
 	response = NULL;
 	tokens = NULL;
 
@@ -883,7 +892,6 @@ SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
 
 	if (ret != SR_OK && response_array->len == 0) {
 		g_array_free(response_array, TRUE);
-		*scpi_response = NULL;
 		return SR_ERR_DATA;
 	}
 
@@ -896,14 +904,15 @@ SR_PRIV int sr_scpi_get_floatv(struct sr_scpi_dev_inst *scpi,
  * Send a SCPI command, read the reply, parse it as comma separated list of
  * unsigned 8 bit integers and store the as an result in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the parsed result.
+ * Callers must free the allocated memory (unless it's NULL) regardless of
+ * the routine's return code. See @ref g_array_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the parsed result.
  *
  * @return SR_OK upon successfully parsing all values, SR_ERR* upon a parsing
- *         error or upon no response. The allocated response must be freed by
- *         the caller in the case of an SR_OK as well as in the case of
- *         parsing error.
+ *         error or upon no response.
  */
 SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
 			       const char *command, GArray **scpi_response)
@@ -913,6 +922,7 @@ SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
 	gchar **ptr, **tokens;
 	GArray *response_array;
 
+	*scpi_response = NULL;
 	response = NULL;
 	tokens = NULL;
 
@@ -939,7 +949,6 @@ SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
 
 	if (response_array->len == 0) {
 		g_array_free(response_array, TRUE);
-		*scpi_response = NULL;
 		return SR_ERR_DATA;
 	}
 
@@ -952,14 +961,15 @@ SR_PRIV int sr_scpi_get_uint8v(struct sr_scpi_dev_inst *scpi,
  * Send a SCPI command, read the reply, parse it as binary data with a
  * "definite length block" header and store the as an result in scpi_response.
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param command The SCPI command to send to the device (can be NULL).
- * @param scpi_response Pointer where to store the parsed result.
+ * Callers must free the allocated memory (unless it's NULL) regardless of
+ * the routine's return code. See @ref g_byte_array_free().
+ *
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[in] command The SCPI command to send to the device (can be NULL).
+ * @param[out] scpi_response Pointer where to store the parsed result.
  *
  * @return SR_OK upon successfully parsing all values, SR_ERR* upon a parsing
- *         error or upon no response. The allocated response must be freed by
- *         the caller in the case of an SR_OK as well as in the case of
- *         parsing error.
+ *         error or upon no response.
  */
 SR_PRIV int sr_scpi_get_block(struct sr_scpi_dev_inst *scpi,
 			       const char *command, GByteArray **scpi_response)
@@ -972,6 +982,8 @@ SR_PRIV int sr_scpi_get_block(struct sr_scpi_dev_inst *scpi,
 	long datalen;
 	gint64 timeout;
 
+	*scpi_response = NULL;
+
 	g_mutex_lock(&scpi->scpi_mutex);
 
 	if (command)
@@ -993,8 +1005,6 @@ SR_PRIV int sr_scpi_get_block(struct sr_scpi_dev_inst *scpi,
 
 	timeout = g_get_monotonic_time() + scpi->read_timeout_us;
 
-	*scpi_response = NULL;
-
 	/* Get (the first chunk of) the response. */
 	do {
 		ret = scpi_read_response(scpi, response, timeout);
@@ -1092,10 +1102,11 @@ SR_PRIV int sr_scpi_get_block(struct sr_scpi_dev_inst *scpi,
  * Send the *IDN? SCPI command, receive the reply, parse it and store the
  * reply as a sr_scpi_hw_info structure in the supplied scpi_response pointer.
  *
- * The hw_info structure must be freed by the caller via sr_scpi_hw_info_free().
+ * Callers must free the allocated memory regardless of the routine's
+ * return code. See @ref sr_scpi_hw_info_free().
  *
- * @param scpi Previously initialised SCPI device structure.
- * @param scpi_response Pointer where to store the hw_info structure.
+ * @param[in] scpi Previously initialised SCPI device structure.
+ * @param[out] scpi_response Pointer where to store the hw_info structure.
  *
  * @return SR_OK upon success, SR_ERR* on failure.
  */
@@ -1108,6 +1119,7 @@ SR_PRIV int sr_scpi_get_hw_id(struct sr_scpi_dev_inst *scpi,
 	struct sr_scpi_hw_info *hw_info;
 	gchar *idn_substr;
 
+	*scpi_response = NULL;
 	response = NULL;
 	tokens = NULL;