Synopsis

ImageProfileIterator AllocateImageProfileIterator( const Image *image );

Description

AllocateImageProfileIterator allocates an iterator to traverse the image profile list. It is an error (i.e. will surely crash) to invoke DeleteImageProfile() on the profile that the iterator is currently referencing. However, it is safe to delete a profile that the iterator is not currently referencing. Inserting additional profiles does not invalidate the current iterator.

The format of the AllocateImageProfileIterator method is:

ImageProfileIterator AllocateImageProfileIterator( const Image *image );

A description of each parameter follows:

image:

The image.

Synopsis

MaickPassFail AppendImageProfile( Image *image, const char *name,
                                  const unsigned char *profile_chunk,
                                  const size_t chunk_length );

Description

AppendImageProfile adds a named profile to the image. If a profile with the same name already exists, then the new profile data is appended to the existing profile. If a null profile address is supplied, then an existing profile is removed. The profile is copied into the image. Note that this function does not execute CMS color profiles. Any existing CMS color profile is simply added/updated. Use the ProfileImage() function in order to execute a CMS color profile.

The format of the AppendImageProfile method is:

MaickPassFail AppendImageProfile( Image *image, const char *name,
                                  const unsigned char *profile_chunk,
                                  const size_t chunk_length );

image:

The image.

name:

Profile name. Valid names are "8BIM", "ICM", "IPTC", XMP, or any unique text string.

profile_chunk:

Address of profile chunk to add or append. Pass zero to remove an existing profile.

length:

The length of the profile chunk to add or append.

Synopsis

void DeallocateImageProfileIterator( ImageProfileIterator profile_iterator );

Description

DeallocateImageProfileIterator deallocates an image profile iterator.

The format of the DeallocateImageProfileIterator method is:

void DeallocateImageProfileIterator( ImageProfileIterator profile_iterator );

A description of each parameter follows:

profile_iterator:

Profile iterator to deallocate.

Synopsis

unsigned int DeleteImageProfile( Image *image, const char *name );

Description

DeleteImageProfile removes a named profile from the image.

The format of the DeleteImageProfile method is:

unsigned int DeleteImageProfile( Image *image, const char *name );

A description of each parameter follows:

image:

The image.

name:

Profile name. Valid names are "8BIM", "ICM", & "IPTC" or a generic profile name.

Synopsis

const unsigned char *GetImageProfile( const Image *image, const char *name,
                                      size_t *length );

Description

GetImageProfile returns a pointer to the named image profile if it is present. A null pointer is returned if the named profile is not present.

Older versions of this function stored profiles named "8BIM" and "IPTC" in the same storage location. This is no longer the case. However, GetImageProfile() will try the alternate name if the specifically requested profile name is not available.

The format of the GetImageProfile method is:

const unsigned char *GetImageProfile( const Image *image, const char *name,
                                      size_t *length );

image:

The image.

name:

Profile name. Valid names are "8BIM", "EXIF", "ICM", "IPTC", "XMP" or any unique text string.

length:

Updated with profile length if profile is present. Set to NULL if length is not needed.

Synopsis

MagickPassFail NextImageProfile( ImageProfileIterator profile_iterator, const char ** name,
                                 const unsigned char ** profile, size_t *length );

Description

NextImageProfile iterates forward to the next image profile. The profile name is returned along with the profile data, and length. If there are no more entries in the list, then MagickFail is returned.

The format of the AllocateImageProfileIterator method is:

MagickPassFail NextImageProfile( ImageProfileIterator profile_iterator, const char ** name,
                                 const unsigned char ** profile, size_t *length );

profile_iterator:

Profile iterator.

name:

Address of pointer to update with address of name.

profile:

Address of pointer to update with location of profile data.

length:

Address of parameter to update with profile length.

Synopsis

unsigned int ProfileImage( Image *image, const char *name, unsigned char *profile,
                           const size_t length, unsigned int clone );

Description

ProfileImage() adds, applies, or removes a ICM, IPTC, or generic profile from an image. If the profile is NULL, it is removed from the image otherwise added (or applied). Use a name of '*' and a profile of NULL to remove all profiles from the image. Ownership of the profile is transferred to GraphicsMagick (it should not be altered or deallocated) unless the clone option is set to True.

ICC ICM profiles are a special case and are handled as follows:

If there is no ICM profile currently associated with the image, then the profile is simply associated with the image and the image pixels are not altered.

If there is already a ICM profile associated with the image, then the colorspace transform described by the existing and new profiles is applied to the image pixels, and the new profile is associated with the image.

The format of the ProfileImage method is:

unsigned int ProfileImage( Image *image, const char *name, unsigned char *profile,
                           const size_t length, unsigned int clone );

image:

The image.

name:

Name of profile to add or remove: ICM, IPTC, or generic profile.

profile:

The profile. Can not be 'const' due to 'clone' option but is treated as 'const' if 'clone' is set to MagickTrue.

length:

The length of the profile.

clone:

If set True, then copy the profile rather than taking ownership of it.

Synopsis

unsigned int SetImageProfile( Image *image, const char *name, const unsigned char *profile,
                              const size_t length );

Description

SetImageProfile adds a named profile to the image. If a profile with the same name already exists, then it is replaced. If a null profile address is supplied, then an existing profile is removed. The profile is copied into the image. Note that this function does not execute CMS color profiles. Any existing CMS color profile is simply replaced. Use the ProfileImage() function in order to execute a CMS color profile.

Older versions of this function stored profiles named "8BIM" and "IPTC" in the same storage location. This is no longer the case. However, GetImageProfile() will try the alternate name if the specifically requested profile name is not available. Note that when trying to remove a profile, it may be necessary to remove both names in order for an "IPTC" profile to no longer be included in output file formats.

The format of the SetImageProfile method is:

unsigned int SetImageProfile( Image *image, const char *name, const unsigned char *profile,
                              const size_t length );

image:

The image.

name:

Profile name. Valid names are "8BIM", EXIF, "ICM", "IPTC", XMP, or any unique text string.

profile:

Address of profile to add. Pass zero to remove an existing profile.

length:

The length of the profile.