263 lines
10 KiB
C
263 lines
10 KiB
C
//
|
|
// ProResMetadataReader.h
|
|
// Copyright (c) 2017 Apple. All rights reserved.
|
|
//
|
|
|
|
#ifndef PRORESMETADATAREADER_H
|
|
#define PRORESMETADATAREADER_H 1
|
|
|
|
#include "ProResTypes.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#pragma pack(push, 4)
|
|
|
|
/*!
|
|
@enum ProResMetadataReader Errors
|
|
@discussion Errors returned from the ProResMetadataReader APIs
|
|
|
|
@constant kProResMetadataReaderError_RequiredParameterMissing
|
|
Returned if a required parameter is missing.
|
|
@constant kProResMetadataReaderError_InvalidParameter
|
|
Returned if any of the parameters is invalid.
|
|
@constant kProResMetadataReaderError_AllocationFailed
|
|
Returned if memory allocation failed.
|
|
@constant kProResMetadataReaderError_NoSuchKey
|
|
Returned if container does not contain the given key.
|
|
@constant kProResMetadataReaderError_UnsupportedCommonKey
|
|
Returned if container does not support the given common key.
|
|
@constant kProResMetadataReaderError_NoSuchItem
|
|
Returned if container does not contain the given item.
|
|
@constant kProResMetadataReaderError_NoSuchValueType
|
|
Returned if the requested value type is not available.
|
|
@constant kProResMetadataReaderError_BadData
|
|
Returned if the container contains bad data.
|
|
@constant kProResMetadataReaderError_InsufficientData
|
|
Returned if there is insufficient data to complete the request.
|
|
@constant kProResMetadataReaderError_InsufficientKeyBufferSize
|
|
Returned if the key's buffer needs to be larger.
|
|
@constant kProResMetadataReaderError_InsufficientValueBufferSize
|
|
Returned if the value's buffer needs to be larger.
|
|
*/
|
|
enum {
|
|
kProResMetadataReaderError_RequiredParameterMissing = -12600,
|
|
kProResMetadataReaderError_InvalidParameter = -12601,
|
|
kProResMetadataReaderError_AllocationFailed = -12602,
|
|
kProResMetadataReaderError_NoSuchKey = -12604,
|
|
kProResMetadataReaderError_UnsupportedCommonKey = -12605,
|
|
kProResMetadataReaderError_NoSuchItem = -12607,
|
|
kProResMetadataReaderError_NoSuchValueType = -12608,
|
|
kProResMetadataReaderError_BadData = -12609,
|
|
kProResMetadataReaderError_InsufficientData = -12610,
|
|
kProResMetadataReaderError_NoSuchDataType = -12611,
|
|
kProResMetadataReaderError_InsufficientKeyBufferSize = -12612,
|
|
kProResMetadataReaderError_InsufficientValueBufferSize = -12613,
|
|
};
|
|
|
|
/*!
|
|
@typedef ProResMetadataReaderRef
|
|
@abstract A ProResMetadataReaderRef represents a metadata container reader.
|
|
@discussion ProResMetadataReaderRef is an abstract format-agnostic reader interface to
|
|
metadata. The metadata can represent different metadata formats (QT
|
|
user data, etc.).
|
|
|
|
A ProResMetadataReaderRef is a PRTypeRef object and must be retained/released.
|
|
*/
|
|
typedef struct OpaqueProResMetadataReader *ProResMetadataReaderRef;
|
|
|
|
/*!
|
|
@function ProResMetadataReaderGetFormat
|
|
@abstract Returns the format of the data represented by the metadata reader (e.g., QuickTime metadata
|
|
vs. QuickTime user data).
|
|
*/
|
|
PR_EXPORT ProResMetadataFormat ProResMetadataReaderGetFormat(ProResMetadataReaderRef metadataReader);
|
|
|
|
/*!
|
|
@function ProResMetadataReaderCopyValue
|
|
@abstract Copy the value of an item with the given key.
|
|
@discussion This is the simple high level API that can be used to retrieve the value
|
|
with the given key.
|
|
|
|
Common usage sample (doesn't cover all cases; only for illustrative purposes):
|
|
|
|
status = ProResMetadataReaderCopyValue(reader,
|
|
kProResMetadataKeyFormatLong,
|
|
key,
|
|
&valueDataType,
|
|
NULL,
|
|
&valueSize);
|
|
if (valueDataType == kProResQuickTimeMetadataTypeBinary) {
|
|
uint8_t *data = malloc(valueSize);
|
|
status = ProResMetadataReaderCopyValue(reader,
|
|
kProResMetadataKeyFormatLong,
|
|
key,
|
|
NULL,
|
|
data,
|
|
NULL);
|
|
}
|
|
else if (valueDataType == kProResQuickTimeMetadataTypeSignedIntegerBE
|
|
&& valueSize == 4) {
|
|
int32_t number;
|
|
status = ProResMetadataReaderCopyValue(reader,
|
|
kProResMetadataKeyFormatLong,
|
|
key,
|
|
NULL,
|
|
&number,
|
|
NULL);
|
|
}
|
|
else if (valueDataType == kProResQuickTimeMetadataTypeUTF16BE) {
|
|
valueSize += 2; // add 2 bytes for NULL character padding, otherwise
|
|
// ProResMetadataReaderCopyValue will return
|
|
// kProResMetadataReaderError_InsufficientValueBufferSize
|
|
uint8_t *utf16str = malloc(valueSize);
|
|
status = ProResMetadataReaderCopyValue(reader,
|
|
kProResMetadataKeyFormatLong,
|
|
key,
|
|
NULL,
|
|
&utf16str,
|
|
NULL);
|
|
}
|
|
else if (valueDataType == kProResQuickTimeMetadataTypeUTF8 ||
|
|
valueDataType == kProResQuickTimeMetadataTypeMacEncodedText) {
|
|
valueSize += 1; // add 1 byte for NULL character padding, otherwise
|
|
// ProResMetadataReaderCopyValue will return
|
|
// kProResMetadataReaderError_InsufficientValueBufferSize
|
|
uint8_t *string = malloc(valueSize);
|
|
status = ProResMetadataReaderCopyValue(reader,
|
|
kProResMetadataKeyFormatLong,
|
|
key,
|
|
NULL,
|
|
&string,
|
|
NULL);
|
|
}
|
|
}
|
|
|
|
@param reader The metadata reader.
|
|
@param keyFormat The format of key.
|
|
@param key The key. If the keyFormat is kProResMetadataKeyFormatLong, the C string
|
|
must be NULL terminated.
|
|
@param valueDataTypeOut The data type of the value. Can be NULL.
|
|
@param valueBuffer Copies the value to this pointer. Can be NULL.
|
|
@param valueSizeOut The size in bytes that valueBuffer's data must be. Can be NULL.
|
|
*/
|
|
PR_EXPORT PRStatus ProResMetadataReaderCopyValue(ProResMetadataReaderRef reader,
|
|
const ProResMetadataKeyFormat keyFormat,
|
|
const uint8_t *key,
|
|
ProResMetadataDataType *valueDataTypeOut,
|
|
void *valueBuffer,
|
|
PRIndex *valueSizeOut);
|
|
|
|
/*!
|
|
@function ProResMetadataReaderCopyLocale
|
|
@abstract Copy the locale information of an item with the given key.
|
|
This is only applicable to QuickTime metadata, _not_ user data.
|
|
@discussion If status != 0, this information is unavailable or not applicable.
|
|
@param countryIndicatorOut The country indicator, e.g., 0 (default), GB, CA, FR, DE.
|
|
@param languageIndicatorOut The language indicator, e.g. 0 (default), eng, fra, deu.
|
|
*/
|
|
PR_EXPORT PRStatus ProResMetadataReaderCopyLocale(ProResMetadataReaderRef reader,
|
|
const uint8_t *key,
|
|
uint16_t *countryIndicatorOut,
|
|
uint16_t *languageIndicatorOut);
|
|
|
|
/*!
|
|
@function ProResMetadataReaderCopyLanguageCode
|
|
@abstract Copy the language code of an item with the given key.
|
|
This is only applicable to QuickTime user data, _not_ metadata.
|
|
@discussion If status != 0, this information is unavailable or not applicable.
|
|
*/
|
|
PR_EXPORT PRStatus ProResMetadataReaderCopyLanguageCode(ProResMetadataReaderRef reader,
|
|
const uint8_t *key,
|
|
uint16_t *languageCode);
|
|
|
|
/*!
|
|
@function ProResMetadataReaderHasKey
|
|
@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 = ProResMetadataReaderHasKey(reader,
|
|
kProResMetadataKeyFormatShort,
|
|
(const uint8_t *)&key);
|
|
|
|
- or -
|
|
|
|
bool hasKey = ProResMetadataReaderHasKey(reader,
|
|
kProResMetadataKeyFormatLong,
|
|
(const uint8_t *)kProResQuickTimeMetadataKey_Author);
|
|
|
|
@param reader The metadata reader.
|
|
@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 ProResMetadataReaderHasKey(ProResMetadataReaderRef reader,
|
|
const ProResMetadataKeyFormat keyFormat,
|
|
const uint8_t *key);
|
|
|
|
/*!
|
|
@function ProResMetadataReaderGetKeyCount
|
|
@abstract Returns the total number of all keys in the container.
|
|
|
|
@param reader The metadata reader.
|
|
*/
|
|
PR_EXPORT PRIndex ProResMetadataReaderGetKeyCount(ProResMetadataReaderRef reader);
|
|
|
|
/*!
|
|
@function ProResMetadataReaderCopyKeyAtIndex
|
|
@abstract Returns the key at the given key index.
|
|
|
|
Common usage:
|
|
|
|
PRIndex keyCount = ProResMetadataReaderGetKeyCount(metadataReader);
|
|
for (PRIndex ii = 0; ii < keyCount && status == 0; ii++) {
|
|
ProResMetadataKeyFormat keyFormat;
|
|
PRIndex keySize;
|
|
status = ProResMetadataReaderCopyKeyAtIndex(metadataReader,
|
|
ii,
|
|
&keyFormat,
|
|
NULL,
|
|
&keySize);
|
|
if (status == 0) {
|
|
if (keyFormat == kProResMetadataKeyFormatLong)
|
|
keySize += 1; // add a byte for the NULL character
|
|
uint8_t *key = malloc(keySize);
|
|
status = ProResMetadataReaderCopyKeyAtIndex(metadataReader,
|
|
ii,
|
|
NULL,
|
|
key,
|
|
NULL);
|
|
if (status == 0) {
|
|
// use ProResMetadatareaderCopyValue sample code above.
|
|
}
|
|
}
|
|
}
|
|
|
|
@param reader The metadata reader.
|
|
@param keyIndex The position of the key in the key list.
|
|
@param keyFormatOut keyOut's format (short or long). Can be NULL.
|
|
@param keyBuffer Copies the key to this pointer. Can be NULL.
|
|
@param keySizeOut The size in bytes that keyBuffer's data must be. Can be NULL.
|
|
If the keyFormat is kProResMetadataKeyFormatShort, this will be 4.
|
|
If the keyFormat is kProResMetadataKeyFormatLong, this will be the
|
|
equivalent of calling strlen(key); the keySize does not reflect
|
|
the trailing NULL character of the C string (see above).
|
|
*/
|
|
PR_EXPORT PRStatus ProResMetadataReaderCopyKeyAtIndex(ProResMetadataReaderRef reader,
|
|
PRIndex keyIndex,
|
|
ProResMetadataKeyFormat *keyFormatOut,
|
|
uint8_t *keyBuffer,
|
|
PRIndex *keySizeOut);
|
|
|
|
#pragma pack(pop)
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // PRORESMETADATAREADER_H
|