xml.c: make the different functions to get/set image properties more consistent
authorEric Biggers <ebiggers3@gmail.com>
Sat, 19 Dec 2015 22:32:23 +0000 (16:32 -0600)
committerEric Biggers <ebiggers3@gmail.com>
Sat, 19 Dec 2015 22:48:35 +0000 (16:48 -0600)
include/wimlib.h
src/xml.c

index 10f9bb7..6a6b0e8 100644 (file)
@@ -3133,19 +3133,8 @@ wimlib_get_error_string(enum wimlib_error_code code);
 /**
  * @ingroup G_wim_information
  *
- * Get the description of the specified image.
- *
- * @param wim
- *     Pointer to the ::WIMStruct to query.  This need not represent a
- *     standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- *     The 1-based index of the image for which to query the description.
- *
- * @return
- *     The description of the image, or @c NULL if there is no such image, or
- *     @c NULL if the specified image has no description.  The string may not
- *     remain valid after later library calls, so the caller should duplicate
- *     it if needed.
+ * Get the description of the specified image.  Equivalent to
+ * <tt>wimlib_get_image_property(wim, image, "DESCRIPTION")</tt>.
  */
 extern const wimlib_tchar *
 wimlib_get_image_description(const WIMStruct *wim, int image);
@@ -3153,18 +3142,10 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
 /**
  * @ingroup G_wim_information
  *
- * Get the name of the specified image.
- *
- * @param wim
- *     Pointer to the ::WIMStruct to query.  This need not represent a
- *     standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- *     The 1-based index of the image for which to query the name.
- *
- * @return
- *     The name of the image, or @c NULL if there is no such image, or an empty
- *     string if the image is unnamed.  The string may not remain valid after
- *     later library calls, so the caller should duplicate it if needed.
+ * Get the name of the specified image.  Equivalent to
+ * <tt>wimlib_get_image_property(wim, image, "NAME")</tt>, except that
+ * wimlib_get_image_name() will return an empty string if the image is unnamed
+ * whereas wimlib_get_image_property() may return @c NULL in that case.
  */
 extern const wimlib_tchar *
 wimlib_get_image_name(const WIMStruct *wim, int image);
@@ -3967,20 +3948,8 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path);
 /**
  * @ingroup G_modifying_wims
  *
- * Change the description of a WIM image.
- *
- * @param wim
- *     Pointer to the ::WIMStruct for the WIM.
- * @param image
- *     The 1-based index of the image for which to change the description.
- * @param description
- *     The new description to give the image.  It may be @c NULL, which
- *     indicates that the image is to be given no description.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- *     @p image does not exist in @p wim.
+ * Change the description of a WIM image.  Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "DESCRIPTION", description)</tt>.
  */
 extern int
 wimlib_set_image_descripton(WIMStruct *wim, int image,
@@ -3990,20 +3959,8 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
  * @ingroup G_modifying_wims
  *
  * Change what is stored in the \<FLAGS\> element in the WIM XML document
- * (usually something like "Core" or "Ultimate")
- *
- * @param wim
- *     Pointer to the ::WIMStruct for the WIM.
- * @param image
- *     The 1-based index of the image for which to change the flags.
- * @param flags
- *     The new \<FLAGS\> element to give the image.  It may be @c NULL, which
- *     indicates that the image is to be given no \<FLAGS\> element.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- *     @p image does not exist in @p wim.
+ * (usually something like "Core" or "Ultimate").  Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "FLAGS", flags)</tt>.
  */
 extern int
 wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
@@ -4011,23 +3968,8 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
 /**
  * @ingroup G_modifying_wims
  *
- * Change the name of a WIM image.
- *
- * @param wim
- *     Pointer to the ::WIMStruct for the WIM.
- * @param image
- *     The 1-based index of the image for which to change the name.
- * @param name
- *     New name to give the new image.  If @c NULL or empty, the new image is
- *     given no name.  Otherwise, it must specify a name that does not already
- *     exist in @p wim.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
- *     The WIM already contains an image with the requested name.
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- *     @p image does not exist in @p wim.
+ * Change the name of a WIM image.  Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "NAME", name)</tt>.
  */
 extern int
 wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
@@ -4060,6 +4002,9 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
  *
  * @return 0 on success; a ::wimlib_error_code value on failure.
  *
+ * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
+ *     The user requested to set the image name (the <tt>NAME</tt> property),
+ *     but another image in the WIM already had the requested name.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  *     @p image does not exist in @p wim.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
index d464706..20c9abd 100644 (file)
--- a/src/xml.c
+++ b/src/xml.c
@@ -512,37 +512,6 @@ xml_set_ttext_by_path(xmlNode *root, const xmlChar *path, const tchar *ttext)
        }
 }
 
-/* Sets a string property for the specified WIM image.  */
-static int
-set_image_property(WIMStruct *wim, int image, const xmlChar *name,
-                  const tchar *value)
-{
-       struct wim_xml_info *info = wim->xml_info;
-
-       if (image < 1 || image > info->image_count)
-               return WIMLIB_ERR_INVALID_IMAGE;
-
-       return xml_set_ttext_by_path(info->images[image - 1], name, value);
-}
-
-/* Gets a string property for the specified WIM image as a 'tchar' string.
- * Returns a pointer to the property value if found; NULL if the image doesn't
- * exist; or 'default_value' if the property doesn't exist in the image or if
- * the property value could not be translated to a 'tchar' string.  */
-static const tchar *
-get_image_property(const WIMStruct *wim, int image, const xmlChar *name,
-                  const tchar *default_value)
-{
-       struct wim_xml_info *info = wim->xml_info;
-       const tchar *value;
-
-       if (image < 1 || image > info->image_count)
-               return NULL;
-
-       value = xml_get_ttext_by_path(info, info->images[image - 1], name);
-       return value ? value : default_value;
-}
-
 /* Unlink and return the node which represents the INDEX attribute of the
  * specified IMAGE element.  */
 static xmlAttr *
@@ -1419,13 +1388,19 @@ wimlib_image_name_in_use(const WIMStruct *wim, const tchar *name)
 WIMLIBAPI const tchar *
 wimlib_get_image_name(const WIMStruct *wim, int image)
 {
-       return get_image_property(wim, image, "NAME", T(""));
+       const struct wim_xml_info *info = wim->xml_info;
+       const tchar *name;
+
+       if (image < 1 || image > info->image_count)
+               return NULL;
+       name = wimlib_get_image_property(wim, image, T("NAME"));
+       return name ? name : T("");
 }
 
 WIMLIBAPI const tchar *
 wimlib_get_image_description(const WIMStruct *wim, int image)
 {
-       return get_image_property(wim, image, "DESCRIPTION", NULL);
+       return wimlib_get_image_property(wim, image, T("DESCRIPTION"));
 }
 
 WIMLIBAPI const tchar *
@@ -1434,12 +1409,15 @@ wimlib_get_image_property(const WIMStruct *wim, int image,
 {
        const xmlChar *name;
        const tchar *value;
+       struct wim_xml_info *info = wim->xml_info;
 
        if (!property_name || !*property_name)
                return NULL;
+       if (image < 1 || image > info->image_count)
+               return NULL;
        if (tstr_get_utf8(property_name, &name))
                return NULL;
-       value = get_image_property(wim, image, name, NULL);
+       value = xml_get_ttext_by_path(info, info->images[image - 1], name);
        tstr_put_utf8(name);
        return value;
 }
@@ -1447,22 +1425,19 @@ wimlib_get_image_property(const WIMStruct *wim, int image,
 WIMLIBAPI int
 wimlib_set_image_name(WIMStruct *wim, int image, const tchar *name)
 {
-       if (image_name_in_use(wim, name, image))
-               return WIMLIB_ERR_IMAGE_NAME_COLLISION;
-
-       return set_image_property(wim, image, "NAME", name);
+       return wimlib_set_image_property(wim, image, T("NAME"), name);
 }
 
 WIMLIBAPI int
 wimlib_set_image_descripton(WIMStruct *wim, int image, const tchar *description)
 {
-       return set_image_property(wim, image, "DESCRIPTION", description);
+       return wimlib_set_image_property(wim, image, T("DESCRIPTION"), description);
 }
 
 WIMLIBAPI int
 wimlib_set_image_flags(WIMStruct *wim, int image, const tchar *flags)
 {
-       return set_image_property(wim, image, "FLAGS", flags);
+       return wimlib_set_image_property(wim, image, T("FLAGS"), flags);
 }
 
 WIMLIBAPI int
@@ -1470,15 +1445,23 @@ wimlib_set_image_property(WIMStruct *wim, int image, const tchar *property_name,
                          const tchar *property_value)
 {
        const xmlChar *name;
+       struct wim_xml_info *info = wim->xml_info;
        int ret;
 
        if (!property_name || !*property_name)
                return WIMLIB_ERR_INVALID_PARAM;
 
+       if (image < 1 || image > info->image_count)
+               return WIMLIB_ERR_INVALID_IMAGE;
+
+       if (!tstrcmp(property_name, T("NAME")) &&
+           image_name_in_use(wim, property_value, image))
+               return WIMLIB_ERR_IMAGE_NAME_COLLISION;
+
        ret = tstr_get_utf8(property_name, &name);
        if (ret)
                return ret;
-       ret = set_image_property(wim, image, name, property_value);
+       ret = xml_set_ttext_by_path(info->images[image - 1], name, property_value);
        tstr_put_utf8(name);
        return ret;
 }