156 lines
5.6 KiB
C
156 lines
5.6 KiB
C
//
|
|
// ProResMetadataWriter.h
|
|
// Copyright (c) 2017 Apple. All rights reserved.
|
|
//
|
|
|
|
#ifndef PRORESMETADATAWRITER_H
|
|
#define PRORESMETADATAWRITER_H 1
|
|
|
|
#include "ProResTypes.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#pragma pack(push, 4)
|
|
|
|
/*!
|
|
@enum ProResMetadataWriter Errors
|
|
@discussion PRStatus errors returned from the ProResMetadataWriter APIs
|
|
|
|
@constant kProResMetadataWriterError_RequiredParameterMissing
|
|
Returned if a required parameter is missing.
|
|
@constant kProResMetadataWriterError_InvalidParameter
|
|
Returned if any of the parameters is invalid.
|
|
@constant kProResMetadataWriterError_AllocationFailed
|
|
Returned if memory allocation failed.
|
|
@constant kProResMetadataWriterError_UnsupportedCommonKey
|
|
Returned if the common key is invalid.
|
|
@constant kProResMetadataWriterError_ItemAlreadyPresent
|
|
Returned if the item is already present.
|
|
@constant kProResMetadataWriterError_NoSuchProperty
|
|
Returned if the property is not supported.
|
|
@constant kProResMetadataWriterError_BadData
|
|
Returned if the container contains bad data.
|
|
*/
|
|
enum {
|
|
kProResMetadataWriterError_RequiredParameterMissing = -12580,
|
|
kProResMetadataWriterError_InvalidParameter = -12581,
|
|
kProResMetadataWriterError_AllocationFailed = -12582,
|
|
kProResMetadataWriterError_UnsupportedCommonKey = -12583,
|
|
kProResMetadataWriterError_ItemAlreadyPresent = -12585,
|
|
kProResMetadataWriterError_NoSuchProperty = -12586,
|
|
kProResMetadataWriterError_BadData = -12587,
|
|
};
|
|
|
|
/*!
|
|
@typedef ProResMetadataWriterRef
|
|
@abstract A ProResMetadataWriterRef represents metadata to be written using
|
|
ProResFileWriter.
|
|
@discussion ProResMetadataWriterRef is an abstract format-agnostic interface to
|
|
metadata to be written. The metadata can represent different metadata
|
|
formats (QT user data, etc.).
|
|
|
|
A ProResMetadataWriterRef is a PRTypeRef object and must be retained/released.
|
|
*/
|
|
typedef struct OpaqueProResMetadataWriter *ProResMetadataWriterRef;
|
|
|
|
/*!
|
|
@function ProResMetadataWriterGetFormat
|
|
@abstract Returns the format of the data represented by the metadata writer (e.g.,
|
|
QuickTime metadata vs. QuickTime user data).
|
|
*/
|
|
PR_EXPORT ProResMetadataFormat ProResMetadataWriterGetFormat(ProResMetadataWriterRef writer);
|
|
|
|
/*!
|
|
@function ProResMetadataWriterAddItem
|
|
@abstract Adds a new item to the metadata container.
|
|
|
|
Common usage:
|
|
|
|
ProResMetadataDataType valueDataType = kProResQuickTimeMetadataType32BitSignedInteger;
|
|
int32_t value = 1984;
|
|
PRIndex valueSize = sizeof(int32_t);
|
|
|
|
status = ProResMetadataWriterAddItem(writer,
|
|
kProResMetadataKeyFormatLong,
|
|
(const uint8_t *)kProResQuickTimeMetadataKey_Author,
|
|
kProResQuickTimeMetadataType32BitSignedInteger,
|
|
&value,
|
|
valueSize);
|
|
|
|
- or -
|
|
|
|
uint32_t key = kProResUserDataShortKey_Description;
|
|
ProResMetadataDataType valueDataType = kProResQuickTimeUserDataTypeUTF8;
|
|
const char* value = "foo";
|
|
PRIndex valueSize = 3;
|
|
|
|
status = ProResMetadataWriterAddItem(writer,
|
|
kProResMetadataKeyFormatShort,
|
|
(const uint8_t *)&key,
|
|
valueDataType,
|
|
value,
|
|
valueSize);
|
|
|
|
@param writer The metadata writer.
|
|
@param keyFormat The format of key.
|
|
@param key The key. If the keyFormat is kProResMetadataKeyFormatLong, the C string
|
|
must be NULL terminated.
|
|
@param value The data type of the value. Cannot be NULL.
|
|
@param valueBuffer "valueSize" bytes are copied from the valueBuffer pointer. Cannot be NULL.
|
|
valueBuffer may be freed after call.
|
|
@param valueSize The size in bytes to copy from valueBuffer. Cannot be NULL.
|
|
Do not add padding for C strings.
|
|
@param countryIndicator The country indicator, e.g., 0 (default), GB, CA, FR, DE. Can be NULL.
|
|
Only applies to QuickTime metadata.
|
|
@param languageIndicator The language indicator, e.g. 0 (default), eng, fra, deu. Can be NULL.
|
|
Only applies to QuickTime metadata.
|
|
@param languageCode The language code, e.g. 0 (English), 1 (French), 32768 (Unspecified). Can be NULL.
|
|
Only applies to QuickTime user data.
|
|
*/
|
|
PR_EXPORT PRStatus ProResMetadataWriterAddItem(ProResMetadataWriterRef writer,
|
|
const ProResMetadataKeyFormat keyFormat,
|
|
const uint8_t *key,
|
|
ProResMetadataDataType valueDataType,
|
|
void *valueBuffer,
|
|
PRIndex valueSize,
|
|
uint16_t *countryIndicator,
|
|
uint16_t *languageIndicator,
|
|
uint16_t *languageCode);
|
|
|
|
/*!
|
|
@function ProResMetadataWriterHasKey
|
|
@abstract Returns a bool value that indicates whether the given key
|
|
is currently in the container.
|
|
|
|
Common usage:
|
|
|
|
uint32_t key = kProResUserDataShortKey_CreationDate;
|
|
bool hasKey = ProResMetadataWriterHasKey(writer,
|
|
kProResMetadataKeyFormatShort,
|
|
(const uint8_t *)&key);
|
|
|
|
- or -
|
|
|
|
bool hasKey = ProResMetadataWriterHasKey(writer,
|
|
kProResMetadataKeyFormatLong,
|
|
(const uint8_t *)kProResQuickTimeMetadataKey_Author);
|
|
|
|
@param writer The metadata writer.
|
|
@param keyFormat The format of key.
|
|
@param key The key. If the keyFormat is kProResMetadataKeyFormatLong, the C string
|
|
must be NULL terminated.
|
|
*/
|
|
PR_EXPORT bool ProResMetadataWriterHasKey(ProResMetadataWriterRef writer,
|
|
const ProResMetadataKeyFormat keyFormat,
|
|
const uint8_t *key);
|
|
|
|
#pragma pack(pop)
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // PRORESMETADATAWRITER_H
|