/// <summary>
/// Create a new <see cref="Enumerator"/> instance.
/// </summary>
/// <param name="ARef">The <see cref="Unsafe.AVDictionary"/>.</param>
/// <param name="AFlags">The <see cref="AVDictFlags"/>.</param>
public Enumerator(Ref <Unsafe.AVDictionary> ARef, AVDictFlags AFlags = AVDictFlags.NONE)
{
FRef = ARef;
FFlags = AFlags;
Reset();
}
public static Ref <Unsafe.AVDictionaryEntry> Get(
Ref <Unsafe.AVDictionary> ARef,
[NotNull] string AKey,
Ref <Unsafe.AVDictionaryEntry> APrev = default,
AVDictFlags AFlags = AVDictFlags.NONE
)
{
const AVDictFlags C_ProhibitedFlags =
AVDictFlags.AV_DICT_DONT_STRDUP_KEY;
// No null-check necessary.
Debug.Assert(
AKey != null,
"Key is null.",
"The key for a set operation may not be null. This indicates a severe logic " +
"error in the code."
);
Debug.Assert(
(AFlags & C_ProhibitedFlags) != AVDictFlags.NONE,
"Flag is prohibited.",
"Some provided flag (DONT_STRDUP_KEY) is invalid on marshalled strings and " +
"therefore prohibited. This indicates a logic error in the code."
);
// Strip the prohibited flags at all cost.
AFlags &= ~C_ProhibitedFlags;
return(Unsafe.ffmpeg.av_dict_get(ARef, AKey, APrev, (int)AFlags));
}
/// <summary>
/// Create a new <see cref="Dictionary"/> instance.
/// </summary>
/// <param name="ARef">The <see cref="Unsafe.AVDictionary"/>.</param>
/// <param name="AFlags">The <see cref="AVDictFlags"/>.</param>
internal Dictionary(Ref <Unsafe.AVDictionary> ARef, AVDictFlags AFlags)
{
Ref = ARef;
Flags = AFlags;
Keys = new KeyCollection(this);
Values = new ValueCollection(this);
}
/// <summary>
/// Parse a string into a dictionary.
/// </summary>
/// <param name="ARef">The <see cref="Unsafe.AVDictionary"/>.</param>
/// <param name="ABuffer">The string to parse.</param>
/// <param name="AKeyValSep">The key-value separator list.</param>
/// <param name="APairsSep">The pairs separator list.</param>
/// <param name="AFlags">The <see cref="AVDictFlags"/>.</param>
/// <exception cref="FFmpegError">Error parsing string.</exception>
/// <remarks>
/// If the parse operation fails, the <paramref name="ARef"/> might still be changed and
/// may also have been allocated. The caller must cleanup after an error if that is not
/// intended.
/// </remarks>
public static void ParseString(
ref Ref <Unsafe.AVDictionary> ARef,
[CanBeNull] string ABuffer,
[NotNull] string AKeyValSep,
[NotNull] string APairsSep,
AVDictFlags AFlags = AVDictFlags.NONE
)
{
const char C_Null = '\0';
const char C_Slash = '\\';
const char C_Max = '\x7F';
// No null-check necessary.
Debug.Assert(
AKeyValSep != null,
"Key-value separator list is null.",
"The separator list may not be null. This indicates a severe logic error in the " +
"code."
);
Debug.Assert(
!AKeyValSep.Any(X => X == C_Null || X == C_Slash || X > C_Max),
"Key-value separator contains invalid chars.",
"The slash and zero terminator character are reserved and may not be used " +
"for any separator. All chars must be ANSI. This indicates a contract violation."
);
Debug.Assert(
APairsSep != null,
"Pairs separator list is null.",
"The separator list may not be null. This indicates a severe logic error in the " +
"code."
);
Debug.Assert(
!APairsSep.Any(X => X == C_Null || X == C_Slash || X > C_Max),
"Pairs separator contains invalid chars.",
"The slash and zero terminator character are reserved and may not be used " +
"for any separator. All chars must be ANSI. This indicates a contract violation."
);
var ptr = ARef.Ptr;
var error = Unsafe.ffmpeg.av_dict_parse_string(
&ptr,
ABuffer,
AKeyValSep,
APairsSep,
(int)AFlags
).CheckFFmpeg("Error parsing string.");
ARef = ptr;
// Postponed throw to make reference modification visible to caller at all costs.
error.ThrowIfPresent();
}
/// <summary>
/// Copy pairs from one dictionary into another.
/// </summary>
/// <param name="ADst">The destination <see cref="Unsafe.AVDictionary"/>.</param>
/// <param name="ASrc">The source <see cref="Unsafe.AVDictionary"/>.</param>
/// <param name="AFlags">The <see cref="AVDictFlags"/>.</param>
/// <exception cref="FFmpegError">Error copying values.</exception>
/// <remarks>
/// If the copy operation fails, the <paramref name="ADst"/> might still be changed and
/// may also have been allocated. The caller must cleanup after an error if that is not
/// intended.
/// </remarks>
public static void Copy(
ref Ref <Unsafe.AVDictionary> ADst,
Ref <Unsafe.AVDictionary> ASrc,
AVDictFlags AFlags = AVDictFlags.NONE
)
{
// No null-check necessary.
var ptr = ADst.Ptr;
var error = Unsafe.ffmpeg.av_dict_copy(&ptr, ASrc, (int)AFlags)
.CheckFFmpeg("Error copying values.");
ADst = ptr;
// Postponed throw to make reference modification visible to caller at all costs.
error.ThrowIfPresent();
}
/// <summary>
/// Set a value in the dictionary.
/// </summary>
/// <param name="ARef">The <see cref="Unsafe.AVDictionary"/>.</param>
/// <param name="AKey">The key string.</param>
/// <param name="AValue">The value string.</param>
/// <param name="AFlags">The <see cref="AVDictFlags"/>.</param>
/// <exception cref="FFmpegError">Error setting value.</exception>
public static void Set(
ref Ref <Unsafe.AVDictionary> ARef,
[NotNull] string AKey,
[CanBeNull] string AValue,
AVDictFlags AFlags = AVDictFlags.NONE
)
{
const AVDictFlags C_ProhibitedFlags =
AVDictFlags.AV_DICT_DONT_STRDUP_KEY
| AVDictFlags.AV_DICT_DONT_STRDUP_VAL;
// No null-check necessary.
Debug.Assert(
AKey != null,
"Key is null.",
"The key for a set operation may not be null. This indicates a severe logic " +
"error in the code."
);
Debug.Assert(
(AFlags & C_ProhibitedFlags) != AVDictFlags.NONE,
"Flag is prohibited.",
"Some provided flags (DONT_STRDUP family) are invalid on marshalled strings and " +
"therefore prohibited. This indicates a logic error in the code."
);
// Strip the prohibited flags at all cost.
AFlags &= ~C_ProhibitedFlags;
var ptr = ARef.Ptr;
var error = Unsafe.ffmpeg.av_dict_set(&ptr, AKey, AValue, (int)AFlags)
.CheckFFmpeg("Error setting value.");
ARef = ptr;
// Postponed throw to make reference modification visible to caller at all costs.
error.ThrowIfPresent();
}