/**
* @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);
/**
* @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);
/**
* @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,
* @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);
/**
* @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);
*
* @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
}
}
-/* 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 *
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 *
{
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;
}
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
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;
}