#[repr(C)]pub struct CGMutableImageMetadata { /* private fields */ }
CGImageMetadata
only.Expand description
a mutable container for CGImageMetadataTags
A CGMutableImageMetadataRef can be used in any function that accepts a CGImageMetadataRef.
See also Apple’s documentation
Implementations§
Source§impl CGMutableImageMetadata
impl CGMutableImageMetadata
Sourcepub unsafe fn new() -> CFRetained<CGMutableImageMetadata>
pub unsafe fn new() -> CFRetained<CGMutableImageMetadata>
Creates an empty CGMutableImageMetadataRef
Sourcepub unsafe fn new_copy(
metadata: &CGImageMetadata,
) -> Option<CFRetained<CGMutableImageMetadata>>
pub unsafe fn new_copy( metadata: &CGImageMetadata, ) -> Option<CFRetained<CGMutableImageMetadata>>
Creates a deep mutable copy of another CGImageMetadataRef
Before modifying an immutable CGImageMetadataRef (such as metadata from CGImageSourceCopyMetadataAtIndex) you must first make a copy. This function makes a deep copy of all CGImageMetadataTags and their values.
Source§impl CGMutableImageMetadata
impl CGMutableImageMetadata
Sourcepub unsafe fn register_namespace_for_prefix(
self: &CGMutableImageMetadata,
xmlns: &CFString,
prefix: &CFString,
err: *mut *mut CFError,
) -> bool
pub unsafe fn register_namespace_for_prefix( self: &CGMutableImageMetadata, xmlns: &CFString, prefix: &CFString, err: *mut *mut CFError, ) -> bool
*!
Associates an XMP namespace URI with a prefix string.
This allows ImageIO to create custom metadata when it encounters an unrecognized prefix in a path (see CGImageMetadataCopyTagWithPath for more information about path syntax). A namespace must be registered before it can be used to add custom metadata. All namespaces found in the image’s metadata, or defined as a constant above, will be pre-registered. Namespaces and prefixes must be unique.
Returns: Returns true if successful. Returns false and sets ‘err’ if an error or conflict occurs.
Sourcepub unsafe fn set_tag_with_path(
self: &CGMutableImageMetadata,
parent: Option<&CGImageMetadataTag>,
path: &CFString,
tag: &CGImageMetadataTag,
) -> bool
pub unsafe fn set_tag_with_path( self: &CGMutableImageMetadata, parent: Option<&CGImageMetadataTag>, path: &CFString, tag: &CGImageMetadataTag, ) -> bool
Sets the tag at a specific path in a CGMutableImageMetadata container or a parent tag
This is the primary function for adding new metadata tags to a metadata container, or updating existing tags. All tags required to reach the final tag (at the end of the path) will be created, if needed. Tags will created with default types (ordered arrays). Creating tags will fail if a prefix is encountered that has not been registered. Use
CGImageMetadataRegisterNamespaceForPrefix
to associate a prefix with a namespace prior to using a path-based CGImageMetadata function. Note that if a parent tag is provided, the children of that tag reference will be modified, which may be a different reference from the tag stored in the metadata container. Since tags are normally obtained as a copy, it is typically neccesary to use CGImageMetadataSetTagWithPath to commit the changed parent object back to the metadata container (using the parent’s path and NULL for the parent).
Parameter metadata
: A mutable collection of metadata tags.
Use
CGImageMetadataCreateMutableCopy
or
CGImageMetadataCreateMutable
to obtain a mutable metadata container.
Parameter parent
: A parent tag. If NULL, the path is relative to the root of the
CGImageMetadataRef (i.e. it is not a child of another property).
Note that if a parent tag is provided,
the children of that tag reference will be modified, which may be a different
reference from the tag stored in the metadata container. Since tags are normally
obtained as a copy, it is typically neccesary to use CGImageMetadataSetTagWithPath
to commit the changed parent object back to the metadata container (using
the parent’s path and NULL for the parent).
Parameter path
: A string with the path to the desired tag. Please consult
the documentation of
CGImageMetadataCopyTagWithPath
for information about path syntax.
Parameter tag
: The CGImageMetadataTag to be added to the metadata. The tag
will be retained.
Returns: Returns true if successful, false otherwise.
Sourcepub unsafe fn set_value_with_path(
self: &CGMutableImageMetadata,
parent: Option<&CGImageMetadataTag>,
path: &CFString,
value: &CFType,
) -> bool
pub unsafe fn set_value_with_path( self: &CGMutableImageMetadata, parent: Option<&CGImageMetadataTag>, path: &CFString, value: &CFType, ) -> bool
Sets the value of the tag at a specific path in a CGMutableImageMetadataRef container or a parent tag
This function is used to add new metadata values to a metadata container, or update existing tag values. All tags required to reach the final tag (at the end of the path) are created, if needed. Tags are created with default types (i.e. arrays will be ordered). Creating tags will fail if a prefix is encountered that has not been registered. Use
CGImageMetadataRegisterNamespaceForPrefix
to associate a prefix with a namespace prior to using a path-based CGImageMetadata function.
Examples
- 'path' = CFSTR("xmp:CreateDate"), 'value' = CFSTR("2011-09-20T14:54:47-08:00")
- 'path' = CFSTR("dc:subject[0]"), 'value' = CFSTR("San Francisco")
- 'path' = CFSTR("dc:subject[1]"), 'value' = CFSTR("Golden Gate Bridge")
- 'path' = CFSTR("dc:description[en]") 'value' = CFSTR("my image description")
- 'path' = CFSTR("dc:description[de]") 'value' = CFSTR("meine bildbeschreibung")
Parameter metadata
: A mutable collection of metadata tags.
Use
CGImageMetadataCreateMutableCopy
or
CGImageMetadataCreateMutable
to obtain a mutable metadata container.
Parameter parent
: A parent tag. If NULL, the path is relative to the root of the
CGImageMetadataRef (i.e. it is not a child of another property).
Parameter path
: A string with the path to the desired tag. Please consult
the documentation of
CGImageMetadataCopyTagWithPath
for information about path syntax.
Parameter value
: The value to be added to the CGImageMetadataTag matching the path.
The tag will be retained. The restrictions for the value are the same as in
CGImageMetadataTagCreate
.
Returns: Returns true if successful, false otherwise.
Sourcepub unsafe fn remove_tag_with_path(
self: &CGMutableImageMetadata,
parent: Option<&CGImageMetadataTag>,
path: &CFString,
) -> bool
pub unsafe fn remove_tag_with_path( self: &CGMutableImageMetadata, parent: Option<&CGImageMetadataTag>, path: &CFString, ) -> bool
Removes the tag at a specific path from a CGMutableImageMetadata container or from the parent tag
Use this function to delete a metadata tag matching a specific path from a mutable metadata container. Note that if a parent tag is provided, the children of that tag reference will be modified, which may be a different reference from the tag stored in the metadata container. Since tags are normally obtained as a copy, it is typically neccesary to use CGImageMetadataSetTagWithPath to commit the changed parent object back to the metadata container (using the parent’s path and NULL for the parent).
Parameter parent
: A parent tag. If NULL, the path is relative to the root of the
CGImageMetadataRef (i.e. it is not a child of another property).
Parameter path
: A string with the path to the desired tag. Please consult
the documentation of
CGImageMetadataCopyTagWithPath
for information about path syntax.
Source§impl CGMutableImageMetadata
impl CGMutableImageMetadata
Sourcepub unsafe fn set_value_matching_image_property(
self: &CGMutableImageMetadata,
dictionary_name: &CFString,
property_name: &CFString,
value: &CFType,
) -> bool
pub unsafe fn set_value_matching_image_property( self: &CGMutableImageMetadata, dictionary_name: &CFString, property_name: &CFString, value: &CFType, ) -> bool
Sets the value of the CGImageMetadataTag matching a kCGImageProperty constant
Provides a bridge for values from CGImageCopyPropertiesAtIndex, simplifying changing property values defined in EXIF and IPTC standards, which have no notion of namespaces, prefixes, or XMP property types. Metadata Working Group guidance is factored into the mapping of CGImageProperties to XMP compatible CGImageMetadataTags. For example, setting kCGImagePropertyExifDateTimeOriginal will set the value of the corresponding XMP tag, which is photoshop:DateCreated. Note that property values should still be in their XMP forms, such as “YYYY-MM-DDThh:mm:ss” for DateTime, rather than the EXIF or IPTC DateTime formats. Although this function will allow the caller to set custom values for these properties, you should consult the appropriate specifications for details about property value formats for EXIF and IPTC tags in XMP.
Parameter metadata
: A mutable collection of metadata tags
Parameter dictionaryName
: the metadata subdictionary to which the image property belongs,
such as kCGImagePropertyExifDictionary or kCGImagePropertyIPTCDictionary. Not all
dictionaries and properties are supported at this time.
Parameter propertyName
: the name of the property. This must be a defined property constant
corresponding to the ‘dictionaryName’. For example, kCGImagePropertyTIFFOrientation,
kCGImagePropertyExifDateTimeOriginal, or kCGImagePropertyIPTCKeywords. A warning
will be logged if the CGImageProperty is unsupported by CGImageMetadata.
Parameter value
: A CFTypeRef with the value for the tag. The same value restrictions apply
as in
CGImageMetadataTagCreate
.
Returns: Returns true if successful, false otherwise.
Methods from Deref<Target = CGImageMetadata>§
*!
Obtain an array of tags from a CGImageMetadataRef
Returns: Returns an array with a shallow copy of all top-level CGImageMetadataTagRefs in a CGImageMetadataRef.
Sourcepub unsafe fn tag_with_path(
self: &CGImageMetadata,
parent: Option<&CGImageMetadataTag>,
path: &CFString,
) -> Option<CFRetained<CGImageMetadataTag>>
pub unsafe fn tag_with_path( self: &CGImageMetadata, parent: Option<&CGImageMetadataTag>, path: &CFString, ) -> Option<CFRetained<CGImageMetadataTag>>
Searches for a specific CGImageMetadataTag in a CGImageMetadataRef
This is the primary function for clients to obtain specific metadata properties from an image. The ‘path’ mechanism provides a way to access both simple top-level properties, such as Date & Time, or complex deeply-nested properties with ease.
Parameter metadata
: A collection of metadata tags.
Parameter parent
: A parent tag. If NULL, the path is relative to the root of the
CGImageMetadataRef (i.e. it is not a child of another property). If the parent
is provided, the effective path will be the concatenation of the parent’s path
and the ‘path’ parameter. This is useful for accessing array elements or
structure fields inside nested tags.
Parameter path
: A string representing a path to the desired tag. Paths consist of
a tag prefix (i.e. “exif”) joined with a tag name (i.e. “Flash”) by a colon
(“:”), such as CFSTR(“exif:Flash”).
Elements of ordered and unordered arrays are accessed via 0-based indices inside square [] brackets.
Elements of alternate-text arrays are accessed by an RFC 3066 language code inside square [] brackets.
Fields of a structure are delimited by a period, ‘.’.
Qualifiers are delimited by the ‘?’ character. Only tags with string values (kCGImageMetadataTypeString)
are allowed to have qualifiers - arrays and structures may not contain qualifiers.
If parent is NULL, a prefix must be specified for the first tag. Prefixes for all subsequent tags are optional. If unspecified, the prefix is inherented from the nearest parent tag with a prefix. Custom prefixes must be registered using
CGImageMetadataRegisterNamespaceForPrefix
prior to use in any path-based functions.
Examples:
- 'path' = CFSTR("xmp:CreateDate")
- 'path' = CFSTR("exif:Flash.Fired")
- 'parent' = tag at path CFSTR("exif:Flash"), path = CFSTR("exif:Fired") (equivilent to previous)
- 'path' = CFSTR("exif:Flash.RedEyeMode")
- 'path' = CFSTR("dc:title")
- 'path' = CFSTR("dc:subject")
- 'path' = CFSTR("dc:subject[2]")
- 'parent' = tag at path CFSTR("dc:subject"), path = CFSTR("[2]") (equivilent to previous)
- 'path' = CFSTR("dc:description[x-default])"
- 'path' = CFSTR("dc.description[de])"
- 'path' = CFSTR("dc.description[fr])"
- 'path' = CFSTR("foo:product)"
- 'path' = CFSTR("foo:product?bar:manufacturer)"
Returns: Returns a copy of CGImageMetadataTag matching ‘path’, or NULL if no match is found. The copy of the tag’s value is shallow. Tags copied from an immutable CGImageMetadataRef are also immutable. Because this function returns a copy of the tag’s value, any modification of the tag’s value must be followed by a CGImageMetadataSetTagWithPath to commit the change to the metadata container.
Sourcepub unsafe fn string_value_with_path(
self: &CGImageMetadata,
parent: Option<&CGImageMetadataTag>,
path: &CFString,
) -> Option<CFRetained<CFString>>
pub unsafe fn string_value_with_path( self: &CGImageMetadata, parent: Option<&CGImageMetadataTag>, path: &CFString, ) -> Option<CFRetained<CFString>>
Searches for a specific tag in a CGImageMetadataRef and returns its string value.
This is a convenience method for searching for a tag at path and extracting the string value.
Parameter metadata
: A collection of metadata tags.
Parameter parent
: A parent tag. If NULL, the path is relative to the root of the
CGImageMetadataRef (i.e. it is not a child of another property).
Parameter path
: A string with the path to the desired tag. Please consult
the documentation of
CGImageMetadataCopyTagWithPath
for information about path syntax.
Returns: Returns a string from a CGImageMetadataTag located at ‘path’. The tag must be of type kCGImageMetadataTypeString or kCGImageMetadataTypeAlternateText. For AlternateText tags, the element with the “x-default” language qualifier will be returned. For other types, NULL will be returned.
Available on crate feature block2
only.
block2
only.Executes a given block using each tag in the metadata
This function iterates over all of the tags in a CGImageMetadataRef, executing the block for each tag. The default behavior iterates over all top-level tags in the metadata. The path of the tag and the tag itself is passed to the block. The metadata cannot be modified inside the block - consider adding the tags of interest into another collection.
Parameter metadata
: A collection of metadata tags.
Parameter rootPath
: Iteration will occur for all children of the tag matching
the root path. Please refer to CGImageMetadataCopyTagWithPath for information
about path syntax. If NULL or an empty string, the block will be executed
for all top-level tags in the metadata container.
Parameter options
: A dictionary of options for iterating through the tags.
Currently the only supported option is kCGImageMetadataEnumerateRecursively,
which should be set to a CFBoolean.
Parameter block
: The block that is executed for each tag in metadata.
Sourcepub unsafe fn tag_matching_image_property(
self: &CGImageMetadata,
dictionary_name: &CFString,
property_name: &CFString,
) -> Option<CFRetained<CGImageMetadataTag>>
pub unsafe fn tag_matching_image_property( self: &CGImageMetadata, dictionary_name: &CFString, property_name: &CFString, ) -> Option<CFRetained<CGImageMetadataTag>>
*!
Searches for a specific CGImageMetadataTag matching a kCGImageProperty constant
Provides a bridge for values from CGImageCopyPropertiesAtIndex, simplifying access for properties defined in EXIF and IPTC standards, which have no notion of namespaces, prefixes, or XMP property types. Metadata Working Group guidance is factored into the mapping of CGImageProperties to XMP compatible CGImageMetadataTags. For example, kCGImagePropertyExifDateTimeOriginal will get the value of the corresponding XMP tag, which is photoshop:DateCreated. Note that property values will still be in their XMP forms, such as “YYYY-MM-DDThh:mm:ss” for DateTime, rather than the EXIF or IPTC DateTime formats.
Parameter metadata
: A collection of metadata tags
Parameter dictionaryName
: the metadata subdictionary to which the image property belongs,
such as kCGImagePropertyExifDictionary or kCGImagePropertyIPTCDictionary. Not all
dictionaries and properties are supported at this time.
Parameter propertyName
: the name of the property. This must be a defined property constant
corresponding to the ‘dictionaryName’. For example, kCGImagePropertyTIFFOrientation,
kCGImagePropertyExifDateTimeOriginal, or kCGImagePropertyIPTCKeywords. A warning
will be logged if the CGImageProperty is unsupported by CGImageMetadata.
Returns: Returns a CGImageMetadataTagRef with the appropriate namespace, prefix, tag name, and XMP value for the corresponding CGImageProperty. Returns NULL if the property could not be found.
Sourcepub unsafe fn xmp_data(
self: &CGImageMetadata,
options: Option<&CFDictionary>,
) -> Option<CFRetained<CFData>>
pub unsafe fn xmp_data( self: &CGImageMetadata, options: Option<&CFDictionary>, ) -> Option<CFRetained<CFData>>
Serializes the CGImageMetadataRef to XMP data
This converts all of the metadata tags to a block of XMP data. Common uses include creating sidecar files that contain metadata for image formats that do not support embedded XMP, or cannot be edited due to other format restrictions (such as proprietary RAW camera formats).
Parameter metadata
: A collection of metadata tags.
Parameter options
: should be NULL. Options are currently not used, but may be used in
future release.
Returns: Returns a CFData containing an XMP representation of the metadata. Returns NULL if an error occurred.
Methods from Deref<Target = CFType>§
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: ConcreteType,
pub fn downcast_ref<T>(&self) -> Option<&T>where
T: ConcreteType,
Attempt to downcast the type to that of type T
.
This is the reference-variant. Use CFRetained::downcast
if you
want to convert a retained type. See also ConcreteType
for more
details on which types support being converted to.
Sourcepub fn retain_count(&self) -> usize
pub fn retain_count(&self) -> usize
Get the reference count of the object.
This function may be useful for debugging. You normally do not use this function otherwise.
Beware that some things (like CFNumber
s, small CFString
s etc.) may
not have a normal retain count for optimization purposes, and can
return usize::MAX
in that case.
Trait Implementations§
Source§impl AsRef<AnyObject> for CGMutableImageMetadata
impl AsRef<AnyObject> for CGMutableImageMetadata
Source§impl AsRef<CFType> for CGMutableImageMetadata
impl AsRef<CFType> for CGMutableImageMetadata
Source§impl AsRef<CGImageMetadata> for CGMutableImageMetadata
impl AsRef<CGImageMetadata> for CGMutableImageMetadata
Source§fn as_ref(&self) -> &CGImageMetadata
fn as_ref(&self) -> &CGImageMetadata
Source§impl Borrow<AnyObject> for CGMutableImageMetadata
impl Borrow<AnyObject> for CGMutableImageMetadata
Source§impl Borrow<CFType> for CGMutableImageMetadata
impl Borrow<CFType> for CGMutableImageMetadata
Source§impl Borrow<CGImageMetadata> for CGMutableImageMetadata
impl Borrow<CGImageMetadata> for CGMutableImageMetadata
Source§fn borrow(&self) -> &CGImageMetadata
fn borrow(&self) -> &CGImageMetadata
Source§impl Debug for CGMutableImageMetadata
impl Debug for CGMutableImageMetadata
Source§impl Deref for CGMutableImageMetadata
impl Deref for CGMutableImageMetadata
Source§impl Hash for CGMutableImageMetadata
impl Hash for CGMutableImageMetadata
Source§impl Message for CGMutableImageMetadata
impl Message for CGMutableImageMetadata
Source§impl PartialEq for CGMutableImageMetadata
impl PartialEq for CGMutableImageMetadata
Source§impl RefEncode for CGMutableImageMetadata
impl RefEncode for CGMutableImageMetadata
Source§const ENCODING_REF: Encoding
const ENCODING_REF: Encoding
Source§impl Type for CGMutableImageMetadata
impl Type for CGMutableImageMetadata
Source§fn retain(&self) -> CFRetained<Self>where
Self: Sized,
fn retain(&self) -> CFRetained<Self>where
Self: Sized,
Source§fn as_concrete_TypeRef(&self) -> &Self
fn as_concrete_TypeRef(&self) -> &Self
core-foundation
crate.Source§unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>where
Self: Sized,
unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>where
Self: Sized,
core-foundation
crate. Read moreSource§fn as_CFTypeRef(&self) -> &CFType
fn as_CFTypeRef(&self) -> &CFType
core-foundation
crate.Source§unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>where
Self: Sized,
unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>where
Self: Sized,
core-foundation
crate. Read more