Class DiagnosticReporter

Namespace

Egami

Assembly

Egami.dll

One call's link to Diagnostics, with the same level filter and per-id cap Egami's own readers and writers use. Get one from StartDiagnostics() at the start of a call (format plug-ins use Diagnostics) and dispose it when the call ends. When the context has no handler it is a shared instance that does nothing, so reporting costs one check.

public sealed class DiagnosticReporter : IDisposable

Inheritance

object

DiagnosticReporter

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// A decoder outside Egami (a video demuxer, a format plug-in's own entry point) reports through the same handler, with the
// same level filter and the same cap of 10 per id per call. Dispose the reporter when the call ends.
using (DiagnosticReporter diagnostics = context.StartDiagnostics())
{
    if (diagnostics.IsEnabled(DiagnosticLevel.Warning))
    {
        diagnostics.Report(DiagnosticLevel.Warning, "Avi.IndexRebuilt", "The index was missing; it was rebuilt from the frames.", offset: 4096);
    }

    diagnostics.Report(DiagnosticLevel.Info, "Mjpeg.DhtInserted", "Frames have no Huffman tables; the standard ones were used.");
}

Remarks

Each id is delivered at most 10 times per reporter; disposing sends one more event per capped id that counts the rest. Report(DiagnosticLevel, string, string, long?, int?) may be called from several threads at once.

Methods

Dispose()

Ends the call: sends one event for each capped id, counting the events left out.

public void Dispose()

IsEnabled(DiagnosticLevel)

Gets whether events at level are delivered. Check it before building an expensive message.

public bool IsEnabled(DiagnosticLevel level)

Parameters

level DiagnosticLevel

The level of the event about to be reported.

Returns

bool

true if a handler is set and level is at or above the context's level.

Report(DiagnosticLevel, string, string, long?, int?)

Reports an event, unless its level is below the context's or its id has already been delivered 10 times.

public void Report(DiagnosticLevel level, string id, string message, long? offset = null, int? frame = null)

Parameters

level DiagnosticLevel

How much the event matters.

id string

A stable id of the form Source.Name, such as "Video.FrameDropped".

message string

What happened and what was done, as a sentence.

offset long?

The byte offset in the input the event is about, if known.

frame int?

The frame or page index the event is about, if known.

Exceptions

ArgumentException

id is not of the form Source.Name, or message is empty.

Report(EgamiDiagnostic)

Reports an event built elsewhere, unless its level is below the context's or its id is past the cap.

public void Report(EgamiDiagnostic diagnostic)

Parameters

diagnostic EgamiDiagnostic

The event.

Exceptions

ArgumentException

The event's id or message is empty.