SalObject

Namespace: PPJ.Runtime.Com

Assembly: PPJ.Runtime.50 (5.0.0.0)

Wraps an automation object and manages its interfaces, enumeration, and COM error state.

C#

public class SalObject : SalFunctionalClass, IDisposable

VB.NET

Public Class SalObject
    Inherits SalFunctionalClass
    Implements IDisposable

Assigning Value attaches the object and detaches the previous value. Dispose the wrapper when its attached object is no longer needed.

Example:

using PPJ.Runtime.Com;

using (var automation = new SalObject())
{
    if (automation.CreateObject("Scripting.Dictionary"))
        System.Console.WriteLine(automation.IsDispatchValid());
}

Constructors

SalObject()

Initializes a wrapper without an attached object.

SalObject(obj)

Initializes a wrapper and attaches the supplied object.

Name	Type	Description
obj	Object	The wrapper or automation object involved in the attachment.

Properties

AutoErrorMode

Boolean: Gets or sets whether HandleException propagates automation exceptions instead of recording them.

AutoRelease

Boolean: Gets or sets whether detaching also releases the attached COM object automatically.

Value

Object: Gets or sets the attached automation object, updating reflected interface fields and enabling automatic release.

Methods

Attach(obj)

Assigns this wrapper's object to another wrapper.

Parameter	Type	Description
obj	SalObject	The destination wrapper that receives this Value.

Returns: Boolean. True if assignment succeeds; false for a null destination or a handled COM error.

The destination argument receives this Value; this wrapper remains attached.

AttachInterface(com)

Assigns an automation object to the wrapper's reflected interface fields.

Parameter	Type	Description
com	Object	The object assigned to the reflected interface fields.

An incompatible field type is reported as InvalidCastException.

Count()

Reads the attached collection's public Count property through reflection.

Returns: SalNumber. The element count, or zero if no enumerator or property value is available.

CreateObject()

Creates and attaches an instance of the COM class declared by the wrapper's _CoClass field.

Returns: Boolean. True if creation and attachment succeed; false if the field is absent or creation fails.

CreateObject(progid)

Creates and attaches the COM class identified by a ProgID or CLSID.

Parameter	Type	Description
progid	String	The registered programmatic identifier or CLSID string.

Returns: Boolean. True if creation and attachment succeed; otherwise, false.

CreateObjectEx(host)

Creates the wrapper's declared COM class on the specified host.

Parameter	Type	Description
host	String	The host on which to activate the COM class.

Returns: Boolean. True if the _CoClass field exists and creation succeeds; otherwise, false.

CreateObjectEx(progid, host)

Creates the specified COM class on a host and assigns the wrapper's _CoClass field.

Parameter	Type	Description
progid	String	The registered programmatic identifier or CLSID string.
host	String	The host on which to activate the COM class.

Returns: Boolean. True if the _CoClass field exists and creation succeeds; otherwise, false.

Detach()

Releases tracked interfaces and detaches the current object.

Returns: Boolean. True after detachment completes.

Clears the attached object and cached enumerator even if release fails.

Dispose()

Detaches this wrapper once and releases its tracked COM references.

Finalize()

Destructor.

GetInterface(iface, iid)

Queries the attached object for an interface and assigns it to another wrapper.

Parameter	Type	Description
iface	SalObject	The destination wrapper that receives the queried interface.
iid	String	The requested interface GUID, or an empty value to assign the current object.

Returns: Boolean. True if the interface is assigned; otherwise, false.

An empty interface identifier assigns the current object without querying a specific interface.

GetLastError(err)

Copies details of the most recently handled exception into an error record.

Parameter	Type	Description
err	SalOleErrorInfo	The error record to populate.

Returns: SalBoolean. True if a stored exception is available; otherwise, false.

Only available exception fields are assigned; existing fields in the record are not cleared.

HandleException(e)

Traces an automation exception and either stores or rethrows it.

Parameter	Type	Description
e	Exception	The exception to record or propagate.

Returns: Boolean. False when automatic error propagation is disabled.

With AutoErrorMode enabled, a COMException is thrown directly; otherwise its InnerException is thrown. With automatic errors disabled, the original exception is stored for GetLastError.

IsCollection()

Determines whether an enumerator can be obtained for the attached object.

Returns: SalBoolean. True if an enumerator is available; otherwise, false.

IsDispatchValid()

Tests whether an object is currently attached.

Returns: Boolean. True if Value is non-null; otherwise, false.

This checks only for a non-null reference, not COM server availability.

MTSDisableCommit()

Marks the current COM+ context as unable to commit its transaction.

MTSEnableCommit()

Allows the current COM+ context to commit its transaction.

MTSIsCallerInRole(role)

Tests the immediate caller's membership in a COM+ role.

Parameter	Type	Description
role	SalString	The COM+ security role name.

Returns: SalBoolean. True if the caller belongs to the role; otherwise, false.

MTSIsInTransaction()

Tests whether the current COM+ context participates in a transaction.

Returns: Boolean. True if the context participates in a transaction; otherwise, false.

MTSIsSecurityEnabled()

Tests whether COM+ role-based security is enabled in the current context.

Returns: Boolean. True if security is enabled; otherwise, false.

MTSSetAbort()

Votes to abort the current COM+ transaction and marks the object as complete.

MTSSetComplete()

Votes to commit the current COM+ transaction and marks the object as complete.

Next(obj)

Advances the cached enumerator and attaches its current item to the supplied wrapper.

Parameter	Type	Description
obj	SalObject	The destination wrapper for the next collection item.

Returns: SalBoolean. True if another item is available; otherwise, false.

Reset()

Resets the cached enumerator to its initial position.

Returns: SalBoolean. True after reset; false if enumeration is unavailable.

Skip(nElems)

Advances the cached enumerator by the requested number of elements.

Parameter	Type	Description
nElems	SalNumber	The number of enumeration steps to perform; nonpositive values perform no steps.

Returns: SalBoolean. True if all requested advances succeed; false if enumeration is unavailable or ends early.