Struct CGImageMetadata

Source

#[repr(C)]
pub struct CGImageMetadata { /* private fields */ }

Available on crate feature CGImageMetadata only.

Expand description

an immutable container for CGImageMetadataTags

Implementations§

Source §

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

impl CGImageMetadata

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 §

impl CGImageMetadata

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 §

impl CGImageMetadata

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.

Source

pub unsafe fn from_xmp_data( data: &CFData, ) -> Option<CFRetained<CGImageMetadata>>

Creates a collection of CGImageMetadataTags from a block of XMP data

Converts XMP data into a collection of metadata tags. The data must be a complete XMP tree. XMP packet headers ( < ?xpacket .. ?>) are supported.

Parameter data: The XMP data.

Returns: Returns a collection of CGImageMetadata tags. 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.