콘텐츠로 이동
무료 평가 시작

PDComm.HsmsEndpoint

클래스

TCP/IP로 SECS-II 메시지를 주고받는 동기식 HSMS(SEMI E37) 끝점입니다.

public sealed class HsmsEndpoint : IDisposable

끝점은 스레드와 콜백을 만들지 않으며, 코드가 직접 구동합니다. HsmsEndpoint.Start를 호출한 다음, 타이머와 소켓 I/O를 진행하도록 HsmsEndpoint.Poll을, 상태 변경·수신 메시지·실패를 읽도록 HsmsEndpoint.NextEvent를 반복해서 호출합니다. 액티브 끝점은 스스로 연결하고 Select.req를 보냅니다. 패시브 끝점은 HsmsEndpoint.Create에서 수신 소켓을 바인딩합니다. 미리 만들어진 폴링 루프를 사용하려면 HsmsWorker를 사용합니다.

모든 메서드는 내부 잠금을 사용하므로 여러 스레드의 호출이 직렬화됩니다. 연결 시도 중에는 HsmsEndpoint.Poll이 최대 HsmsOptions.ConnectTimeoutMilliseconds 동안 잠금을 보유할 수 있습니다.

끝점은 네이티브 핸들을 소유합니다. 정상적으로 닫으려면 HsmsEndpoint.Stop을 호출하고, HsmsState.Closed가 true가 될 때까지 폴링과 이벤트 읽기를 계속한 다음 HsmsEndpoint.Dispose를 호출합니다. 그 전에 해제하면 정상적인 전송 종료 절차 없이 리소스가 해제됩니다. HsmsEndpoint.NextEvent가 반환한 이벤트는 자체 데이터를 소유하므로 끝점을 해제한 뒤에도 유효합니다.

HsmsEndpoint.Request 같은 메서드의 성공은 메시지가 큐에 들어갔다는 뜻일 뿐이며, 결과는 나중에 같은 HsmsToken을 가진 이벤트로 도착합니다.

PdcommRuntime.Initialize(libraryPath);
using var endpoint = HsmsEndpoint.Create("127.0.0.1:5000", options); // options.Mode == HsmsMode.Active
endpoint.Start();
HsmsToken request = default;
while (true)
{
    endpoint.Poll();
    if (request == default && endpoint.GetState().State == HsmsConnectionState.Selected)
    {
        request = endpoint.Request(1, 1, true, ReadOnlySpan<byte>.Empty); // S1F1 W
    }
    using HsmsEvent? next = endpoint.NextEvent();
    if (next?.GetInfo() is { Kind: HsmsEventKind.Received, IsReply: true } info && info.Token == request)
    {
        Console.WriteLine($"S{info.Header!.Value.Stream}F{info.Header.Value.Function}, {info.BodyLength} bytes");
        break;
    }
}

멤버

Cancel

메서드

이 끝점의 열린 거래를 취소합니다.

public bool Cancel(HsmsToken token)

취소된 요청은 HsmsFailureReason.Cancelled 실패 이벤트로 완료됩니다. 일부만 쓰인 메시지를 취소하면 연결이 닫힐 수 있으며, 이미 전송된 바이트는 회수되지 않습니다.

매개변수

이름설명
token거래를 시작할 때 반환된 토큰입니다.

반환값

거래가 열려 있었고 이제 취소되었으면 true이고, 그렇지 않으면 false입니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 네이티브 호출이 실패했습니다.

Create

메서드

HSMS 끝점을 만듭니다.

public static HsmsEndpoint Create(string numericAddress, HsmsOptions options)

매개변수

이름설명
numericAddress127.0.0.1:5000 또는 [::1]:5000 같은 숫자 IPv4 또는 IPv6 소켓 주소입니다. 호스트 이름은 확인하지 않습니다. 액티브 끝점은 이 주소로 연결하고, 패시브 끝점은 이 주소에서 수신 대기합니다(포트 0이면 빈 포트를 선택하며, HsmsEndpoint.GetLocalAddress를 참고합니다).
options끝점의 역할, 세션, 타이머, 한도입니다.

반환값

호출자가 소유하며 해제해야 하는 새 끝점입니다.

참고

  • ArgumentNullException 예외: numericAddress 또는 options가 null입니다.
  • EncoderFallbackException 예외: numericAddress에 짝이 맞지 않는 서로게이트가 있습니다.
  • PdcommException 예외: 주소가 숫자 소켓 주소가 아니거나 옵션이 0이거나 잘못되었거나(PdcommStatus.InvalidArgument), 한도가 서로 맞지 않거나(PdcommStatus.LimitExceeded), 패시브 끝점이 소켓을 바인딩할 수 없었습니다(PdcommStatus.IoError).

Deselect

메서드

연결을 닫지 않고 선택된 HSMS 세션을 끝내는 Deselect.req를 보냅니다.

public HsmsToken Deselect()

반환값

제어 거래의 토큰입니다. 결과는 이벤트로 도착합니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 세션이 선택되지 않았거나(PdcommStatus.InvalidState), Deselect가 이미 대기 중입니다(PdcommStatus.Backpressure).

Dispose

메서드

네이티브 끝점을 해제하고 소켓을 닫습니다.

public void Dispose()

해제는 정상적인 HSMS 종료를 수행하지 않습니다. 정상 종료하려면 먼저 HsmsEndpoint.Stop을 호출하고 이벤트를 모두 비웁니다. 끝점에서 이미 가져온 이벤트는 계속 유효합니다. 이 메서드를 여러 번 호출해도 효과가 없습니다.

GetLocalAddress

메서드

로컬 소켓 주소를 가져옵니다. 예를 들어 패시브 끝점이 실제로 수신 대기하는 포트를 알 수 있습니다.

public string GetLocalAddress()

반환값

127.0.0.1:50123 같은 숫자 로컬 소켓 주소입니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 열린 소켓이 없습니다. 예를 들어 연결 전의 액티브 끝점입니다(PdcommStatus.IoError).

GetState

메서드

끝점의 연결 상태를 가져옵니다.

public HsmsState GetState()

반환값

끝점 상태의 스냅샷입니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 네이티브 호출이 실패했습니다.

IsPending

메서드

이 끝점의 거래가 아직 열려 있는지 확인합니다.

public bool IsPending(HsmsToken token)

매개변수

이름설명
token거래를 시작할 때 반환된 토큰입니다.

반환값

거래가 아직 완료되지 않았으면 true이고, 그렇지 않으면 false입니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 네이티브 호출이 실패했습니다.

Linktest

메서드

연결이 살아 있는지 확인하는 Linktest.req를 보냅니다.

public HsmsToken Linktest()

반환값

제어 거래의 토큰입니다. T6 안의 실패는 HsmsEventKind.Failed 이벤트로 도착합니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 열린 연결이 없거나(PdcommStatus.InvalidState), Linktest가 이미 대기 중입니다(PdcommStatus.Backpressure).

NextEvent

메서드

큐에 있는 다음 이벤트를 가져옵니다.

public HsmsEvent? NextEvent()

큐가 비어 있다고 세션이 끝났다는 뜻은 아닙니다. 계속 폴링해야 합니다.

반환값

호출자가 소유하며 해제해야 하는 다음 이벤트이거나, 큐에 이벤트가 없으면 null입니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 이벤트를 할당할 수 없었거나(PdcommStatus.AllocationFailed이며, 이벤트가 큐에 남아 있으므로 다시 시도), 끝점이 오염되었습니다.

Poll

메서드

타이머, 연결 처리, 소켓 I/O를 진행합니다.

public nuint Poll()

연결 시도 중에는 최대 HsmsOptions.ConnectTimeoutMilliseconds 동안 차단될 수 있습니다.

반환값

수행한 내부 동작의 수이며 최대 HsmsOptions.PollBudget입니다. 생성된 이벤트의 수가 아니며, 0이라고 해서 세션이 끝났다는 뜻은 아닙니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 이벤트 큐가 가득 찼거나(PdcommStatus.Backpressure이며, 먼저 HsmsEndpoint.NextEvent로 이벤트를 읽어야 함) 끝점이 실패했습니다.

Reply

메서드

수신한 1차 메시지에 대한 응답을 큐에 넣습니다.

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

매개변수

이름설명
primary응답을 기대하는 수신 1차 메시지 이벤트입니다.
stream응답의 스트림 번호이며, 보통 1차 메시지의 스트림입니다.
function응답의 펑션 번호이며, 보통 1차 메시지의 펑션에 1을 더한 값입니다. 중단하려면 0입니다.
replyExpected응답에 W 비트를 설정할지 여부입니다. 보통 false입니다.
body인코딩된 완전한 SECS-II 아이템 하나이거나, 헤더만 있는 응답이면 빈 범위입니다.

참고

  • ArgumentNullException 예외: primary가 null입니다.
  • ObjectDisposedException 예외: 끝점 또는 primary가 해제되었습니다.
  • PdcommException 예외: primary가 다른 끝점이나 연결에 속하거나(PdcommStatus.StaleToken), 이미 응답했거나 응답을 기대하는 1차 메시지가 아니거나(PdcommStatus.InvalidArgument), 본문이 프레임 한도나 아이템 한도를 넘거나(PdcommStatus.LimitExceeded), 응답을 큐에 넣을 수 없습니다.

Request

메서드

1차 데이터 메시지를 큐에 넣습니다.

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

본문은 복사됩니다. 성공은 메시지가 큐에 들어갔다는 뜻입니다. replyExpected가 true이면 반환된 토큰을 가진 HsmsEventKind.Received 응답 또는 HsmsEventKind.Failed 이벤트가 거래를 완료합니다. 그렇지 않으면 HsmsEventKind.W0Written 이벤트가 로컬 쓰기를 보고합니다.

매개변수

이름설명
streamSECS-II 스트림 번호(0~127)입니다.
functionSECS-II 펑션 번호입니다. 1차 메시지는 홀수를 사용합니다.
replyExpectedW 비트를 설정하고 T3 안에 응답을 기다릴지 여부입니다.
body인코딩된 완전한 SECS-II 아이템 하나이거나, 헤더만 있는 메시지이면 빈 범위입니다.

반환값

이후 이벤트에서 거래를 식별하는 토큰입니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 세션이 선택되지 않았거나(PdcommStatus.InvalidState), 큐에 들어간 거래나 바이트가 너무 많거나(PdcommStatus.Backpressure), 본문이 프레임 한도나 아이템 한도를 초과하거나(PdcommStatus.LimitExceeded), 본문이 유효한 SECS-II 아이템이 아닙니다.

Select

메서드

HSMS 세션을 선택하는 Select.req를 보냅니다.

public HsmsToken Select()

액티브 끝점은 연결 후 자동으로 선택합니다. 다시 선택하려면 이 메서드를 사용합니다.

반환값

제어 거래의 토큰입니다. 결과는 이벤트로 도착합니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 연결이 HsmsConnectionState.NotSelected 상태가 아니거나(PdcommStatus.InvalidState), Select가 이미 대기 중입니다(PdcommStatus.Backpressure).

Start

메서드

연결(액티브) 또는 수신 대기(패시브)를 시작합니다.

public void Start()

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 현재 상태에서는 끝점을 시작할 수 없습니다.

Stop

메서드

연결의 정상 종료를 시작합니다.

public void Stop()

HsmsEndpoint.GetState가 HsmsState.Closed를 보고할 때까지 HsmsEndpoint.Poll과 HsmsEndpoint.NextEvent를 계속 호출합니다. 종료는 HsmsOptions.ShutdownTimeoutMilliseconds로 제한됩니다.

참고

  • ObjectDisposedException 예외: 끝점이 해제되었습니다.
  • PdcommException 예외: 현재 상태에서는 끝점을 중지할 수 없습니다.

개인정보 처리방침