CGMutableImageMetadata

Struct CGMutableImageMetadata 

Source
#[repr(C)]
pub struct CGMutableImageMetadata { /* private fields */ }
Available on crate feature 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

Source

pub unsafe fn new() -> CFRetained<CGMutableImageMetadata>

Creates an empty CGMutableImageMetadataRef

Source

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

Source

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.

Source

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.

Source

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")
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).

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.

Source

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

Source

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>§

Source

pub unsafe fn tags(self: &CGImageMetadata) -> Option<CFRetained<CFArray>>

*!

Obtain an array of tags from a CGImageMetadataRef

Returns: Returns an array with a shallow copy of all top-level CGImageMetadataTagRefs in a CGImageMetadataRef.

Source

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.

Source

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.

Source

pub unsafe fn enumerate_tags_using_block( self: &CGImageMetadata, root_path: Option<&CFString>, options: Option<&CFDictionary>, block: CGImageMetadataTagBlock, )

Available on crate feature 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.

Source

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.

Source

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>§

Source

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.

Source

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 CFNumbers, small CFStrings 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

Source§

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl AsRef<CFType> for CGMutableImageMetadata

Source§

fn as_ref(&self) -> &CFType

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl AsRef<CGImageMetadata> for CGMutableImageMetadata

Source§

fn as_ref(&self) -> &CGImageMetadata

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl AsRef<CGMutableImageMetadata> for CGMutableImageMetadata

Source§

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.
Source§

impl Borrow<AnyObject> for CGMutableImageMetadata

Source§

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value. Read more
Source§

impl Borrow<CFType> for CGMutableImageMetadata

Source§

fn borrow(&self) -> &CFType

Immutably borrows from an owned value. Read more
Source§

impl Borrow<CGImageMetadata> for CGMutableImageMetadata

Source§

fn borrow(&self) -> &CGImageMetadata

Immutably borrows from an owned value. Read more
Source§

impl Debug for CGMutableImageMetadata

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Deref for CGMutableImageMetadata

Source§

type Target = CGImageMetadata

The resulting type after dereferencing.
Source§

fn deref(&self) -> &Self::Target

Dereferences the value.
Source§

impl Hash for CGMutableImageMetadata

Source§

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
Source§

impl Message for CGMutableImageMetadata

Source§

fn retain(&self) -> Retained<Self>
where Self: Sized,

Increment the reference count of the receiver. Read more
Source§

impl PartialEq for CGMutableImageMetadata

Source§

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl RefEncode for CGMutableImageMetadata

Source§

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type. Read more
Source§

impl Type for CGMutableImageMetadata

Source§

fn retain(&self) -> CFRetained<Self>
where Self: Sized,

Increment the reference count of the receiver. Read more
Source§

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant
Helper for easier transition from the core-foundation crate.
Source§

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>
where Self: Sized,

👎Deprecated: use CFRetained::retain
Helper for easier transition from the core-foundation crate. Read more
Source§

fn as_CFTypeRef(&self) -> &CFType
where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)
Helper for easier transition from the core-foundation crate.
Source§

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>
where Self: Sized,

👎Deprecated: use CFRetained::from_raw
Helper for easier transition from the core-foundation crate. Read more
Source§

impl Eq for CGMutableImageMetadata

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> AutoreleaseSafe for T
where T: ?Sized,