Class: Winlog::Provider

Inherits:
Object
  • Object
show all
Defined in:
lib/winlog.rb,
ext/winlog/winlog.cpp

Overview

Native (TypedData) provider class; the C side defines the bridges and the read-only methods. The Ruby layer here adds the validated, ergonomic API.

Instance Method Summary collapse

Constructor Details

#initialize(name) ⇒ Provider

Same contract as Winlog.open (no block form here; open delegates to new). Raises ArgumentError on a bad name; never raises on EventRegister failure (see #registered?).



166
167
168
169
 
# File 'lib/winlog.rb', line 166

def initialize(name)
  @name = Winlog.send(:validate_name!, name).dup.freeze
  _register(@name)
end

Instance Method Details

#close ⇒ Object

Provider#close -> nil. Idempotent (E20). Unregister + free the native provider now; safe to call again, on a never-registered object, etc.



716
717
718
719
720
721
722
723
724
725
726
 
# File 'ext/winlog/winlog.cpp', line 716

static VALUE
provider_close(VALUE self)
{
    provider_t *pt = provider_get(self);
    if (pt->prov) {
        delete pt->prov;     /* tld dtor: EventUnregister + HeapFree metadata */
        pt->prov = NULL;
    }
    pt->closed = 1;
    return Qnil;
}

#closed? ⇒ Boolean

Provider#closed? -> true/false.

Returns:

  • (Boolean) 


729
730
731
732
733
734
 
# File 'ext/winlog/winlog.cpp', line 729

static VALUE
provider_closed_p(VALUE self)
{
    provider_t *pt = provider_get(self);
    return (pt->prov == NULL || pt->closed) ? Qtrue : Qfalse;
}

#enabled?(level: nil, keyword: 0) ⇒ Boolean

Is any ETW session listening (with the given level/keyword filter)? Reads in-process enable state — no system call. Raises Winlog::Closed after close.

level:   nil (default; "any level") | Symbol in LEVELS | Integer 1..255
keyword: Integer 0..0x0000_FFFF_FFFF_FFFF (reserved bits raise)

Returns:

  • (Boolean) 


200
201
202
203
 
# File 'lib/winlog.rb', line 200

def enabled?(level: nil, keyword: 0)
  lvl = level.nil? ? nil : Winlog.level_for(level)
  _enabled(lvl, keyword)
end

#guid ⇒ Object

Provider#guid -> 36-char lowercase hyphenated String (from tld Provider::Id, authoritative; equals Winlog.guid_for(name)). Set before Init runs, untouched by registration failure (E11). Raises Winlog::Closed after close.



691
692
693
694
695
696
 
# File 'ext/winlog/winlog.cpp', line 691

static VALUE
provider_guid(VALUE self)
{
    provider_t *pt = provider_live(self);
    return guid_to_rb(pt->prov->Id());
}

#inspect ⇒ Object

Never raises, even closed.



206
207
208
209
210
211
212
 
# File 'lib/winlog.rb', line 206

def inspect
  if closed?
    "#<Winlog::Provider (closed)>"
  else
    "#<Winlog::Provider #{@name} {#{guid}}>"
  end
end

#log(level, event, **fields) ⇒ Object

Emit one TraceLogging event. THE call of the gem.

level  : Symbol in LEVELS, or Integer 1..255.
event  : event name (Symbol or String; valid UTF-8, non-empty, no NUL).
fields : keyword splat of field-name => value pairs, plus the reserved
       control kwargs keyword:/opcode:/activity:/related: (extracted by
       exact Symbol key; String keys with the same text stay fields).

Returns true if enabled and written, false if skipped/dropped. Never raises on delivery problems (ETW is lossy by design). Raises Winlog::Closed after close. Field-value type errors raise only when the event is enabled (the deliberate E2 asymmetry; control args validate on every call).



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/winlog.rb', line 183

def log(level, event, **fields)
  # Map opcode symbol -> integer here (Ruby owns the OPCODES table) without
  # disturbing the String-key escape hatch: only a :opcode Symbol key is a
  # control arg, and only when its value is a Symbol does it need mapping.
  if fields.key?(:opcode) && fields[:opcode].is_a?(Symbol)
    fields = fields.dup
    fields[:opcode] = Winlog.opcode_for(fields[:opcode])
  end
  _log(Winlog.level_for(level), event, fields)
end

#name ⇒ Object

The provider name as given (frozen UTF-8 String). Stored at initialize and never read back from provider metadata (tld swaps in empty NullMetadata on a failed registration). Correct regardless of registration outcome.

Raises:



157
158
159
160
161
 
# File 'lib/winlog.rb', line 157

def name
  raise Winlog::Closed, "winlog: provider is closed" if closed?

  @name
end

#registered? ⇒ Boolean

Provider#registered? -> true if EventRegister succeeded (E11).

Returns:

  • (Boolean) 


699
700
701
702
703
704
 
# File 'ext/winlog/winlog.cpp', line 699

static VALUE
provider_registered_p(VALUE self)
{
    provider_t *pt = provider_live(self);
    return SUCCEEDED(pt->prov->InitializationResult()) ? Qtrue : Qfalse;
}

#registration_result ⇒ Object

Provider#registration_result -> raw HRESULT Integer; 0 on success.



707
708
709
710
711
712
 
# File 'ext/winlog/winlog.cpp', line 707

static VALUE
provider_registration_result(VALUE self)
{
    provider_t *pt = provider_live(self);
    return INT2NUM((int)pt->prov->InitializationResult());
}