PDComm.GemEndpoint

Class

Provides the members shared by GemHost and GemEquipment: a synchronous SEMI E30 (GEM) endpoint layered on one HSMS (SEMI E37) TCP connection.

public abstract class GemEndpoint : IDisposable

The endpoint has no internal thread. The application calls GemEndpoint.Start, then repeatedly calls GemEndpoint.Poll, drains GemEndpoint.NextEvent, and passes every event to GemEndpoint.HandleEvent in queue order so that GEM state, automatic replies and pending requests stay consistent. To run the endpoint on a dedicated polling thread instead, use GemHostWorker or GemEquipmentWorker.

All calls are serialized by an internal lock, so the endpoint can be called from several threads, but calls do not run concurrently. GemEndpoint.Poll can block for up to HsmsOptions.ConnectTimeoutMilliseconds during an active connection attempt.

For a graceful shutdown, call GemEndpoint.Stop, keep polling and draining events until GemEndpoint.GetTransportState reports a closed state, then call GemEndpoint.Dispose. Events and results that were already returned own their data and stay valid after the endpoint is disposed.

Members

`BeginCommunication`

Method

Sends S1F13 (Establish Communications Request) to start GEM communication.

public HsmsToken BeginCommunication()

Allowed only in GemCommunicationState.NotCommunicating; the state then becomes GemCommunicationState.WaitingAck. A host sends an empty list body; equipment sends its model (MDLN) and software revision (SOFTREV).

Returns

The token of the request; the S1F14 reply arrives as a GemResult with this token.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The request was not sent: PdcommStatus.InvalidState in another communication state, or PdcommStatus.Backpressure when all 32 pending request slots are in use or a retained transport event must be read first.

`Cancel`

Method

Cancels a pending transaction.

public bool Cancel(HsmsToken token)

A canceled GEM request completes later as a GemResultKind.Failed result whose code is HsmsFailureReason.Cancelled.

Parameters

Name	Description
`token`	The token returned when the request was submitted.

Returns

true when the transaction was pending and is now canceled.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native call failed.

`Deselect`

Method

Sends an HSMS Deselect.req control message.

public HsmsToken Deselect()

Returns

The token that identifies the control transaction in later events.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The transport could not accept the request.

`Dispose`

Method

Releases the native endpoint without a graceful wire shutdown.

public void Dispose()

Events and results that were already returned remain valid.

`GetLocalAddress`

Method

Gets the numeric local socket address, for example the bound address of a passive endpoint.

public string GetLocalAddress()

Returns

The local address as IP:port text.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native call failed.
Throws InvalidOperationException: The native address size changed during the read.

`GetState`

Method

Gets a snapshot of the GEM state.

public GemState GetState()

Returns

The current GEM state.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native call failed.

`GetTransportState`

Method

Gets the HSMS connection state of the underlying transport.

public HsmsState GetTransportState()

Returns

The current transport state.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native call failed.

`HandleEvent`

Method

Processes one transport event with the GEM layer.

public GemResult HandleEvent(HsmsEvent tcpEvent)

GEM updates its state, sends automatic replies, and matches replies and failures to pending GEM requests. Events that are not GEM traffic produce a GemResultKind.Ignored result. Each event can be handled once; the event stays readable afterward and can be disposed independently of the result.

The result owns a snapshot of its data and stays valid after the event and the endpoint are disposed.

Parameters

Name	Description
`tcpEvent`	An event returned by `GemEndpoint.NextEvent` of this endpoint.

Returns

A new GemResult that the caller owns and must dispose. Inspect it with GemResult.GetInfo.

Notes

Throws ArgumentNullException: tcpEvent is null.
Throws ObjectDisposedException: The endpoint or tcpEvent was disposed.
Throws PdcommException: The event could not be handled: PdcommStatus.StaleToken when it was already handled or belongs to another endpoint or an older connection; PdcommStatus.AllocationFailed or PdcommStatus.Backpressure leave the event retryable.

`IsPending`

Method

Gets whether a transaction is still waiting for its reply.

public bool IsPending(HsmsToken token)

Parameters

Name	Description
`token`	The token returned when the request was submitted.

Returns

true when the transaction is pending.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native call failed.

`Linktest`

Method

Sends an HSMS Linktest.req control message.

public HsmsToken Linktest()

Returns

The token that identifies the control transaction in later events.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The transport could not accept the request.

`NextEvent`

Method

Removes the next transport event from the endpoint queue.

public HsmsEvent? NextEvent()

Pass every returned event to GemEndpoint.HandleEvent before handling the next one. An empty queue does not mean the session is finished.

Returns

The next event, or null when the queue is empty. The caller owns and must dispose it.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native call failed, for example PdcommStatus.AllocationFailed; the event is kept and returned by the next call.

`Poll`

Method

Performs pending transport work such as connecting, reading, writing and timer checks.

public nuint Poll()

Can block for up to HsmsOptions.ConnectTimeoutMilliseconds during an active connection attempt. See HsmsEndpoint.Poll.

Returns

The number of internal actions performed; this is not the number of events produced.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native transport failed, for example with PdcommStatus.Backpressure.

`ReplyRaw`

Method

Sends a raw SECS-II reply to a received primary message.

public void ReplyRaw(HsmsEvent primary, byte stream, byte function, bool replyExpected, ReadOnlySpan<byte> body)

Use this method to answer a primary that GEM reported as GemResultKind.Unhandled.

Parameters

Name	Description
`primary`	The received primary event to answer.
`stream`	The SECS-II stream number of the reply.
`function`	The SECS-II function number of the reply, or 0 to abort the transaction.
`replyExpected`	Whether the reply sets the reply-expected (W) bit; replies normally do not.
`body`	One complete encoded SECS-II item, or an empty span for a header-only reply.

Notes

Throws ArgumentNullException: primary is null.
Throws ObjectDisposedException: The endpoint or primary was disposed.
Throws PdcommException: The transport rejected the reply, for example PdcommStatus.StaleToken when the primary was already answered or belongs to an older connection.

`RequestRaw`

Method

Sends a raw SECS-II primary message that GEM does not track.

public HsmsToken RequestRaw(byte stream, byte function, bool replyExpected, ReadOnlySpan<byte> body)

The body is copied before the method returns. Success means the transport accepted the message, not that a reply arrived. The reply is reported as a GemResultKind.Ignored result by GemEndpoint.HandleEvent; read it from the HsmsEvent.

Parameters

Name	Description
`stream`	The SECS-II stream number.
`function`	The SECS-II function number; primary messages use odd numbers.
`replyExpected`	Whether the message sets the reply-expected (W) bit.
`body`	One complete encoded SECS-II item, or an empty span for a header-only message.

Returns

The token that identifies the transaction in later events.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The transport could not accept the message, for example because a limit was exceeded.

`Select`

Method

Sends an HSMS Select.req control message.

public HsmsToken Select()

Returns

The token that identifies the control transaction in later events.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The transport could not accept the request.

`Start`

Method

Starts the HSMS transport: an active endpoint starts connecting and a passive endpoint starts listening.

public void Start()

See HsmsEndpoint.Start.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native transport rejected the call.

`Stop`

Method

Starts closing the HSMS transport; keep polling and draining events until the state reports closed.

public void Stop()

See HsmsEndpoint.Stop.

Notes

Throws ObjectDisposedException: The endpoint was disposed.
Throws PdcommException: The native transport rejected the call.

`FormattedPrograms`

Property

Gets the formatted process program services of this endpoint.

public GemFormattedPrograms FormattedPrograms { get; }

Every access creates a new lightweight object. It holds no native resources and needs no disposal; its methods take the same internal lock as the other endpoint methods.

Returns

A new GemFormattedPrograms object that operates on this endpoint.

Notes

Throws NotSupportedException: The loaded native library does not export the formatted process program functions.