Class ExternalBindingHandle

Namespace

RDCore.SDK.Model.Values.Bindings

Assembly

RDCore.SDK.dll

A handle to a binding to a member whose code is not the workspace's — a standard-library member, a referenced library's, a host application's object model, or a native export a Declare named.

public record ExternalBindingHandle : ICallableBinding, IBindingHandle, IEquatable<ExternalBindingHandle>

Inheritance

object

ExternalBindingHandle

Implements

ICallableBinding

IBindingHandle

IEquatable<ExternalBindingHandle>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The sibling of CallableBindingHandle, and deliberately the same shape: the handle says which member and, for a member of a class, which object; something else runs it. The only difference is which engine that is — an IProcedureInvoker for code the workspace declares, an IExternalDispatcher for everything else.

Like its sibling it only ever supports Invoke. A property of a host's object model is an accessor that can validate, have side effects and raise errors just as a workspace property can, so no value-slot shortcut may bypass it; reading Err.Number is an invocation made with no arguments. Value is never supported, because it reads without a resolver and an invocation needs one.

Constructors

ExternalBindingHandle(VBTypeMemberSymbol, IExternalDispatcher, IRuntimeValue?, SourceLocation)

A handle to a binding to a member whose code is not the workspace's — a standard-library member, a referenced library's, a host application's object model, or a native export a Declare named.

public ExternalBindingHandle(VBTypeMemberSymbol Member, IExternalDispatcher Dispatcher, IRuntimeValue? Receiver = null, SourceLocation CallSite = default)

Parameters

Member VBTypeMemberSymbol

The external member this handle invokes.

Dispatcher IExternalDispatcher

The engine that reaches whatever really implements Member.

Receiver IRuntimeValue

The object a member of a class is bound to, null for a member of a module. It is passed as the argument at index 0, the same as the Me of a workspace member — an external object is an opaque handle, so this travels as a reference to something the provider owns rather than as anything marshalled.

CallSite SourceLocation

Where the call is written, for an error that would otherwise have no location.

Remarks

The sibling of CallableBindingHandle, and deliberately the same shape: the handle says which member and, for a member of a class, which object; something else runs it. The only difference is which engine that is — an IProcedureInvoker for code the workspace declares, an IExternalDispatcher for everything else.

Like its sibling it only ever supports Invoke. A property of a host's object model is an accessor that can validate, have side effects and raise errors just as a workspace property can, so no value-slot shortcut may bypass it; reading Err.Number is an invocation made with no arguments. Value is never supported, because it reads without a resolver and an invocation needs one.

Properties

BindingCapabilities

Indicates the valid members of this binding.

public BindingCapabilities BindingCapabilities { get; }

Property Value

BindingCapabilities

CallSite

Where the call is written, for an error that would otherwise have no location.

public SourceLocation CallSite { get; init; }

Property Value

SourceLocation

Dispatcher

The engine that reaches whatever really implements Member.

public IExternalDispatcher Dispatcher { get; init; }

Property Value

IExternalDispatcher

Member

The external member this handle invokes.

public VBTypeMemberSymbol Member { get; init; }

Property Value

VBTypeMemberSymbol

Receiver

The object a member of a class is bound to, null for a member of a module. It is passed as the argument at index 0, the same as the Me of a workspace member — an external object is an opaque handle, so this travels as a reference to something the provider owns rather than as anything marshalled.

public IRuntimeValue? Receiver { get; init; }

Property Value

IRuntimeValue

Value

The bound runtime value, read without a resolver.

public IRuntimeValue Value { get; }

Property Value

IRuntimeValue

Remarks

👉 A direct read for the common literal/value cases. Handles that resolve a value lazily or via a reference still expose GetValue(ISymbolResolver).

Exceptions

NotSupportedException

The binding has no readable value.

NotSupportedException

Always: an invocation needs a resolver.

Methods

Call(ISymbolResolver, IRuntimeValue[])

Invokes the member and returns the outcome as a result, the way the semantics of the language do: an error it raised, that nothing handled, is in the result rather than thrown.

public RuntimeSemanticsEvaluationResult Call(ISymbolResolver resolver, IRuntimeValue[] args)

Parameters

resolver ISymbolResolver

A read-only interface over the current execution context.

args IRuntimeValue[]

The arguments of the call, without the receiver, which the handle passes itself.

Returns

RuntimeSemanticsEvaluationResult

GetValue(ISymbolResolver)

Gets the value associated to this handle, resolving through resolver when the binding is not self-contained.

public IRuntimeValue GetValue(ISymbolResolver resolver)

Parameters

resolver ISymbolResolver

Returns

IRuntimeValue

Remarks

👉 Verify that the binding supports GetValue.

Exceptions

NotSupportedException

NotSupportedException

Always: an external member is reached by invoking it.

Invoke(ISymbolResolver, IRuntimeValue[])

Invokes the callable entity associated to this handle, and returns the runtime value it yields - an HRESULT (S_OK), for one that yields no value.

public IRuntimeValue Invoke(ISymbolResolver resolver, IRuntimeValue[] args)

Parameters

resolver ISymbolResolver

args IRuntimeValue[]

Returns

IRuntimeValue

Remarks

👉 Verify that the binding supports Invoke.
A handle to code that runs on a call stack does not push the frame itself: it hands the call to an IProcedureInvoker.

Exceptions

NotSupportedException

The binding does not support Invoke.

VBRuntimeErrorException

A run-time error was raised by the invoked entity and nothing handled it.

VBRuntimeErrorException

The member raised a run-time error and nothing handled it. A caller that handles the errors of the program, or wants the typed value, uses Call(ISymbolResolver, IRuntimeValue[]), which returns them instead.

SetValue(ISymbolResolver, IRuntimeValue)

Sets the value associated to this handle.

public void SetValue(ISymbolResolver resolver, IRuntimeValue value)

Parameters

resolver ISymbolResolver

value IRuntimeValue

Remarks

👉 Verify that the binding supports SetValue.

Exceptions

NotSupportedException

NotSupportedException

Always: an external member is reached by invoking it.